coriolis/documentation/PythonCpp/DBoStandalone.rst

.. -*- 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' )