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.