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
|
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
|
17.. _core_types: 18 19Convenience classes for arbitrary Python types 20============================================== 21
|
22Common member functions 23----------------------- 24 25.. doxygenclass:: object_api 26 :members: 27 |
28Without reference counting 29-------------------------- 30
|
38.. class:: handle
|
31.. doxygenclass:: handle 32 :members: |
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
|
34With reference counting 35----------------------- 36
|
142.. class:: object : public handle
|
37.. doxygenclass:: object 38 :members: |
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 |
41
|
152.. function:: object::object(const object &o)
|
42.. doxygenfunction:: reinterpret_steal |
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
|
44Convenience classes for specific Python types 45============================================= 46
|
47.. doxygenclass:: module 48 :members: |
49
|
186.. class:: module : public object
|
50.. doxygengroup:: pytypes 51 :members: |
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
|
53.. _extras: 54
|
211Passing extra arguments to the def function
212===========================================
|
55Passing extra arguments to ``def`` or ``class_`` 56================================================ |
57
|
214.. class:: arg
|
58.. doxygengroup:: annotations 59 :members: |
60
|
216.. function:: arg::arg(const char *name)
|
61Python build-in functions 62========================= |
63
|
218.. function:: template <typename T> arg_v arg::operator=(T &&value)
|
64.. doxygengroup:: python_builtins 65 :members: |
66
|
220.. class:: arg_v : public arg
|
67Exceptions 68========== |
69
|
222 Represents a named argument with a default value
|
70.. doxygenclass:: error_already_set 71 :members: |
72
|
224.. class:: sibling
|
73.. doxygenclass:: builtin_exception 74 :members: |
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`.
|
76
|
230.. function:: sibling::sibling(handle handle)
|
77Literals 78======== |
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 |
|