diff options
Diffstat (limited to 'ext/pybind11/docs/reference.rst')
| -rw-r--r-- | ext/pybind11/docs/reference.rst | 235 |
1 files changed, 34 insertions, 201 deletions
diff --git a/ext/pybind11/docs/reference.rst b/ext/pybind11/docs/reference.rst index 542259eba..3d211f7e9 100644 --- a/ext/pybind11/docs/reference.rst +++ b/ext/pybind11/docs/reference.rst @@ -12,236 +12,69 @@ 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(); - } +.. doxygendefine:: PYBIND11_PLUGIN .. _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. +Common member functions +----------------------- -.. function:: template <typename ... Args> object handle::call(Args&&... args) const +.. doxygenclass:: object_api + :members: - 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`. +Without reference counting +-------------------------- - 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. +.. doxygenclass:: handle + :members: 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() +.. doxygenclass:: object + :members: - 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. +.. doxygenfunction:: reinterpret_borrow -.. function:: object::~object() - - Destructor, which automatically calls :func:`handle::dec_ref()`. +.. doxygenfunction:: reinterpret_steal Convenience classes for specific Python types ============================================= +.. doxygenclass:: module + :members: -.. 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`. +.. doxygengroup:: pytypes + :members: .. _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) +Passing extra arguments to ``def`` or ``class_`` +================================================ -.. class doc +.. doxygengroup:: annotations + :members: - This is class is internally used by pybind11. +Python build-in functions +========================= -.. function:: doc::doc(const char *value) +.. doxygengroup:: python_builtins + :members: - Create a new docstring with the specified value +Exceptions +========== -.. class name +.. doxygenclass:: error_already_set + :members: - This is class is internally used by pybind11. +.. doxygenclass:: builtin_exception + :members: -.. function:: name::name(const char *value) - Used to specify the function name +Literals +======== +.. doxygennamespace:: literals |