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