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
|
| |