1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
[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]
|
