.. -*- Mode: rst -*-
.. include:: ../etc/definitions.rst
3. Case 1 - DBo Derived, Standalone
======================================
As example, we take ``Library``. This a ``DBo`` derived class, but we
choose not to export the parent classes. From Python, it will appear
as a base class.
.. _3.1:
.. _3.1 Class Associated Header File:
3.1 Class Associated Header File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is the typical content of a header file (for ``PyLibrary``):
.. code-block:: c++
#ifndef PY_LIBRARY_H
#define PY_LIBRARY_H
#include "hurricane/isobar/PyHurricane.h"
#include "hurricane/Library.h"
namespace Isobar {
using namespace Hurricane;
extern "C" {
typedef struct {
PyObject_HEAD
Library* _object;
} PyLibrary;
extern PyTypeObject PyTypeLibrary;
extern PyMethodDef PyLibrary_Methods[];
extern PyObject* PyLibrary_Link ( Hurricane::Library* lib );
extern void PyLibrary_LinkPyType ();
#define IsPyLibrary(v) ( (v)->ob_type == &PyTypeLibrary )
#define PYLIBRARY(v) ( (PyLibrary*)(v) )
#define PYLIBRARY_O(v) ( PYLIBRARY(v)->_object )
} // extern "C".
} // Isobar namespace.
#endif // PY_LIBRARY_H
The code is organized as follow:
1. It must have, *as the first include* ``PyHurricane.h``, which provides
the complete bunch of macros needed to build the module. Then the include
of the C++ class we want to wrap (``Library.h``).
2. As Python is written in C, all the wrapper code has to be but inside
an ``extern "C"`` namespace.
3. Definition of the wrapped |struct|, ``PyLibrary``. It is standard Python here.
.. note::
For our set of macros to work, the name of the pointer to the
C++ class must always be **_object**, and the various functions and
macros defined here must take the name of the class (either in
lowercase, camel case or capitals).
4. Declaration of the Python type ``PyTypeLibrary`` (standard).
5. Declaration of the Python type table of methods ``PyLibrary_Methods`` (standard).
.. _3.6:
6. Declaration of ``PyLibrary_Link()``, helper to convert a C++ ``Lybrary`` into
a ``PyLibrary`` (put in the support shared library).
7. Declaration of ``PyLibrary_LinkPyType()``, this function setup the class-level
function of the new Python type (here, ``PyTypeLibrary``).
8. And, lastly, three macros to:
* ``IsPylibrary()``, know if a Python object is a ``PyLibrary``
* ``PYLIBRARY()``, force cast (C style) of a ``PyObject`` into a ``PyLibrary``.
* ``PYLIBRARY_O()``, extract the C++ object (``Library*``) from the Python
object (``PyLibrary``).
.. _3.2 Class Associated File:
3.2 Class Associated File
~~~~~~~~~~~~~~~~~~~~~~~~~~~
3.2.1 Head of the file
------------------------
.. code-block:: c++
#include "hurricane/isobar/PyLibrary.h"
#include "hurricane/isobar/PyDataBase.h"
#include "hurricane/isobar/PyCell.h"
namespace Isobar {
using namespace Hurricane;
extern "C" {
#define METHOD_HEAD(function) GENERIC_METHOD_HEAD(Library,lib,function)
As for the header, all the code must be put inside a ``extern "C"`` namespace.
A convenience macro ``METHOD_HEAD()`` must be defined, by refining
``GENERIC_METHOD_HEAD()``. This macro will be used in the method wrappers
below to cast the ``_object`` field of the Python object into the
appropriate C++ class, this is done using a C-style cast.
The parameters of that macro are:
#. The C++ encapsulated class (``Library``).
#. The name of the *variable* that will be used to store a pointer
to the C++ working object.
#. The name of the C++ method which is to be wrapped.
3.2.2 The Python Module Part
------------------------------
First, we have to build all the wrappers to the C++ methods of
the class. For common predicates, accessors, and mutators macros
are supplied.
Wrapping of the ``Library::getCell()`` method:
.. code-block:: c++
static PyObject* PyLibrary_getCell ( PyLibrary* self, PyObject* args )
{
Cell* cell = NULL;
HTRY
METHOD_HEAD( "Library.getCell()" )
char* name = NULL;
if (PyArg_ParseTuple(args,"s:Library.getCell", &name)) {
cell = lib->getCell( Name(name) );
} else {
PyErr_SetString( ConstructorError
, "invalid number of parameters for Library::getCell." );
return NULL;
}
HCATCH
return PyCell_Link(cell);
}
Key points about this method wrapper:
#. The ``HTRY`` / ``HCATCH`` macros provides an insulation from the C++
exceptions. If one is emitted, it will be catched and transformed in
a Python one. This way, the Python program will be cleanly interrupted
and the usual stack trace displayed.
#. The returned value of this method is of type ``Cell*``, we have to
transform it into a Python one. This is done with ``PyCell_Link()``.
This macro is supplied by the ``PyCell.h`` header and this is why
it must be included.
|newpage|
Wrapping of the ``Library::create()`` method:
.. code-block:: c++
static PyObject* PyLibrary_create( PyObject*, PyObject* args )
{
PyObject* arg0;
PyObject* arg1;
Library* library = NULL;
HTRY
__cs.init( "Library.create" ); // Step (1).
if (not PyArg_ParseTuple( args, "O&O&:Library.create"
, Converter, &arg0
, Converter, &arg1 )) { // Step (2).
PyErr_SetString( ConstructorError
, "invalid number of parameters for Library constructor." );
return NULL;
}
if (__cs.getObjectIds() == ":db:string") { // Step (3.a)
DataBase* db = PYDATABASE_O(arg0);
library = Library::create( db, Name(PyString_AsString(arg1)) );
} else if (__cs.getObjectIds() == ":library:string") { // Step (3.b)
Library* masterLibrary = PYLIBRARY_O(arg0);
library = Library::create( masterLibrary, Name(PyString_AsString(arg1)) );
} else {
PyErr_SetString( ConstructorError
, "invalid number of parameters for Library constructor." );
return NULL;
}
HCATCH
return PyLibrary_Link( library );
}
Key point about this constructor:
#. We want the Python interface to mimic as closely as possible the
C++ API. As such, Python object will be created using a static
``.create()`` method. So we do not use the usual Python allocation
mechanism.
#. As it is a *static* method, there is no first argument.
#. Python do not allow function overload like C++. To emulate that
behavior we use the ``__cs`` object (which is a global variable).
#. Init/reset the ``__cs`` object: see *step (1)*.
#. Call ``PyArg_ParseTuple()``, read every mandatory or optional
argument as a Python object (``"O&"``) and use ``Converter``
on each one. ``Converter`` will determine the real type of
the Python object given as argument by looking at the
encapsulated C++ class. It then update the ``__cs`` object.
Done in *step (2)*
#. After the call to ``PyArg_ParseTuple()``, the function
``__cs.getObjectIds()`` will return the *signature* of
the various arguments. In our case, the valid signatures
will be ``":db:string"`` (*step (3.a)*a) and ``":library:string"``
(*step (3.b)*).
#. Call the C++ method after extracting the C++ objects from
the Python arguments. Note the use of the ``PYLIBRARY_O()``
and ``PYDATABSE_O()`` macros to perform the conversion.
#. Return the result, encapsulated through a call to ``PyLibrary_Link()``.
|newpage|
Wrapping of the ``Library::destroy()`` method:
.. code-block:: c++
DBoDestroyAttribute(PyLibrary_destroy, PyLibrary)
For C++ classes **that are derived** from ``DBo``, the destroy method
wrapper must be defined using the macro ``DBoDestroyAttribute()``.
This macro implements the bi-directional communication mechanism
using ``Hurricane::Property``. It **must not** be used for
non ``DBo`` derived classes.
Defining the method table of the PyLibrary type:
.. code-block:: c++
PyMethodDef PyLibrary_Methods[] =
{ { "create" , (PyCFunction)PyLibrary_create , METH_VARARGS|METH_STATIC
, "Creates a new library." }
, { "getCell" , (PyCFunction)PyLibrary_getCell, METH_VARARGS
, "Get the cell of name <name>" }
, { "destroy" , (PyCFunction)PyLibrary_destroy, METH_NOARGS
, "Destroy associated hurricane object The python object remains." }
, {NULL, NULL, 0, NULL} /* sentinel */
};
This is standard Python/C API. The name of the ``PyMethodDef`` table must be
named from the class: ``PyLibrary_Methods``.
3.2.3 Python Type Linking
---------------------------
Defining the ``PyTypeLibrary`` class methods and the type linking function.
Those are the functions for the Python object itself to work, not the
wrapped method from the C++ class.
.. note::
At this point we **do not** define the ``PyTypeLibrary`` itself.
Only it's functions and a function to set them up *once* the
type will be defined.
.. code-block:: c++
DBoDeleteMethod(Library)
PyTypeObjectLinkPyType(Library)
The macro ``DBoDeleteMethod()`` define the function to delete a
``PyLibrary`` *Python* object. Again, do not mistake it for the deletion
of the C++ class (implemented by ``DBoDestroyAttribute()``).
Here again, ``DBoDeleteMethod()`` is specially tailored for
``DBo`` derived classes.
.. _PyLibrary_LinkPyType():
To define ``PyLibrary_LinkPyType()``, use the ``PyTypeObjectLinkPyType()``
macro. This macro is specific for ``DBo`` derived classes that are seen as
base classes under Python (i.e. we don't bother exposing the base
class under Python). ``PyLibrary_LinkPyType()`` setup the class functions
in the ``PyTypeLibrary`` type object, it **must** be called in the
Python module this class is part of (in this case: ``PyHurricane.cpp``).
This particular flavor of the macro *will define* and setup the
following class functions:
* ``PyTypeLibrary.tp_compare`` (defined by the macro).
* ``PyTypeLibrary.tp_repr`` (defined by the macro).
* ``PyTypeLibrary.tp_str`` (defined by the macro).
* ``PyTypeLibrary.tp_hash`` (defined by the macro).
* ``PyTypeLibrary.tp_methods`` sets to the previously defined ``PyLibrary_Methods`` table.
* ``PyTypeLibrary.tp_dealloc`` is set to a function that *must* be named ``PyLibrary_DeAlloc``,
this is what ``DBoDeleteMethod`` does. It is *not* done by ``PyTypeObjectLinkPyType``.
Defining the ``PyTypeLibrary`` type:
3.2.4 The Shared Library Part
-------------------------------
This part will be put in a separate supporting shared library, allowing
other Python module to link against it (and make use of its symbols).
.. code-block:: c++
DBoLinkCreateMethod(Library)
PyTypeObjectDefinitions(Library)
To define ``PyTypeLibrary``, use the ``PyTypeObjectDefinitions()`` macro.
This macro is specific for classes that, as exposed by Python,
are neither *derived* classes nor *base* classes for others.
That is, they are standalone from the inheritance point of view.
The ``DBoLinkCreateMethod()`` macro will define the ``PyLibrary_Link()``
function which is responsible for encapsulating a C++ ``Library`` object
into a Python ``PyLibrary`` one.
3.3 Python Module (C++ namespace)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We use the Python module to replicate the C++ *namespace*. Thus, for the
``Hurricane`` namespace we create a Python ``Hurricane`` module which is
defined in the ``PyHurricane.cpp`` file, then we add into that module
dictionary all the Python types encapsulating the C++ classes of that
namespace.
.. code-block:: c++
DL_EXPORT(void) initHurricane ()
{
PyLibrary_LinkPyType(); // step 1.
PYTYPE_READY( Library ) // step 2.
__cs.addType( "library", &PyTypeLibrary, "<Library>", false ); // step 3.
PyObject* module = Py_InitModule( "Hurricane", PyHurricane_Methods );
if (module == NULL) {
cerr << "[ERROR]\n"
<< " Failed to initialize Hurricane module." << endl;
return;
}
Py_INCREF( &PyTypeLibrary ); // step 4.
PyModule_AddObject( module, "Library", (PyObject*)&PyTypeLibrary ); // step 4.
}
The ``initHurricane()`` initialisation function shown above has
been scrubbed of everything not relevant to the ``PyLibrary`` class.
The integration of the ``PyLibrary`` class into the module needs
four steps:
#. A call to `PyLibrary_LinkPyType()`_ to hook the Python type functions
in the Python type object.
#. A call to the ``PYTYPE_READY()`` macro (standard Python).
#. Registering the type into the ``__cs`` object, with ``addType()``.
The arguments are self explanatory, save for the last which is a
boolean to tell if this is a *derived* class or not.
#. Adding the type object (``PyTypeLibrary``) into the dictionnary of
the module itself. This allow to mimic closely the C++ syntax:
.. code-block:: python
import Hurricane
lib = Hurricane.Library.create( db, 'root' )