...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
This page defines two concepts used to describe classes which manage a Python objects, and which are intended to support usage with a Python-like syntax.
Models of the ObjectWrapper concept have object as a publicly-accessible base class, and are used to supply special construction behavior and/or additional convenient functionality through (often templated) member functions. Except when the return type R is itself an TypeWrapper, a member function invocation of the form
x.some_function(a1, a2,...an)
always has semantics equivalent to:
extract<R>(x.attr("some_function")(object(a1), object(a2),...object(an)))()
(see caveat below).
TypeWrapper is a refinement of ObjectWrapper
which is associated with a particular Python type X
.
For a given TypeWrapper T
,
a valid constructor expression
T(a1, a2,...an)
builds a new T object managing the result of invoking X with arguments corresponding to
object(a1), object(a2),...object(an)
. When used as arguments to wrapped C++ functions, or as the template parameter to extract<>, only instances of the associated Python type will be considered a match.
The upshot of the special member function invocation rules when the return
type is a TypeWrapper is that it is possible for the returned object to
manage a Python object of an inappropriate type. This is not usually a
serious problem; the worst-case result is that errors will be detected
at runtime a little later than they might otherwise be. For an example
of how this can occur, note that the dict
member function items
returns
an object of type list.
Now suppose the user defines this dict
subclass in Python:
>>> class mydict(dict): ... def items(self): ... return tuple(dict.items(self)) # return a tuple
Since an instance of mydict
is also an instance of dict
,
when used as an argument to a wrapped C++ function, boost::python::dict
can accept objects of Python type mydict
.
Invoking items()
on this object can result in an instance of boost::python::list
which actually holds a Python tuple
.
Subsequent attempts to use list
methods (e.g. append
, or
any other mutating operation) on this object will raise the same exception
that would occur if you tried to do it from Python.