pybind11/docs/reference.rst

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