.. -*- Mode: rst -*- 1. Introduction =============== * This document is written for people already familiar with the `Python/C API Reference Manual`_. * The macros provided by the Hurricane Python/C API are written using the standard Python C/API. That is, you may not use them and write directly your functions with the original API or any mix between. You only have to respect some naming convention. * Coriolis is build against Python 2.7. 1.1 About Technical Choices ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some would say, why not use *off the shelf* wrappers like ``swig``, ``boost::python`` or ``pybind11``, here are some clues. #. **Partial exposure of the C++ class tree.** We expose at Python level C++ base classes, only if they provides common methods that we want to see. Otherwise, we just show them as base classes under Python. For instance ``Library`` is derived from ``DBo``, but we won't see it under Python. #. **Bi-directional communication.** When a Python object is deleted, the wrapper obviously has a pointer toward the underlying C++ object and is able to delete it. But, the reverse case can occurs, meaning that you have a C++ object wrapped in Python and the database delete the underlying object. The wrapped Python object *must* be informed that it no longer refer a valid C++ one. Moreover, as we do not control when Python objects gets deleteds (that is, when their reference count reaches zero), we can have valid Python object with a dangling C++ pointer. So our Python objects can be warned by the C++ objects that they are no longer valid and any other operation than the deletion should result in a severe non-blocking error. To be precise, this apply to persistent object in the C++ database, like ``Cell``, ``Net``, ``Instance`` or ``Component``. Short lived objects like ``Box`` or ``Point`` retains the classic Python behavior. Another aspect is that, for all derived ``DBo`` objects, one and only one Python object is associated. For one given ``Instance`` object we will always return the *same* ``PyInstance`` object, thanks to the bi-directional link. Obviously, the *reference count* of the ``PyInstance`` is managed accordingly. This mechanism is implemented by the ``PyTypeManager::_link()`` method. #. **Linking accross modules.** As far as I understand, the wrappers are for monolithic libraries. That is, you wrap the entire library in one go. But Hurricane has a modular design, the core database then various tools. We do not, and cannot, have one gigantic wrapper that would encompass all the libraries in one go. We do one Python module for one C++ library. This brings another issue, at Python level this time. The Python modules for the libraries have to share some functions. Python provides a mechanism to pass C function pointers accross modules, (``Capsule``) but I did not fully understand it. Instead, we register all the newly defined Python type object in the ``PyTypeManager`` and we link the associated C++ library into all Python modules. So all types and ancillary functions can easily be seen accross modules. This way, we do not rely upon a pointer transmission through Python modules, but directly uses linker capabilities. **The PyTypeManager** approach also suppress the need to *split* into two libraries the Python modules like in the C-Macros implementation, and the double compilation pass.