reference.rst (11986:c12e4625ab56) reference.rst (12037:d28054ac6ec9)
1.. _reference:
2
3.. warning::
4
5 Please be advised that the reference documentation discussing pybind11
6 internals is currently incomplete. Please refer to the previous sections
7 and the pybind11 header files for the nitty gritty details.
8
9Reference
10#########
11
12Macros
13======
14
1.. _reference:
2
3.. warning::
4
5 Please be advised that the reference documentation discussing pybind11
6 internals is currently incomplete. Please refer to the previous sections
7 and the pybind11 header files for the nitty gritty details.
8
9Reference
10#########
11
12Macros
13======
14
15.. function:: PYBIND11_PLUGIN(const char *name)
15.. doxygendefine:: PYBIND11_PLUGIN
16
16
17 This macro creates the entry point that will be invoked when the Python
18 interpreter imports a plugin library. Please create a
19 :class:`module` in the function body and return the pointer to its
20 underlying Python object at the end.
21
22 .. code-block:: cpp
23
24 PYBIND11_PLUGIN(example) {
25 pybind11::module m("example", "pybind11 example plugin");
26 /// Set up bindings here
27 return m.ptr();
28 }
29
30.. _core_types:
31
32Convenience classes for arbitrary Python types
33==============================================
34
17.. _core_types:
18
19Convenience classes for arbitrary Python types
20==============================================
21
22Common member functions
23-----------------------
24
25.. doxygenclass:: object_api
26 :members:
27
35Without reference counting
36--------------------------
37
28Without reference counting
29--------------------------
30
38.. class:: handle
31.. doxygenclass:: handle
32 :members:
39
33
40 The :class:`handle` class is a thin wrapper around an arbitrary Python
41 object (i.e. a ``PyObject *`` in Python's C API). It does not perform any
42 automatic reference counting and merely provides a basic C++ interface to
43 various Python API functions.
44
45.. seealso::
46
47 The :class:`object` class inherits from :class:`handle` and adds automatic
48 reference counting features.
49
50.. function:: handle::handle()
51
52 The default constructor creates a handle with a ``nullptr``-valued pointer.
53
54.. function:: handle::handle(const handle&)
55
56 Copy constructor
57
58.. function:: handle::handle(PyObject *)
59
60 Creates a :class:`handle` from the given raw Python object pointer.
61
62.. function:: PyObject * handle::ptr() const
63
64 Return the ``PyObject *`` underlying a :class:`handle`.
65
66.. function:: const handle& handle::inc_ref() const
67
68 Manually increase the reference count of the Python object. Usually, it is
69 preferable to use the :class:`object` class which derives from
70 :class:`handle` and calls this function automatically. Returns a reference
71 to itself.
72
73.. function:: const handle& handle::dec_ref() const
74
75 Manually decrease the reference count of the Python object. Usually, it is
76 preferable to use the :class:`object` class which derives from
77 :class:`handle` and calls this function automatically. Returns a reference
78 to itself.
79
80.. function:: void handle::ref_count() const
81
82 Return the object's current reference count
83
84.. function:: handle handle::get_type() const
85
86 Return a handle to the Python type object underlying the instance
87
88.. function detail::accessor handle::operator[](handle key) const
89
90 Return an internal functor to invoke the object's sequence protocol.
91 Casting the returned ``detail::accessor`` instance to a :class:`handle` or
92 :class:`object` subclass causes a corresponding call to ``__getitem__``.
93 Assigning a :class:`handle` or :class:`object` subclass causes a call to
94 ``__setitem__``.
95
96.. function detail::accessor handle::operator[](const char *key) const
97
98 See the above function (the only difference is that they key is provided as
99 a string literal).
100
101.. function detail::accessor handle::attr(handle key) const
102
103 Return an internal functor to access the object's attributes.
104 Casting the returned ``detail::accessor`` instance to a :class:`handle` or
105 :class:`object` subclass causes a corresponding call to ``__getattr``.
106 Assigning a :class:`handle` or :class:`object` subclass causes a call to
107 ``__setattr``.
108
109.. function detail::accessor handle::attr(const char *key) const
110
111 See the above function (the only difference is that they key is provided as
112 a string literal).
113
114.. function operator handle::bool() const
115
116 Return ``true`` when the :class:`handle` wraps a valid Python object.
117
118.. function str handle::str() const
119
120 Return a string representation of the object. This is analogous to
121 the ``str()`` function in Python.
122
123.. function:: template <typename T> T handle::cast() const
124
125 Attempt to cast the Python object into the given C++ type. A
126 :class:`cast_error` will be throw upon failure.
127
128.. function:: template <typename ... Args> object handle::call(Args&&... args) const
129
130 Assuming the Python object is a function or implements the ``__call__``
131 protocol, ``call()`` invokes the underlying function, passing an arbitrary
132 set of parameters. The result is returned as a :class:`object` and may need
133 to be converted back into a Python object using :func:`handle::cast`.
134
135 When some of the arguments cannot be converted to Python objects, the
136 function will throw a :class:`cast_error` exception. When the Python
137 function call fails, a :class:`error_already_set` exception is thrown.
138
139With reference counting
140-----------------------
141
34With reference counting
35-----------------------
36
142.. class:: object : public handle
37.. doxygenclass:: object
38 :members:
143
39
144 Like :class:`handle`, the object class is a thin wrapper around an
145 arbitrary Python object (i.e. a ``PyObject *`` in Python's C API). In
146 contrast to :class:`handle`, it optionally increases the object's reference
147 count upon construction, and it *always* decreases the reference count when
148 the :class:`object` instance goes out of scope and is destructed. When
149 using :class:`object` instances consistently, it is much easier to get
150 reference counting right at the first attempt.
40.. doxygenfunction:: reinterpret_borrow
151
41
152.. function:: object::object(const object &o)
42.. doxygenfunction:: reinterpret_steal
153
43
154 Copy constructor; always increases the reference count
155
156.. function:: object::object(const handle &h, bool borrowed)
157
158 Creates a :class:`object` from the given :class:`handle`. The reference
159 count is only increased if the ``borrowed`` parameter is set to ``true``.
160
161.. function:: object::object(PyObject *ptr, bool borrowed)
162
163 Creates a :class:`object` from the given raw Python object pointer. The
164 reference count is only increased if the ``borrowed`` parameter is set to
165 ``true``.
166
167.. function:: object::object(object &&other)
168
169 Move constructor; steals the object from ``other`` and preserves its
170 reference count.
171
172.. function:: handle object::release()
173
174 Resets the internal pointer to ``nullptr`` without without decreasing the
175 object's reference count. The function returns a raw handle to the original
176 Python object.
177
178.. function:: object::~object()
179
180 Destructor, which automatically calls :func:`handle::dec_ref()`.
181
182Convenience classes for specific Python types
183=============================================
184
44Convenience classes for specific Python types
45=============================================
46
47.. doxygenclass:: module
48 :members:
185
49
186.. class:: module : public object
50.. doxygengroup:: pytypes
51 :members:
187
52
188.. function:: module::module(const char *name, const char *doc = nullptr)
189
190 Create a new top-level Python module with the given name and docstring
191
192.. function:: module module::def_submodule(const char *name, const char *doc = nullptr)
193
194 Create and return a new Python submodule with the given name and docstring.
195 This also works recursively, i.e.
196
197 .. code-block:: cpp
198
199 pybind11::module m("example", "pybind11 example plugin");
200 pybind11::module m2 = m.def_submodule("sub", "A submodule of 'example'");
201 pybind11::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
202
203.. cpp:function:: template <typename Func, typename ... Extra> module& module::def(const char *name, Func && f, Extra && ... extra)
204
205 Create Python binding for a new function within the module scope. ``Func``
206 can be a plain C++ function, a function pointer, or a lambda function. For
207 details on the ``Extra&& ... extra`` argument, see section :ref:`extras`.
208
209.. _extras:
210
53.. _extras:
54
211Passing extra arguments to the def function
212===========================================
55Passing extra arguments to ``def`` or ``class_``
56================================================
213
57
214.. class:: arg
58.. doxygengroup:: annotations
59 :members:
215
60
216.. function:: arg::arg(const char *name)
61Python build-in functions
62=========================
217
63
218.. function:: template <typename T> arg_v arg::operator=(T &&value)
64.. doxygengroup:: python_builtins
65 :members:
219
66
220.. class:: arg_v : public arg
67Exceptions
68==========
221
69
222 Represents a named argument with a default value
70.. doxygenclass:: error_already_set
71 :members:
223
72
224.. class:: sibling
73.. doxygenclass:: builtin_exception
74 :members:
225
75
226 Used to specify a handle to an existing sibling function; used internally
227 to implement function overloading in :func:`module::def` and
228 :func:`class_::def`.
229
76
230.. function:: sibling::sibling(handle handle)
77Literals
78========
231
79
232.. class doc
233
234 This is class is internally used by pybind11.
235
236.. function:: doc::doc(const char *value)
237
238 Create a new docstring with the specified value
239
240.. class name
241
242 This is class is internally used by pybind11.
243
244.. function:: name::name(const char *value)
245
246 Used to specify the function name
247
80.. doxygennamespace:: literals