Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Aaron/add clib doc #636

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 1, 2015
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions 1 docs/contents.rst.inc
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ different scenarios.
scenarios/xml
scenarios/json
scenarios/crypto
scenarios/clibs


Shipping Great Code
Expand Down
129 changes: 129 additions & 0 deletions 129 docs/scenarios/clibs.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
Interfacing with C/C++ Libraries
================================

C Foreign Function Interface
----------------------------

`CFFI <https://cffi.readthedocs.org/en/latest/>`_ 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
------

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should mention that ctypes is only available on CPython and only works there. It is not supported by PyPy or any other implementation that I'm aware of.

`ctypes <https://docs.python.org/3/library/ctypes.html>`_ 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
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 <https://docs.python.org/3.5/library/struct.html>`_
module, you are essentially provided full control over how your data types get
translated into something something usable by a pure C(++) method.

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)]

SWIG
----

`SWIG <http://www.swig.org>`_, 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 <string>
class MyClass {
private:
std::string name;
public:
std::string getName();
};

:file:`myclass.i`

.. code-block:: c++
:linenos:

%include "string.i"

%module myclass
%{
#include <string>
#include "MyClass.h"
%}

%extend MyClass {
std::string __repr__()
{
return $self->getName();
}
}

%include "MyClass.h"


Boost.Python
------------

`Boost.Python <http://www.boost.org/doc/libs/1_59_0/libs/python/doc/>`_
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.
Morty Proxy This is a proxified and sanitized view of the page, visit original site.