From 44ca0b19a64e2ad9d591a62bd156790e5761cb8e Mon Sep 17 00:00:00 2001 From: aaron Date: Mon, 26 Oct 2015 23:42:56 -0500 Subject: [PATCH 01/11] Added clib interface file; populated ctypes --- docs/scenarios/clibs.rst | 42 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/scenarios/clibs.rst diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst new file mode 100644 index 0000000..b3d80be --- /dev/null +++ b/docs/scenarios/clibs.rst @@ -0,0 +1,42 @@ +Interfacing with C/C++ Libraries +================================ + + +ctypes +------ + +`ctypes `_ is the de facto +library for interfacing with C/C++, and it provides not only full access to +the native C interface of most major operating systems (e.g., kernel32 on +Windows, or libc on *nix), but also provides support for loading and +interfacing with dynamic libraries, such as DLLs or shared objects at runtime. +It does bring along with it a whole host of types for interacting with system +APIs, and allows you to rather easily define your own complex types, such +as structs and unions, and allows you to modify things such as padding and +alignment, if needed. It can be a bit crufty to use, but in conjunction with +the `struct `_ module, you +are essentially provided full control over how your data types get translated +into something something usable by a C(++). + +Struct Equivalents +~~~~~~~~~~~~~~~~~~ + +:file:`MyStruct.h` + +.. code-block:: c + :linenos: + + struct my_struct { + int a; + int b; + }; + +:file:`MyStruct.py` + +.. code-block:: python + :linenos: + + import ctypes + class my_struct(ctypes.Structure): + _fields_ = [("a", c_int), + ("b", c_int)] From 2dea4bc5eecd603ac6332d45eb711078a0fbf767 Mon Sep 17 00:00:00 2001 From: aaron Date: Mon, 26 Oct 2015 23:45:11 -0500 Subject: [PATCH 02/11] Added sections for SWIG and boost.python --- docs/scenarios/clibs.rst | 64 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index b3d80be..f2e75d3 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -40,3 +40,67 @@ Struct Equivalents class my_struct(ctypes.Structure): _fields_ = [("a", c_int), ("b", c_int)] + +SWIG +---- + +`SWIG `_, though not strictly Python focused (it supports a +large number of scripting languages), is a tool for generating bindings for +interpreted languages from C/C++ header files. It is extremely simple to use: +the consumer simply needs to define an interface file (detailed in the +tutorial and documentations), include the requisite C/C++ headers, and run +the build tool against them. While it does have some limits, (it currently +seems to have issues with a small subset of newer C++ features, and getting +template-heavy code to work can be a bit verbose), it provides a great deal +of power and exposes lots of features to Python with little effort. +Additionally, you can easily extend the bindings SWIG creates (in the +interface file) to overload operators and built-in methods, effectively re- +cast C++ exceptions to be catchable by Python, etc. + +Example: Overloading __repr__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:file:`MyClass.h` + +.. code-block:: c++ + :linenos: + + #include + class MyClass { + private: + std::string name; + public: + std::string getName(); + }; + +:file:`myclass.i` + +.. code-block:: c++ + :linenos: + + %include "string.i" + + %module myclass + %{ + #include + #include "MyClass.h" + %} + + %extend MyClass { + std::string __repr__() + { + return $self->getName(); + } + } + + %include "MyClass.h" + + +Boost.Python +------------ + +`Boost.Python `_ +requires a bit more manual work to expose C++ object functionality, but +it is capable of providing all the same features SWIG does, and then some, +to include providing wrappers to access PyObjects in C++, extracting SWIG- +wrapper objects, and even embedding bits of Python into your C++ code. From b1b5f95cdf20f0f912088dc1a824912c80a2d66f Mon Sep 17 00:00:00 2001 From: aaron Date: Mon, 26 Oct 2015 23:46:19 -0500 Subject: [PATCH 03/11] Added new file to list of scenarios --- docs/contents.rst.inc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index b312ee3..17cf003 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -62,6 +62,7 @@ different scenarios. scenarios/xml scenarios/json scenarios/crypto + scenarios/clibs Shipping Great Code From 599200c023b59fbe86a364ff4d450b1113426563 Mon Sep 17 00:00:00 2001 From: aaron Date: Mon, 26 Oct 2015 23:52:03 -0500 Subject: [PATCH 04/11] Edited for typos --- docs/scenarios/clibs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index f2e75d3..5d20fa4 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -16,7 +16,7 @@ as structs and unions, and allows you to modify things such as padding and alignment, if needed. It can be a bit crufty to use, but in conjunction with the `struct `_ module, you are essentially provided full control over how your data types get translated -into something something usable by a C(++). +into something usable by a pure C(++) method. Struct Equivalents ~~~~~~~~~~~~~~~~~~ @@ -101,6 +101,6 @@ Boost.Python `Boost.Python `_ requires a bit more manual work to expose C++ object functionality, but -it is capable of providing all the same features SWIG does, and then some, +it is capable of providing all the same features SWIG does and then some, to include providing wrappers to access PyObjects in C++, extracting SWIG- wrapper objects, and even embedding bits of Python into your C++ code. From 7d0139a2483bdd68811de8669daac07e9fd8d125 Mon Sep 17 00:00:00 2001 From: aaron Date: Sun, 1 Nov 2015 08:41:27 -0600 Subject: [PATCH 05/11] Modified ctypes entry for clarity --- docs/scenarios/clibs.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index 5d20fa4..3f92627 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -5,18 +5,18 @@ Interfacing with C/C++ Libraries ctypes ------ -`ctypes `_ is the de facto -library for interfacing with C/C++, and it provides not only full access to -the native C interface of most major operating systems (e.g., kernel32 on -Windows, or libc on *nix), but also provides support for loading and -interfacing with dynamic libraries, such as DLLs or shared objects at runtime. -It does bring along with it a whole host of types for interacting with system -APIs, and allows you to rather easily define your own complex types, such -as structs and unions, and allows you to modify things such as padding and -alignment, if needed. It can be a bit crufty to use, but in conjunction with -the `struct `_ module, you -are essentially provided full control over how your data types get translated -into something usable by a pure C(++) method. +`ctypes `_ is the CPython +included library for interfacing with C/C++, and it provides not only full +access to the native C interface of most major operating systems (e.g., +kernel32 on Windows, or libc on *nix), but also provides support for loading +and interfacing with dynamic libraries, such as DLLs or shared objects at +runtime. It does bring along with it a whole host of types for interacting +with system APIs, and allows you to rather easily define your own complex +types, such as structs and unions, and allows you to modify things such as +padding and alignment, if needed. It can be a bit crufty to use, but in +conjunction with the `struct `_ +module, you are essentially provided full control over how your data types get +translated into something something usable by a C(++). Struct Equivalents ~~~~~~~~~~~~~~~~~~ From fc092a1a98bec97de52ba671aa177069a513fa38 Mon Sep 17 00:00:00 2001 From: aaron Date: Sun, 1 Nov 2015 11:40:05 -0600 Subject: [PATCH 06/11] Added CFFI section --- docs/scenarios/clibs.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index 3f92627..c4d4110 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -1,6 +1,29 @@ Interfacing with C/C++ Libraries ================================ +C Foreign Function Interface +---------------------------- + +`CFFI `_ provides a simple to use +mechanism for interfacing with C from both CPython and PyPy. It supports two +modes: an inline ABI compatibility mode (example provided below), which allows +you to dynamically load and run functions from executable modules (essentially +exposing the same functionality as LoadLibrary or dlopen), and an API mode, +which allows you to build C extension modules. + +ABI Interaction +~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + from cffi import FFI + ffi = FFI() + ffi.cdef("size_t strlen(const char*);") + clib = ffi.dlopen(None) + length = clib.strlen("String to be evaluated.") + # prints: 23 + print("{}".format(length)) ctypes ------ From 3f0508403e12dcae6e7eb7a995957ca0f1f1c0a2 Mon Sep 17 00:00:00 2001 From: aaron Date: Sun, 1 Nov 2015 13:33:47 -0600 Subject: [PATCH 07/11] Fixed a formatting issue introduced in ctypes --- docs/scenarios/clibs.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst index c4d4110..290638e 100644 --- a/docs/scenarios/clibs.rst +++ b/docs/scenarios/clibs.rst @@ -28,10 +28,10 @@ ABI Interaction ctypes ------ -`ctypes `_ is the CPython -included library for interfacing with C/C++, and it provides not only full -access to the native C interface of most major operating systems (e.g., -kernel32 on Windows, or libc on *nix), but also provides support for loading +`ctypes `_ is the de facto +library for interfacing with C/C++ from CPython, and it provides not only +full access to the native C interface of most major operating systems (e.g., +kernel32 on Windows, or libc on \*nix), but also provides support for loading and interfacing with dynamic libraries, such as DLLs or shared objects at runtime. It does bring along with it a whole host of types for interacting with system APIs, and allows you to rather easily define your own complex @@ -39,7 +39,7 @@ types, such as structs and unions, and allows you to modify things such as padding and alignment, if needed. It can be a bit crufty to use, but in conjunction with the `struct `_ module, you are essentially provided full control over how your data types get -translated into something something usable by a C(++). +translated into something something usable by a pure C(++) method. Struct Equivalents ~~~~~~~~~~~~~~~~~~ From 6e4eb1f9a659a1875e6582fdd9bb5341ebaa5f14 Mon Sep 17 00:00:00 2001 From: Thomas Levine <_@thomaslevine.com> Date: Wed, 4 Nov 2015 20:00:59 -0500 Subject: [PATCH 08/11] use .content in lxml This can also be thought of as a bug in lxml. It just occurred to me that maybe I should fix that. --- docs/scenarios/scrape.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/scrape.rst b/docs/scenarios/scrape.rst index 65560d3..0728d25 100644 --- a/docs/scenarios/scrape.rst +++ b/docs/scenarios/scrape.rst @@ -38,7 +38,10 @@ parse it using the ``html`` module and save the results in ``tree``: .. code-block:: python page = requests.get('http://econpy.pythonanywhere.com/ex/001.html') - tree = html.fromstring(page.text) + tree = html.fromstring(page.content) + +(We need to use ``page.content`` rather than ``page.text`` because +``html.fromstring`` implicitly expects ``bytes`` as input.) ``tree`` now contains the whole HTML file in a nice tree structure which we can go over two different ways: XPath and CSSSelect. In this example, we From baf4158b138dd5fb9c38a80c7a525b0d604b601e Mon Sep 17 00:00:00 2001 From: Britta Gustafson Date: Tue, 17 Nov 2015 15:48:52 -0800 Subject: [PATCH 09/11] Link to internal Virtual Environments page from install pages --- docs/dev/virtualenvs.rst | 2 ++ docs/starting/install/linux.rst | 2 +- docs/starting/install/osx.rst | 2 +- docs/starting/install/win.rst | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 266faeb..bb3f948 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -1,3 +1,5 @@ +.. _virtualenvironments-ref: + Virtual Environments ==================== diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index a42106d..e68c5d0 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -58,7 +58,7 @@ your global site-packages directory clean and manageable. For example, you can work on a project which requires Django 1.3 while also maintaining a project which requires Django 1.0. -To start using and see more information: `Virtual Environments `_ docs. +To start using this and see more information: :ref:`Virtual Environments ` docs. You can also use :ref:`virtualenvwrapper ` to make it easier to manage your virtual environments. diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 0de724f..cb0062c 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -92,7 +92,7 @@ your global site-packages directory clean and manageable. For example, you can work on a project which requires Django 1.3 while also maintaining a project which requires Django 1.0. -To start using and see more information: `Virtual Environments `_ docs. +To start using this and see more information: :ref:`Virtual Environments ` docs. -------------------------------- diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index a0f37c5..140c842 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -77,7 +77,7 @@ your global site-packages directory clean and manageable. For example, you can work on a project which requires Django 1.3 while also maintaining a project which requires Django 1.0. -To start using and see more information: `Virtual Environments `_ docs. +To start using this and see more information: :ref:`Virtual Environments ` docs. -------------------------------- From 560391d0ce331a47b8498a1a3d57adeaeee269fc Mon Sep 17 00:00:00 2001 From: Britta Date: Thu, 19 Nov 2015 14:40:01 -0800 Subject: [PATCH 10/11] Updating "Gittip" to "Gratipay" in text and links Gittip changed its name to Gratipay more than a year ago. --- docs/_templates/sidebarintro.html | 4 ++-- docs/_templates/sidebarlogo.html | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 65ca51e..8a958d9 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -10,11 +10,11 @@

Donate

- If you enjoy this guide, consider supporting the author on Gittip: + If you enjoy this guide, consider supporting the author on Gratipay:

diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index 67650e8..cfe41fc 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -10,10 +10,10 @@

Donate

- If you enjoy this guide, consider supporting the author on Gittip: + If you enjoy this guide, consider supporting the author on Gratipay:

-

\ No newline at end of file +

From 8ad4ec2816dcbe2e990530c1239a026a72669d2e Mon Sep 17 00:00:00 2001 From: Britta Date: Thu, 19 Nov 2015 15:21:09 -0800 Subject: [PATCH 11/11] Removing Gratipay donation widget --- docs/_templates/sidebarintro.html | 10 ---------- docs/_templates/sidebarlogo.html | 10 ---------- 2 files changed, 20 deletions(-) diff --git a/docs/_templates/sidebarintro.html b/docs/_templates/sidebarintro.html index 8a958d9..883572b 100644 --- a/docs/_templates/sidebarintro.html +++ b/docs/_templates/sidebarintro.html @@ -8,16 +8,6 @@

Subscribe to Newsletter

-

Donate

-

- If you enjoy this guide, consider supporting the author on Gratipay: -

-

- -

-

Contributors

This guide is the result of the collaboration of diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html index cfe41fc..6372b3f 100644 --- a/docs/_templates/sidebarlogo.html +++ b/docs/_templates/sidebarlogo.html @@ -7,13 +7,3 @@

Receive updates on new releases and upcoming projects.

Subscribe to Newsletter

- -

Donate

-

- If you enjoy this guide, consider supporting the author on Gratipay: -

-

- -