.. -*- Mode: rst -*-
|newpage|
4. Case 2 - Hierarchy of DBo Derived Classes
==============================================
Now we want to export the following C++ class hierarchy into Python: ::
PyEntity <-- PyComponent <-+- PyContact
+- PySegment <-+- PyHorizontal
+- PyVertical
4.1 Base Class Header
~~~~~~~~~~~~~~~~~~~~~~~
**Remark:** this is only a partial description of the tree for the sake of
clarity.
One important fact to remember is that ``PyEntity`` and ``PyComponent``
being related to C++ abstract classes, no objects of those types will be
created, only ``PyContact``, ``PyHorizontal`` or ``PyVertical`` will.
The consequence is that there is no ``PyEntity_Link()`` like in `3.1`
but instead two functions:
#. ``PyEntity_NEW()`` which create the relevant ``PyEntity`` *derived*
object from the ``Entity`` one. For example, if the ``Entity*`` given
as argument is in fact a ``Horizontal*``, then the function will
return a ``PyHorizontal*``.
#. ``EntityCast()`` do the reverse of ``PyEntity_NEW()`` that is, from
a ``PyEntity``, return the C++ *derived* object. Again, if the
``PyEntity*`` is a ``PyHorizontal*``, the function will cast it as
a ``Horizontal*`` *then* return it as an ``Entity*``.
.. code-block:: python
#ifndef ISOBAR_PY_ENTITY_H
#define ISOBAR_PY_ENTITY_H
#include "hurricane/isobar/PyHurricane.h"
#include "hurricane/Entity.h"
namespace Isobar {
extern "C" {
typedef struct {
PyObject_HEAD
Hurricane::Entity* _object;
} PyEntity;
extern PyObject* PyEntity_NEW ( Hurricane::Entity* entity );
extern void PyEntity_LinkPyType ();
extern PyTypeObject PyTypeEntity;
extern PyMethodDef PyEntity_Methods[];
#define IsPyEntity(v) ( (v)->ob_type == &PyTypeEntity )
#define PYENTITY(v) ( (PyEntity*)(v) )
#define PYENTITY_O(v) ( PYENTITY(v)->_object )
} // extern "C".
Hurricane::Entity* EntityCast ( PyObject* derivedObject );
} // Isobar namespace.
#endif // ISOBAR_PY_ENTITY_H
|newpage|
4.2 Base Class File
~~~~~~~~~~~~~~~~~~~~~
Changes from `3.2 Class Associated File` are:
#. No call to ``DBoLinkCreateMethod()`` because there must be no ``PyEntity_Link()``,
but the definitions of ``PyEntity_NEW()`` and ``EntityCast``.
#. For defining the ``PyTypeEntity`` Python type, we call a different
macro: ``PyTypeRootObjectDefinitions``, dedicated to base classes.
.. code-block:: c++
#include "hurricane/isobar/PyCell.h"
#include "hurricane/isobar/PyHorizontal.h"
#include "hurricane/isobar/PyVertical.h"
#include "hurricane/isobar/PyContact.h"
namespace Isobar {
using namespace Hurricane;
extern "C" {
#if defined(__PYTHON_MODULE__)
#define METHOD_HEAD(function) GENERIC_METHOD_HEAD(Entity,entity,function)
DBoDestroyAttribute(PyEntity_destroy ,PyEntity)
static PyObject* PyEntity_getCell ( PyEntity *self )
{
Cell* cell = NULL;
HTRY
METHOD_HEAD( "Entity.getCell()" )
cell = entity->getCell();
HCATCH
return PyCell_Link( cell );
}
PyMethodDef PyEntity_Methods[] =
{ { "getCell", (PyCFunction)PyEntity_getCell, METH_NOARGS
, "Returns the entity cell." }
, { "destroy", (PyCFunction)PyEntity_destroy, METH_NOARGS
, "Destroy associated hurricane object, the python object remains." }
, {NULL, NULL, 0, NULL} /* sentinel */
};
DBoDeleteMethod(Entity)
PyTypeObjectLinkPyType(Entity)
#else // End of Python Module Code Part.
PyObject* PyEntity_NEW ( Entity* entity )
{
if (not entity) {
PyErr_SetString ( HurricaneError, "Invalid Entity (bad occurrence)" );
return NULL;
}
Horizontal* horizontal = dynamic_cast<Horizontal*>(entity);
if (horizontal) return PyHorizontal_Link( horizontal );
Vertical* vertical = dynamic_cast<Vertical*>(entity);
if (vertical) return PyVertical_Link( vertical );
Contact* contact = dynamic_cast<Contact*>(entity);
if (contact) return PyContact_Link( contact );
Py_RETURN_NONE;
}
PyTypeRootObjectDefinitions(Entity)
#endif // Shared Library Code Part (1).
} // extern "C".
#if !defined(__PYTHON_MODULE__)
Hurricane::Entity* EntityCast ( PyObject* derivedObject ) {
if (IsPyHorizontal(derivedObject)) return PYHORIZONTAL_O(derivedObject);
if (IsPyVertical (derivedObject)) return PYVERTICAL_O(derivedObject);
if (IsPyContact (derivedObject)) return PYCONTACT_O(derivedObject);
return NULL;
}
#endif // Shared Library Code Part (2).
} // Isobar namespace.
|newpage|
4.3 Intermediate Class Header
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changes from `3.1 Class Associated Header File` are:
#. As for ``PyEntity``, and because this is still an abstract class,
there is no ``PyComponent_Link()`` function.
#. The definition of the ``PyComponent`` |struct| is differs. There is
no ``PyObject_HEAD`` (it is a Python *derived* class). The only
field is of the base class type ``PyEntity`` and for use with
Coriolis macros, **it must** be named ``_baseObject`` (note that
this is *not* a pointer but a whole object).
.. code-block:: c++
#ifndef ISOBAR_PY_COMPONENT_H
#define ISOBAR_PY_COMPONENT_H
#include "hurricane/isobar/PyEntity.h"
#include "hurricane/Component.h"
namespace Isobar {
extern "C" {
typedef struct {
PyEntity _baseObject;
} PyComponent;
extern PyTypeObject PyTypeComponent;
extern PyMethodDef PyComponent_Methods[];
extern void PyComponent_LinkPyType ();
#define IsPyComponent(v) ((v)->ob_type == &PyTypeComponent)
#define PYCOMPONENT(v) ((PyComponent*)(v))
#define PYCOMPONENT_O(v) (static_cast<Component*>(PYCOMPONENT(v)->_baseObject._object))
} // extern "C".
} // Isobar namespace.
#endif
4.4 Intermediate Class File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changes from `3.2 Class Associated File` are:
1. Redefinition of the default macros ``ACCESS_OBJECT`` and ``ACCESS_CLASS``.
* The pointer to the C++ encapsulated object (attribute ``_object``) is hold
by the base class ``PyEntity``. The ``ACCESS_OBJECT`` macro which is tasked
to give access to that attribute is then ``_baseObject._object`` as
``PyComponent`` is a direct derived class of ``PyEntity``.
* ``ACCESS_CLASS`` is similar to ``ACCESS_OBJECT`` for accessing the base
class, that is a pointer to ``PyEntity``.
|newpage|
2. For defining the ``PyTypeComponent`` Python type, we call a yet different
macro: ``PyTypeInheritedObjectDefinitions()``, dedicated to derived classes.
For this this macro we need to give as argument the derived class and the
base class.
.. code-block:: c++
#include "hurricane/isobar/PyComponent.h"
#include "hurricane/isobar/PyNet.h"
namespace Isobar {
using namespace Hurricane;
extern "C" {
#undef ACCESS_OBJECT
#undef ACCESS_CLASS
#define ACCESS_OBJECT _baseObject._object
#define ACCESS_CLASS(_pyObject) &(_pyObject->_baseObject)
#define METHOD_HEAD(function) GENERIC_METHOD_HEAD(Component,component,function)
#if defined(__PYTHON_MODULE__)
DirectGetLongAttribute(PyComponent_getX,getX,PyComponent,Component)
DirectGetLongAttribute(PyComponent_getY,getY,PyComponent,Component)
DBoDestroyAttribute(PyComponent_destroy,PyComponent)
static PyObject* PyComponent_getNet ( PyComponent *self )
{
Net* net = NULL;
HTRY
METHOD_HEAD( "Component.getNet()" )
net = component->getNet( );
HCATCH
return PyNet_Link( net );
}
PyMethodDef PyComponent_Methods[] =
{ { "getX" , (PyCFunction)PyComponent_getX , METH_NOARGS
, "Return the Component X value." }
, { "getY" , (PyCFunction)PyComponent_getY , METH_NOARGS
, "Return the Component Y value." }
, { "getNet" , (PyCFunction)PyComponent_getNet , METH_NOARGS
, "Returns the net owning the component." }
, { "destroy", (PyCFunction)PyComponent_destroy, METH_NOARGS
, "destroy associated hurricane object, the python object remains." }
, {NULL, NULL, 0, NULL} /* sentinel */
};
DBoDeleteMethod(Component)
PyTypeObjectLinkPyType(Component)
#else // Python Module Code Part.
PyTypeInheritedObjectDefinitions(Component, Entity)
#endif // Shared Library Code Part.
} // extern "C".
} // Isobar namespace.
4.5 Terminal Class Header
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The contents of this file is almost identical to `4.3 Intermediate Class Header`_,
save for the presence of a ``PyContact_Link()`` function. She is present
at this level because the class is a concrete one and can be instanciated.
.. code-block:: c++
#ifndef ISOBAR_PY_CONTACT_H
#define ISOBAR_PY_CONTACT_H
#include "hurricane/isobar/PyComponent.h"
#include "hurricane/Contact.h"
namespace Isobar {
extern "C" {
typedef struct {
PyComponent _baseObject;
} PyContact;
extern PyTypeObject PyTypeContact;
extern PyMethodDef PyContact_Methods[];
extern PyObject* PyContact_Link ( Hurricane::Contact* object );
extern void PyContact_LinkPyType ();
#define IsPyContact(v) ( (v)->ob_type == &PyTypeContact )
#define PYCONTACT(v) ( (PyContact*)(v) )
#define PYCONTACT_O(v) ( PYCONTACT(v)->_baseObject._baseObject._object )
} // extern "C".
} // Isobar namespace.
#endif // ISOBAR_PY_CONTACT_H
4.6 Terminal Class File
~~~~~~~~~~~~~~~~~~~~~~~~~
Changes from `4.4 Intermediate Class File`_ are:
#. As previously, we have to redefine the macros ``ACCESS_OBJECT`` and ``ACCESS_CLASS``.
But, as we are one level deeper into the hierarchy, one more level of
indirection using ``_baseObject`` must be used.
* ``ACCESS_OBJECT`` becomes ``_baseObject._baseObject._object``.
* ``ACCESS_CLASS`` becomes ``&(_pyObject->_baseObject._baseObject)``.
#. For defining the ``PyTypeContact`` Python type, we call again
``PyTypeInheritedObjectDefinitions()``. It is the same whether the class is
terminal or not.
#. And, this time, as the Python class is concrete, we call the macro
``DBoLinkCreateMethod()`` to create the ``PyContact_Link()`` function.
.. code-block:: c++
#include "hurricane/isobar/PyContact.h"
namespace Isobar {
using namespace Hurricane;
extern "C" {
#undef ACCESS_OBJECT
#undef ACCESS_CLASS
#define ACCESS_OBJECT _baseObject._baseObject._object
#define ACCESS_CLASS(_pyObject) &(_pyObject->_baseObject._baseObject)
#define METHOD_HEAD(function) GENERIC_METHOD_HEAD(Contact,contact,function)
#if defined(__PYTHON_MODULE__)
DirectGetLongAttribute(PyContact_getWidth , getWidth , PyContact,Contact)
DirectGetLongAttribute(PyContact_getHeight, getHeight, PyContact,Contact)
DBoDestroyAttribute(PyContact_destroy, PyContact)
static PyObject* PyContact_create ( PyObject*, PyObject *args )
{
Contact* contact = NULL;
HTRY
// Usual signature then arguments parsing.
HCATCH
return PyContact_Link(contact);
}
PyMethodDef PyContact_Methods[] =
{ { "create" , (PyCFunction)PyContact_create , METH_VARARGS|METH_STATIC
, "Create a new Contact." }
, { "destroy" , (PyCFunction)PyContact_destroy , METH_NOARGS
, "Destroy associated hurricane object, the python object remains." }
, { "getWidth" , (PyCFunction)PyContact_getWidth , METH_NOARGS
, "Return the contact width." }
, { "getHeight", (PyCFunction)PyContact_getHeight, METH_NOARGS
, "Return the contact height." }
, {NULL, NULL, 0, NULL} /* sentinel */
};
DBoDeleteMethod(Contact)
PyTypeObjectLinkPyType(Contact)
#else // Python Module Code Part.
DBoLinkCreateMethod(Contact)
PyTypeInheritedObjectDefinitions(Contact, Component)
#endif // Shared Library Code Part.
} // extern "C".
} // Isobar namespace.
4.8 Python Module
~~~~~~~~~~~~~~~~~~~
.. code-block:: c++
DL_EXPORT(void) initHurricane ()
{
PyEntity_LinkPyType(); // step 1.
PyComponent_LinkPyType();
PyContact_LinkPyType();
PYTYPE_READY( Entity ) // step 2.
PYTYPE_READY_SUB( Component, Entity )
PYTYPE_READY_SUB( Contact , Component )
__cs.addType( "ent" , &PyTypeEntity , "<Entity>" , false ); // step 3.
__cs.addType( "comp" , &PyTypeComponent, "<Component>", false, "ent" );
__cs.addType( "contact", &PyTypeContact , "<Contact>" , false, "comp" );
PyObject* module = Py_InitModule( "Hurricane", PyHurricane_Methods );
if (module == NULL) {
cerr << "[ERROR]\n"
<< " Failed to initialize Hurricane module." << endl;
return;
}
Py_INCREF( &PyTypeContact ); // step 4.
PyModule_AddObject( module, "Contact", (PyObject*)&PyTypeContact ); // step 4.
}