From 44ca0b19a64e2ad9d591a62bd156790e5761cb8e Mon Sep 17 00:00:00 2001 From: aaron Date: Mon, 26 Oct 2015 23:42:56 -0500 Subject: [PATCH 1/7] 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 000000000..b3d80bead --- /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 2/7] 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 b3d80bead..f2e75d3ef 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 3/7] 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 b312ee3e6..17cf00346 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 4/7] 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 f2e75d3ef..5d20fa481 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 5/7] 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 5d20fa481..3f92627d5 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 6/7] 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 3f92627d5..c4d4110d7 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 7/7] 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 c4d4110d7..290638e73 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 ~~~~~~~~~~~~~~~~~~