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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
.. _reference:
.. warning::
Please be advised that the reference documentation discussing pybind11
internals is currently incomplete. Please refer to the previous sections
and the pybind11 header files for the nitty gritty details.
Reference
#########
Macros
======
.. function:: PYBIND11_PLUGIN(const char *name)
This macro creates the entry point that will be invoked when the Python
interpreter imports a plugin library. Please create a
:class:`module` in the function body and return the pointer to its
underlying Python object at the end.
.. code-block:: cpp
PYBIND11_PLUGIN(example) {
pybind11::module m("example", "pybind11 example plugin");
/// Set up bindings here
return m.ptr();
}
.. _core_types:
Convenience classes for arbitrary Python types
==============================================
Without reference counting
--------------------------
.. class:: handle
The :class:`handle` class is a thin wrapper around an arbitrary Python
object (i.e. a ``PyObject *`` in Python's C API). It does not perform any
automatic reference counting and merely provides a basic C++ interface to
various Python API functions.
.. seealso::
The :class:`object` class inherits from :class:`handle` and adds automatic
reference counting features.
.. function:: handle::handle()
The default constructor creates a handle with a ``nullptr``-valued pointer.
.. function:: handle::handle(const handle&)
Copy constructor
.. function:: handle::handle(PyObject *)
Creates a :class:`handle` from the given raw Python object pointer.
.. function:: PyObject * handle::ptr() const
Return the ``PyObject *`` underlying a :class:`handle`.
.. function:: const handle& handle::inc_ref() const
Manually increase the reference count of the Python object. Usually, it is
preferable to use the :class:`object` class which derives from
:class:`handle` and calls this function automatically. Returns a reference
to itself.
.. function:: const handle& handle::dec_ref() const
Manually decrease the reference count of the Python object. Usually, it is
preferable to use the :class:`object` class which derives from
:class:`handle` and calls this function automatically. Returns a reference
to itself.
.. function:: void handle::ref_count() const
Return the object's current reference count
.. function:: handle handle::get_type() const
Return a handle to the Python type object underlying the instance
.. function detail::accessor handle::operator[](handle key) const
Return an internal functor to invoke the object's sequence protocol.
Casting the returned ``detail::accessor`` instance to a :class:`handle` or
:class:`object` subclass causes a corresponding call to ``__getitem__``.
Assigning a :class:`handle` or :class:`object` subclass causes a call to
``__setitem__``.
.. function detail::accessor handle::operator[](const char *key) const
See the above function (the only difference is that they key is provided as
a string literal).
.. function detail::accessor handle::attr(handle key) const
Return an internal functor to access the object's attributes.
Casting the returned ``detail::accessor`` instance to a :class:`handle` or
:class:`object` subclass causes a corresponding call to ``__getattr``.
Assigning a :class:`handle` or :class:`object` subclass causes a call to
``__setattr``.
.. function detail::accessor handle::attr(const char *key) const
See the above function (the only difference is that they key is provided as
a string literal).
.. function operator handle::bool() const
Return ``true`` when the :class:`handle` wraps a valid Python object.
.. function str handle::str() const
Return a string representation of the object. This is analogous to
the ``str()`` function in Python.
.. function:: template <typename T> T handle::cast() const
Attempt to cast the Python object into the given C++ type. A
:class:`cast_error` will be throw upon failure.
.. function:: template <typename ... Args> object handle::call(Args&&... args) const
Assuming the Python object is a function or implements the ``__call__``
protocol, ``call()`` invokes the underlying function, passing an arbitrary
set of parameters. The result is returned as a :class:`object` and may need
to be converted back into a Python object using :func:`handle::cast`.
When some of the arguments cannot be converted to Python objects, the
function will throw a :class:`cast_error` exception. When the Python
function call fails, a :class:`error_already_set` exception is thrown.
With reference counting
-----------------------
.. class:: object : public handle
Like :class:`handle`, the object class is a thin wrapper around an
arbitrary Python object (i.e. a ``PyObject *`` in Python's C API). In
contrast to :class:`handle`, it optionally increases the object's reference
count upon construction, and it *always* decreases the reference count when
the :class:`object` instance goes out of scope and is destructed. When
using :class:`object` instances consistently, it is much easier to get
reference counting right at the first attempt.
.. function:: object::object(const object &o)
Copy constructor; always increases the reference count
.. function:: object::object(const handle &h, bool borrowed)
Creates a :class:`object` from the given :class:`handle`. The reference
count is only increased if the ``borrowed`` parameter is set to ``true``.
.. function:: object::object(PyObject *ptr, bool borrowed)
Creates a :class:`object` from the given raw Python object pointer. The
reference count is only increased if the ``borrowed`` parameter is set to
``true``.
.. function:: object::object(object &&other)
Move constructor; steals the object from ``other`` and preserves its
reference count.
.. function:: handle object::release()
Resets the internal pointer to ``nullptr`` without without decreasing the
object's reference count. The function returns a raw handle to the original
Python object.
.. function:: object::~object()
Destructor, which automatically calls :func:`handle::dec_ref()`.
Convenience classes for specific Python types
=============================================
.. class:: module : public object
.. function:: module::module(const char *name, const char *doc = nullptr)
Create a new top-level Python module with the given name and docstring
.. function:: module module::def_submodule(const char *name, const char *doc = nullptr)
Create and return a new Python submodule with the given name and docstring.
This also works recursively, i.e.
.. code-block:: cpp
pybind11::module m("example", "pybind11 example plugin");
pybind11::module m2 = m.def_submodule("sub", "A submodule of 'example'");
pybind11::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
.. cpp:function:: template <typename Func, typename ... Extra> module& module::def(const char *name, Func && f, Extra && ... extra)
Create Python binding for a new function within the module scope. ``Func``
can be a plain C++ function, a function pointer, or a lambda function. For
details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
.. _extras:
Passing extra arguments to the def function
===========================================
.. class:: arg
.. function:: arg::arg(const char *name)
.. function:: template <typename T> arg_v arg::operator=(T &&value)
.. class:: arg_v : public arg
Represents a named argument with a default value
.. class:: sibling
Used to specify a handle to an existing sibling function; used internally
to implement function overloading in :func:`module::def` and
:func:`class_::def`.
.. function:: sibling::sibling(handle handle)
.. class doc
This is class is internally used by pybind11.
.. function:: doc::doc(const char *value)
Create a new docstring with the specified value
.. class name
This is class is internally used by pybind11.
.. function:: name::name(const char *value)
Used to specify the function name
|