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¶
-
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
module
in the function body and return the pointer to its underlying Python object at the end.PYBIND11_PLUGIN(example) { pybind11::module m("example", "pybind11 example plugin"); /// Set up bindings here return m.ptr(); }
Convenience classes for arbitrary Python types¶
Without reference counting¶
-
class
handle
¶ The
handle
class is a thin wrapper around an arbitrary Python object (i.e. aPyObject *
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.
-
const handle &
handle
::
inc_ref
() const¶ Manually increase the reference count of the Python object. Usually, it is preferable to use the
object
class which derives fromhandle
and calls this function automatically. Returns a reference to itself.
-
const handle &
handle
::
dec_ref
() const¶ Manually decrease the reference count of the Python object. Usually, it is preferable to use the
object
class which derives fromhandle
and calls this function automatically. Returns a reference to itself.
-
template<typename
T
>
Thandle
::
cast
() const¶ Attempt to cast the Python object into the given C++ type. A
cast_error
will be throw upon failure.
-
template<typename ...
Args
>
objecthandle
::
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 aobject
and may need to be converted back into a Python object usinghandle::cast()
.When some of the arguments cannot be converted to Python objects, the function will throw a
cast_error
exception. When the Python function call fails, aerror_already_set
exception is thrown.
With reference counting¶
-
class
object
: public handle¶ Like
handle
, the object class is a thin wrapper around an arbitrary Python object (i.e. aPyObject *
in Python’s C API). In contrast tohandle
, it optionally increases the object’s reference count upon construction, and it always decreases the reference count when theobject
instance goes out of scope and is destructed. When usingobject
instances consistently, it is much easier to get reference counting right at the first attempt.
-
object
::
object
(const handle &h, bool borrowed)¶ Creates a
object
from the givenhandle
. The reference count is only increased if theborrowed
parameter is set totrue
.
-
object
::
object
(PyObject *ptr, bool borrowed)¶ Creates a
object
from the given raw Python object pointer. The reference count is only increased if theborrowed
parameter is set totrue
.
-
object
::
object
(object &&other)¶ Move constructor; steals the object from
other
and preserves its reference count.
-
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.
-
object
::
~object
()¶ Destructor, which automatically calls
handle::dec_ref()
.
Convenience classes for specific Python types¶
-
module
::
module
(const char *name, const char *doc = nullptr)¶ Create a new top-level Python module with the given name and docstring
-
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.
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'");
-
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 theExtra&& ... extra
argument, see section Passing extra arguments to the def function.
Passing extra arguments to the def function¶
-
class
arg
¶
-
class
sibling
¶ Used to specify a handle to an existing sibling function; used internally to implement function overloading in
module::def()
andclass_::def()
.