135 lines
8.8 KiB
Plaintext
135 lines
8.8 KiB
Plaintext
[chapter Concepts
|
|
[quickbook 1.7]
|
|
]
|
|
|
|
[section CallPolicies]
|
|
[section Introduction]
|
|
|
|
Models of the CallPolicies concept are used to specialize the behavior of Python callable objects
|
|
generated by Boost.Python to wrapped C++ objects like function and member function pointers,
|
|
providing three behaviors:
|
|
|
|
# `precall` - Python argument tuple management before the wrapped object is invoked
|
|
# `result_converter` - C++ return value handling
|
|
# `postcall` - Python argument tuple and result management after the wrapped object is invoked
|
|
# `extract_return_type` - metafunction for extracting the return type from a given signature type sequence
|
|
|
|
[endsect]
|
|
[section CallPolicies Composition]
|
|
|
|
In order to allow the use of multiple models of CallPolicies in the same callable object,
|
|
Boost.Python's CallPolicies class templates provide a chaining interface which allows them to be
|
|
recursively composed. This interface takes the form of an optional template parameter, `Base`, which
|
|
defaults to `default_call_policies`. By convention, the `precall` function of the `Base` is invoked after
|
|
the `precall` function supplied by the `outer` template, and the `postcall` function of the `Base` is invoked
|
|
before the `postcall` function of the `outer` template. If a `result_converter` is supplied by the `outer`
|
|
template, it replaces any `result_converter` supplied by the `Base`. For an example, see
|
|
`return_internal_reference`.
|
|
|
|
[endsect]
|
|
[section Concept Requirements]
|
|
[table
|
|
[[Expression][Type][Result/Semantics]]
|
|
[[`x.precall(a)`][convertible to `bool`]
|
|
[returns `false` and `PyErr_Occurred() != 0` upon failure, `true` otherwise.]]
|
|
[[`P::result_converter`][A model of `ResultConverterGenerator`.]
|
|
[An MPL unary Metafunction Class used produce the "preliminary" result object.]]
|
|
[[`x.postcall(a, r)`][convertible to `PyObject*`]
|
|
[`0` and `PyErr_Occurred() != 0` upon failure. Must "conserve references" even in the event of an exception. In other words, if `r` is not returned, its reference count must be decremented; if another existing object is returned, its reference count must be incremented.]]
|
|
[[`P::extract_return_type`][A model of Metafunction.]
|
|
[An MPL unary Metafunction used extract the return type from a given signature. By default it is derived from `mpl::front`.]]
|
|
]
|
|
[endsect]
|
|
[endsect]
|
|
[section Dereferenceable]
|
|
[section Introduction]
|
|
Instances of a `Dereferenceable` type can be used like a pointer to access an lvalue.
|
|
[endsect]
|
|
[section Concept Requirements]
|
|
In the table below, `T` is a model of Dereferenceable, and `x` denotes an object of type `T`. In addition, all pointers are `Dereferenceable`.
|
|
[table
|
|
[[Expression][Result][Operational Semantics]]
|
|
[[`get_pointer(x)`][convertible to `pointee<T>::type*`]
|
|
[`&*x`, or a null pointer ]]
|
|
]
|
|
[endsect]
|
|
[endsect]
|
|
[section Extractor]
|
|
[section Introduction]
|
|
An Extractor is a class which Boost.Python can use to extract C++ objects from Python objects, and is typically used by facilities that define `from_python` conversions for "traditional" Python extension types.
|
|
[endsect]
|
|
[section Concept Requirements]
|
|
In the table below, `X` denotes a model of `Extractor` and `a` denotes an instance of a Python object type.
|
|
[table
|
|
[[Expression][Type][Semantics]]
|
|
[[`X::execute(a)`][non-void]
|
|
[Returns the C++ object being extracted. The execute function must not be overloaded.]]
|
|
[[`&a.ob_type`][`PyTypeObject**`]
|
|
[Points to the `ob_type` field of an object which is layout-compatible with `PyObject`]]
|
|
]
|
|
[endsect]
|
|
[section Notes]
|
|
Informally, an Extractor's execute member must be a non-overloaded static function whose single argument is a Python object type. Acceptable Python object types include those publicly (and unambiguously) derived from PyObject, and POD types which are layout-compatible with PyObject.
|
|
[endsect]
|
|
[endsect]
|
|
[section HolderGenerator]
|
|
[section Introduction]
|
|
A HolderGenerator is a unary metafunction class which returns types suitable for holding instances of its argument in a wrapped C++ class instance.
|
|
[endsect]
|
|
[section Concept Requirements]
|
|
In the table below, `G` denotes an type which models `HolderGenerator`, and `X` denotes a class type.
|
|
[table
|
|
[[Expression][Requirements]]
|
|
[[`G::apply<X>::type`][A concrete subclass of `instance_holder` which can hold objects of type `X`. ]]
|
|
]
|
|
[endsect]
|
|
[endsect]
|
|
[section ResultConverter]
|
|
[section Introduction]
|
|
A ResultConverter for a type `T` is a type whose instances can be used to convert C++ return values of type `T` `to_python`. A ResultConverterGenerator is an MPL unary metafunction class which, given the return type of a C++ function, returns a ResultConverter for that type. ResultConverters in Boost.Python generally inspect library's registry of converters to find a suitable converter, but converters which don't use the registry are also possible.
|
|
[endsect]
|
|
[section ResultConverter Concept Requirements]
|
|
In the table below, `C` denotes a ResultConverter type for a type `R`, `c` denotes an object of type `C`, and `r` denotes an object of type `R`.
|
|
[table
|
|
[[Expression][Type][Semantics]]
|
|
[[`C c`][]
|
|
[Constructs a `c` object.]]
|
|
[[`c.convertible()`][convertible to `bool`]
|
|
[`false` iff no conversion from any `R` value to a Python object is possible.]]
|
|
[[`c(r)`][convertible to `PyObject*`]
|
|
[A pointer to a Python object corresponding to `r`, or `0` iff `r` could not be converted `to_python`, in which case `PyErr_Occurred` should return non-zero.]]
|
|
[[`c.get_pytype()`][`PyTypeObject const *`]
|
|
[A pointer to a Python Type object corresponding to result of the conversion, or `0`. Used for documentation generation. If `0` is returned the generated type in the documentation will be object.]]
|
|
]
|
|
[endsect]
|
|
[section ResultConverterGenerator Concept Requirements]
|
|
In the table below, `G` denotes a ResultConverterGenerator type and `R` denotes a possible C++ function return type.
|
|
[table
|
|
[[Expression][Requirements]]
|
|
[[`G::apply<R>::type`][A ResultConverter type for `R`.]]
|
|
]
|
|
[endsect]
|
|
[endsect]
|
|
[section ObjectWrapper]
|
|
[section Introduction]
|
|
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.
|
|
[endsect]
|
|
[section ObjectWrapper Concept Requirements]
|
|
Models of the ObjectWrapper concept have [link object_wrappers.boost_python_object_hpp.class_object 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 [link concepts.objectwrapper.typewrapper_concept_requirements 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 [link concepts.objectwrapper.caveat caveat] below).
|
|
[endsect]
|
|
[section TypeWrapper Concept Requirements]
|
|
TypeWrapper is a refinement of [link concepts.objectwrapper.objectwrapper_concept_requiremen 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 [link to_from_python_type_conversion.boost_python_extract_hpp.class_template_extract extract<>], only instances of the associated Python type will be considered a match.
|
|
[endsect]
|
|
[section Caveat]
|
|
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 [link object_wrappers.boost_python_dict_hpp.class_dict dict] member function `items` returns an object of type [link object_wrappers.boost_python_list_hpp.class_list 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, [link object_wrappers.boost_python_dict_hpp.class_dict boost::python::dict] can accept objects of Python type `mydict`. Invoking `items()` on this object can result in an instance of [link object_wrappers.boost_python_list_hpp.class_list 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.
|
|
[endsect]
|
|
[endsect]
|