boost_1_45_0/libs/python/doc/internals.rst

===================================
 Boost.Python_ Internals |(logo)|__
===================================

.. |(logo)| image:: ../../../boost.png
   :alt: Boost
   :class: boost-logo

__ ../../../index.htm

.. _`Boost.Python`: index.html

.. _license: ../../../LICENSE_1_0.txt


-------------------------------------------------------
A conversation between Brett Calcott and David Abrahams
-------------------------------------------------------

:copyright: Copyright David Abrahams and Brett Calcott 2003. See
            accompanying license_ for terms of use.

In both of these cases, I'm quite capable of reading code - but the
thing I don't get from scanning the source is a sense of the
architecture, both structurally, and temporally (er, I mean in what
order things go on).

1) What happens when you do the following::

     struct boring {};
     ...etc...
     class_<boring>("boring")
         ;

There seems to be a fair bit going on.

 - Python needs a new ClassType to be registered.
 - We need to construct a new type that can hold our boring struct.
 - Inward and outward converters need to be registered for the type.

Can you gesture in the general direction where these things are done?

  I only have time for a "off-the-top-of-my-head" answer at the moment;
  I suggest you step through the code with a debugger after reading this
  to see how it works, fill in details, and make sure I didn't forget
  anything.

          A new (Python) subclass of Boost.Python.Instance (see
          libs/python/src/object/class.cpp) is created by invoking
          Boost.Python.class, the metatype::

                >>> boring = Boost.Python.class(
                ...     'boring'
                ...   , bases_tuple       # in this case, just ()
                ...   , { 
                ...         '__module__' : module_name
                ...       , '__doc__' : doc_string # optional
                ...     }
                ... )

          A handle to this object is stuck in the m_class_object field
          of the registration associated with ``typeid(boring)``.  The
          registry will keep that object alive forever, even if you
          wipe out the 'boring' attribute of the extension module
          (probably not a good thing).

          Because you didn't specify ``class<boring, non_copyable,
          ...>``, a to-python converter for boring is registered which
          copies its argument into a value_holder held by the the
          Python boring object.

          Because you didn't specify ``class<boring ...>(no_init)``,
          an ``__init__`` function object is added to the class
          dictionary which default-constructs a boring in a
          value_holder (because you didn't specify some smart pointer
          or derived wrapper class as a holder) held by the Python
          boring object.

          ``register_class_from_python`` is used to register a
          from-python converter for ``shared_ptr<boring>``.
          ``boost::shared_ptr``\ s are special among smart pointers
          because their Deleter argument can be made to manage the
          whole Python object, not just the C++ object it contains, no
          matter how the C++ object is held.

          If there were any ``bases<>``, we'd also be registering the
          relationship between these base classes and boring in the
          up/down cast graph (``inheritance.[hpp/cpp]``).

          In earlier versions of the code, we'd be registering lvalue
          from-python converters for the class here, but now
          from-python conversion for wrapped classes is handled as a
          special case, before consulting the registry, if the source
          Python object's metaclass is the Boost.Python metaclass.

          Hmm, that from-python converter probably ought to be handled
          the way class converters are, with no explicit conversions
          registered.

2) Can you give a brief overview of the data structures that are
   present in the registry

        The registry is simple: it's just a map from typeid ->
        registration (see boost/python/converter/registrations.hpp).
        ``lvalue_chain`` and ``rvalue_chain`` are simple endogenous
        linked lists.

        If you want to know more, just ask.

        If you want to know about the cast graph, ask me something specific in
        a separate message.

   and an overview of the process that happens as a type makes its
   way from c++ to python and back again.

  Big subject.  I suggest some background reading: look for relevant
  info in the LLNL progress reports and the messages they link to.
  Also, 

        http://mail.python.org/pipermail/c++-sig/2002-May/001023.html

        http://mail.python.org/pipermail/c++-sig/2002-December/003115.html

        http://aspn.activestate.com/ASPN/Mail/Message/1280898

        http://mail.python.org/pipermail/c++-sig/2002-July/001755.html

  from c++ to python:

       It depends on the type and the call policies in use or, for
       ``call<>(...)``, ``call_method<>(...)``, or ``object(...)``, if
       ``ref`` or ``ptr`` is used.  There are also two basic
       categories to to-python conversion, "return value" conversion
       (for Python->C++ calls) and "argument" conversion (for
       C++->Python calls and explicit ``object()`` conversions).  The
       behavior of these two categories differs subtly in various ways
       whose details I forget at the moment.  You can probably find
       the answers in the above references, and certainly in the code.

       The "default" case is by-value (copying) conversion, which uses
       to_python_value as a to-python converter.

           Since there can sensibly be only one way to convert any type
           to python (disregarding the idea of scoped registries for the
           moment), it makes sense that to-python conversions can be
           handled by specializing a template.  If the type is one of
           the types handled by a built-in conversion
           (builtin_converters.hpp), the corresponding template
           specialization of to_python_value gets used.

           Otherwise, to_python_value uses the ``m_to_python``
           function in the registration for the C++ type.

       Other conversions, like by-reference conversions, are only
       available for wrapped classes, and are requested explicitly by
       using ``ref(...)``, ``ptr(...)``, or by specifying different
       CallPolicies for a call, which can cause a different to-python
       converter to be used.  These conversions are never registered
       anywhere, though they do need to use the registration to find
       the Python class corresponding to the C++ type being referred
       to.  They just build a new Python instance and stick the
       appropriate Holder instance in it.


  from python to C++:

       Once again I think there is a distinction between "return value"
       and "argument" conversions, and I forget exactly what that is.

       What happens depends on whether an lvalue conversion is needed
       (see http://mail.python.org/pipermail/c++-sig/2002-May/001023.html)
       All lvalue conversions are also registered in a type's rvalue
       conversion chain, since when an rvalue will do, an lvalue is
       certainly good enough.

       An lvalue conversion can be done in one step (just get me the
       pointer to the object - it can be ``NULL`` if no conversion is
       possible) while an rvalue conversion requires two steps to
       support wrapped function overloading and multiple converters for
       a given C++ target type: first tell me if a conversion is
       possible, then construct the converted object as a second step.