diff options
Diffstat (limited to 'ext/pybind11/docs/reference.rst')
| -rw-r--r-- | ext/pybind11/docs/reference.rst | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/ext/pybind11/docs/reference.rst b/ext/pybind11/docs/reference.rst new file mode 100644 index 000000000..542259eba --- /dev/null +++ b/ext/pybind11/docs/reference.rst @@ -0,0 +1,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 + |