File: reference.rst

package info (click to toggle)
pybind11 2.0.1-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 1,640 kB
  • ctags: 2,200
  • sloc: cpp: 8,259; python: 3,109; ansic: 1,448; makefile: 182; sh: 53
file content (247 lines) | stat: -rw-r--r-- 8,338 bytes parent folder | download
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