15c15
< .. function:: PYBIND11_PLUGIN(const char *name)
---
> .. doxygendefine:: PYBIND11_PLUGIN
17,29d16
< 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();
< }
<
34a22,27
> Common member functions
> -----------------------
>
> .. doxygenclass:: object_api
> :members:
>
38c31,32
< .. class:: handle
---
> .. doxygenclass:: handle
> :members:
40,138d33
< 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.
<
142c37,38
< .. class:: object : public handle
---
> .. doxygenclass:: object
> :members:
144,150c40
< 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.
---
> .. doxygenfunction:: reinterpret_borrow
152c42
< .. function:: object::object(const object &o)
---
> .. doxygenfunction:: reinterpret_steal
154,181d43
< 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()`.
<
184a47,48
> .. doxygenclass:: module
> :members:
186c50,51
< .. class:: module : public object
---
> .. doxygengroup:: pytypes
> :members:
188,208d52
< .. 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`.
<
211,212c55,56
< Passing extra arguments to the def function
< ===========================================
---
> Passing extra arguments to ``def`` or ``class_``
> ================================================
214c58,59
< .. class:: arg
---
> .. doxygengroup:: annotations
> :members:
216c61,62
< .. function:: arg::arg(const char *name)
---
> Python build-in functions
> =========================
218c64,65
< .. function:: template <typename T> arg_v arg::operator=(T &&value)
---
> .. doxygengroup:: python_builtins
> :members:
220c67,68
< .. class:: arg_v : public arg
---
> Exceptions
> ==========
222c70,71
< Represents a named argument with a default value
---
> .. doxygenclass:: error_already_set
> :members:
224c73,74
< .. class:: sibling
---
> .. doxygenclass:: builtin_exception
> :members:
226,228d75
< Used to specify a handle to an existing sibling function; used internally
< to implement function overloading in :func:`module::def` and
< :func:`class_::def`.
230c77,78
< .. function:: sibling::sibling(handle handle)
---
> Literals
> ========
232,247c80
< .. 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
<
---
> .. doxygennamespace:: literals
< .. function:: PYBIND11_PLUGIN(const char *name)
---
> .. doxygendefine:: PYBIND11_PLUGIN
17,29d16
< 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();
< }
<
34a22,27
> Common member functions
> -----------------------
>
> .. doxygenclass:: object_api
> :members:
>
38c31,32
< .. class:: handle
---
> .. doxygenclass:: handle
> :members:
40,138d33
< 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.
<
142c37,38
< .. class:: object : public handle
---
> .. doxygenclass:: object
> :members:
144,150c40
< 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.
---
> .. doxygenfunction:: reinterpret_borrow
152c42
< .. function:: object::object(const object &o)
---
> .. doxygenfunction:: reinterpret_steal
154,181d43
< 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()`.
<
184a47,48
> .. doxygenclass:: module
> :members:
186c50,51
< .. class:: module : public object
---
> .. doxygengroup:: pytypes
> :members:
188,208d52
< .. 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`.
<
211,212c55,56
< Passing extra arguments to the def function
< ===========================================
---
> Passing extra arguments to ``def`` or ``class_``
> ================================================
214c58,59
< .. class:: arg
---
> .. doxygengroup:: annotations
> :members:
216c61,62
< .. function:: arg::arg(const char *name)
---
> Python build-in functions
> =========================
218c64,65
< .. function:: template <typename T> arg_v arg::operator=(T &&value)
---
> .. doxygengroup:: python_builtins
> :members:
220c67,68
< .. class:: arg_v : public arg
---
> Exceptions
> ==========
222c70,71
< Represents a named argument with a default value
---
> .. doxygenclass:: error_already_set
> :members:
224c73,74
< .. class:: sibling
---
> .. doxygenclass:: builtin_exception
> :members:
226,228d75
< Used to specify a handle to an existing sibling function; used internally
< to implement function overloading in :func:`module::def` and
< :func:`class_::def`.
230c77,78
< .. function:: sibling::sibling(handle handle)
---
> Literals
> ========
232,247c80
< .. 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
<
---
> .. doxygennamespace:: literals