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_MODULE
(name, variable)¶ This macro creates the entry point that will be invoked when the Python interpreter imports an extension module. The module name is given as the fist argument and it should not be in quotes. The second macro argument defines a variable of type
py::module_
which can be used to initialize the module.The entry point is marked as “maybe unused” to aid dead-code detection analysis: since the entry point is typically only looked up at runtime and not referenced during translation, it would otherwise appear as unused (“dead”) code.
PYBIND11_MODULE(example, m) { m.doc() = "pybind11 example module"; // Add bindings here m.def("foo", []() { return "Hello, World!"; }); }
Convenience classes for arbitrary Python types¶
Common member functions¶
-
template<typename
Derived
>
classobject_api
: public pyobject_tag¶ A mixin class which adds common functions to
handle
,object
and various accessors. The only requirement forDerived
is to implementPyObject *Derived::ptr() const
.Public Functions
-
iterator
begin
() const¶ Return an iterator equivalent to calling
iter()
in Python. The object must be a collection which supports the iteration protocol.
-
item_accessor
operator[]
(handle key) const¶ Return an internal functor to invoke the object’s sequence protocol. Casting the returned
detail::item_accessor
instance to ahandle
orobject
subclass causes a corresponding call to__getitem__
. Assigning ahandle
orobject
subclass causes a call to__setitem__
.
-
item_accessor
operator[]
(const char *key) const¶ See above (the only difference is that they key is provided as a string literal)
-
obj_attr_accessor
attr
(handle key) const¶ Return an internal functor to access the object’s attributes. Casting the returned
detail::obj_attr_accessor
instance to ahandle
orobject
subclass causes a corresponding call togetattr
. Assigning ahandle
orobject
subclass causes a call tosetattr
.
-
str_attr_accessor
attr
(const char *key) const¶ See above (the only difference is that they key is provided as a string literal)
-
args_proxy
operator*
() const¶ Matches * unpacking in Python, e.g. to unpack arguments out of a
tuple
orlist
for a function call. Applying another * to the result yields ** unpacking, e.g. to unpack a dict as function keyword arguments. See Calling Python functions.
-
template<typename
T
>
boolcontains
(T &&item) const¶ Check if the given item is contained within this object, i.e.
item in obj
.
-
template<return_value_policy
policy
= return_value_policy::automatic_reference, typename ...Args
>
objectoperator()
(Args&&... args) const¶ Assuming the Python object is a function or implements the
__call__
protocol,operator()
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.
-
bool
is
(object_api const &other) const¶ Equivalent to
obj is other
in Python.
-
bool
is_none
() const¶ Equivalent to
obj is None
in Python.
-
bool
equal
(object_api const &other) const¶ Equivalent to obj == other in Python.
-
str_attr_accessor
doc
() const¶ Get or set the object’s docstring, i.e.
obj.__doc__
.
-
int
ref_count
() const¶ Return the object’s current reference count.
-
iterator
Without reference counting¶
-
class
handle
: public detail::object_api<handle>¶ Holds a reference to a Python object (no reference counting)
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.Subclassed by args_proxy, kwargs_proxy, object
Public Functions
-
handle
() = default¶ The default constructor creates a handle with a
nullptr
-valued pointer.
-
handle
(PyObject *ptr)¶ Creates a
handle
from the given raw Python object pointer.
-
PyObject *
ptr
() const¶ Return the underlying
PyObject *
pointer.
-
const 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 &
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
>
Tcast
() const¶ Attempt to cast the Python object into the given C++ type. A
cast_error
will be throw upon failure.
-
operator bool
() const¶ Return
true
when thehandle
wraps a valid Python object.
-
With reference counting¶
-
class
object
: public handle¶ Holds a reference to a Python object (with reference counting)
Like
handle
, theobject
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.Subclassed by bool_, buffer, bytearray, bytes, capsule, dict, dtype, ellipsis, exception< type >, float_, function, generic_type, int_, iterable, iterator, list, memoryview, module_, none, sequence, set, slice, staticmethod, str, tuple, type, weakref
Public Functions
-
object
(object &&other) noexcept¶ Move constructor; steals the object from
other
and preserves its reference count.
-
~object
()¶ Destructor; automatically calls
handle::dec_ref()
-
-
template<typename
T
>
Treinterpret_borrow
(handle h)¶ Declare that a
handle
orPyObject *
is a certain type and borrow the reference. The target typeT
must beobject
or one of its derived classes. The function doesn’t do any conversions or checks. It’s up to the user to make sure that the target type is correct.PyObject *p = PyList_GetItem(obj, index); py::object o = reinterpret_borrow<py::object>(p); // or py::tuple t = reinterpret_borrow<py::tuple>(p); // <-- `p` must be already be a `tuple`
-
template<typename
T
>
Treinterpret_steal
(handle h)¶ Like
reinterpret_borrow()
, but steals the reference.PyObject *p = PyObject_Str(obj); py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`
Convenience classes for specific Python types¶
-
class
module_
: public object¶ Wrapper for Python extension modules.
Public Functions
-
module_
(const char *name, const char *doc = nullptr)¶ Create a new top-level Python module with the given name and docstring.
-
template<typename
Func
, typename ...Extra
>
module_ &def
(const char *name_, Func &&f, const 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 def or class_.
-
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.
py::module_ m("example", "pybind11 example plugin"); py::module_ m2 = m.def_submodule("sub", "A submodule of 'example'"); py::module_ m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");
-
void
reload
()¶ Reload the module or throws
error_already_set
.
-
void
add_object
(const char *name, handle obj, bool overwrite = false)¶ Adds an object to the module using the given name. Throws if an object with the given name already exists.
overwrite
should almost always be false: attempting to overwrite objects that pybind11 has established will, in most cases, break things.
Public Static Functions
-
module_
import
(const char *name)¶ Import and return a module or throws
error_already_set
.
-
-
group
pytypes
Functions
-
template<typename ...
Args
>
constexpr boolargs_are_all_keyword_or_ds
()¶
-
class
iterator
: public object¶ - #include <pytypes.h>
Wraps a Python iterator so that it can also be used as a C++ input iterator
Caveat: copying an iterator does not (and cannot) clone the internal state of the Python iterable. This also applies to the post-increment operator. This iterator should only be used to retrieve the current value using
operator*()
.
-
class
type
: public object¶ Public Static Functions
-
template<typename
T
>
handlehandle_of
()¶ Convert C++ type to handle if previously registered. Does not convert standard types, like int, float. etc. yet. See https://github.com/pybind/pybind11/issues/2486
-
template<typename
T
>
typeof
()¶ Convert C++ type to type if previously registered. Does not convert standard types, like int, float. etc. yet. See https://github.com/pybind/pybind11/issues/2486
-
template<typename
-
class
memoryview
: public object¶ Public Functions
-
memoryview
(const buffer_info &info)¶ Creates
memoryview
frombuffer_info
.buffer_info
must be created frombuffer::request()
. Otherwise throws an exception.For creating a
memoryview
from objects that support buffer protocol, usememoryview(const object& obj)
instead of this constructor.
Public Static Functions
-
memoryview
from_buffer
(void *ptr, ssize_t itemsize, const char *format, detail::any_container<ssize_t> shape, detail::any_container<ssize_t> strides, bool readonly = false)¶ Creates
memoryview
from static buffer.This method is meant for providing a
memoryview
for C/C++ buffer not managed by Python. The caller is responsible for managing the lifetime ofptr
andformat
, which MUST outlive the memoryview constructed here.See also: Python C API documentation for PyMemoryView_FromBuffer.
- param ptr
Pointer to the buffer.
- param itemsize
Byte size of an element.
- param format
Pointer to the null-terminated format string. For homogeneous Buffers, this should be set to
format_descriptor<T>::value
.- param shape
Shape of the tensor (1 entry per dimension).
- param strides
Number of bytes between adjacent entries (for each per dimension).
- param readonly
Flag to indicate if the underlying storage may be written to.
-
memoryview
from_memory
(void *mem, ssize_t size, bool readonly = false)¶ Creates
memoryview
from static memory.This method is meant for providing a
memoryview
for C/C++ buffer not managed by Python. The caller is responsible for managing the lifetime ofmem
, which MUST outlive the memoryview constructed here.This method is not available in Python 2.
See also: Python C API documentation for PyMemoryView_FromBuffer.
-
-
template<typename ...
Convenience functions converting to Python types¶
-
template<return_value_policy
policy
= return_value_policy::automatic_reference, typename ...Args
>
tuplemake_tuple
(Args&&... args_)¶
-
template<return_value_policy
Policy
= return_value_policy::reference_internal, typenameIterator
, typenameSentinel
, typename ...Extra
>
iteratormake_iterator
(Iterator first, Sentinel last, Extra&&... extra)¶ Makes a python iterator from a first and past-the-end C++ InputIterator.
-
template<return_value_policy
Policy
= return_value_policy::reference_internal, typenameType
, typename ...Extra
>
iteratormake_iterator
(Type &value, Extra&&... extra)¶ Makes an iterator over values of an stl container or other container supporting
std::begin()
/std::end()
-
template<return_value_policy
Policy
= return_value_policy::reference_internal, typenameIterator
, typenameSentinel
, typename ...Extra
>
iteratormake_key_iterator
(Iterator first, Sentinel last, Extra&&... extra)¶ Makes an python iterator over the keys (
.first
) of a iterator over pairs from a first and past-the-end InputIterator.
Passing extra arguments to def
or class_
¶
-
group
annotations
-
struct
is_method
¶ - #include <attr.h>
Annotation for methods.
-
struct
is_operator
¶ - #include <attr.h>
Annotation for operators.
-
struct
is_final
¶ - #include <attr.h>
Annotation for classes that cannot be subclassed.
-
struct
scope
¶ - #include <attr.h>
Annotation for parent scope.
-
struct
doc
¶ - #include <attr.h>
Annotation for documentation.
-
struct
name
¶ - #include <attr.h>
Annotation for function names.
-
struct
sibling
¶ - #include <attr.h>
Annotation indicating that a function is an overload associated with a given “sibling”.
-
template<typename
T
>
structbase
¶ - #include <attr.h>
Annotation indicating that a class derives from another given type.
-
template<size_t
Nurse
, size_tPatient
>
structkeep_alive
¶ - #include <attr.h>
Keep patient alive while nurse lives.
-
struct
multiple_inheritance
¶ - #include <attr.h>
Annotation indicating that a class is involved in a multiple inheritance relationship.
-
struct
dynamic_attr
¶ - #include <attr.h>
Annotation which enables dynamic attributes, i.e. adds
__dict__
to a class.
-
struct
buffer_protocol
¶ - #include <attr.h>
Annotation which enables the buffer protocol for a type.
-
struct
metaclass
¶ - #include <attr.h>
Annotation which requests that a special metaclass is created for a type.
-
struct
module_local
¶ - #include <attr.h>
Annotation that marks a class as local to the module:
-
struct
arithmetic
¶ - #include <attr.h>
Annotation to mark enums as an arithmetic type.
-
struct
prepend
¶ - #include <attr.h>
Mark a function for addition at the beginning of the existing overload chain instead of the end.
-
template<typename ...
Ts
>
structcall_guard
¶ - #include <attr.h>
A call policy which places one or more guard variables (
Ts...
) around the function call.For example, this definition:
m.def("foo", foo, py::call_guard<T>());
is equivalent to the following pseudocode:
m.def("foo", [](args...) { T scope_guard; return foo(args...); // forwarded arguments });
-
template<>
structcall_guard
<>¶
-
struct
arg_v
: public arg¶ - #include <cast.h>
Annotation for arguments with values
Public Functions
-
template<typename
T
>arg_v
(const char *name, T &&x, const char *descr = nullptr)¶ Direct construction with name, default, and description.
-
template<typename
T
>arg_v
(const arg &base, T &&x, const char *descr = nullptr)¶ Called internally when invoking
py::arg("a") = value
-
arg_v &
noconvert
(bool flag = true)¶ Same as
arg::noconvert()
, but returns *this as arg_v&, not arg&.
-
template<typename
-
struct
kw_only
¶ - #include <cast.h>
Annotation indicating that all following arguments are keyword-only; the is the equivalent of an unnamed ‘*’ argument (in Python 3)
-
struct
pos_only
¶ - #include <cast.h>
Annotation indicating that all previous arguments are positional-only; the is the equivalent of an unnamed ‘/’ argument (in Python 3.8)
-
struct
Embedding the interpreter¶
-
PYBIND11_EMBEDDED_MODULE
(name, variable)¶ Add a new module to the table of builtins for the interpreter. Must be defined in global scope. The first macro parameter is the name of the module (without quotes). The second parameter is the variable which will be used as the interface to add functions and classes to the module.
PYBIND11_EMBEDDED_MODULE(example, m) { // ... initialize functions and classes here m.def("foo", []() { return "Hello, World!"; }); }
-
void
initialize_interpreter
(bool init_signal_handlers = true)¶ Initialize the Python interpreter. No other pybind11 or CPython API functions can be called before this is done; with the exception of
PYBIND11_EMBEDDED_MODULE
. The optional parameter can be used to skip the registration of signal handlers (see the Python documentation for details). Calling this function again after the interpreter has already been initialized is a fatal error.If initializing the Python interpreter fails, then the program is terminated. (This is controlled by the CPython runtime and is an exception to pybind11’s normal behavior of throwing exceptions on errors.)
-
void
finalize_interpreter
()¶ Shut down the Python interpreter. No pybind11 or CPython API functions can be called after this. In addition, pybind11 objects must not outlive the interpreter:
{ // BAD py::initialize_interpreter(); auto hello = py::str("Hello, World!"); py::finalize_interpreter(); } // <-- BOOM, hello's destructor is called after interpreter shutdown { // GOOD py::initialize_interpreter(); { // scoped auto hello = py::str("Hello, World!"); } // <-- OK, hello is cleaned up properly py::finalize_interpreter(); } { // BETTER py::scoped_interpreter guard{}; auto hello = py::str("Hello, World!"); }
Warning
The interpreter can be restarted by calling
initialize_interpreter()
again. Modules created using pybind11 can be safely re-initialized. However, Python itself cannot completely unload binary extension modules and there are several caveats with regard to interpreter restarting. All the details can be found in the CPython documentation. In short, not all interpreter memory may be freed, either due to reference cycles or user-created global data.
-
class
scoped_interpreter
¶ Scope guard version of
initialize_interpreter()
andfinalize_interpreter()
. This a move-only guard and only a single instance can exist.#include <pybind11/embed.h> int main() { py::scoped_interpreter guard{}; py::print(Hello, World!); } // <-- interpreter shutdown
Redirecting C++ streams¶
-
class
scoped_ostream_redirect
¶ This a move-only guard that redirects output.
#include <pybind11/iostream.h> ... { py::scoped_ostream_redirect output; std::cout << "Hello, World!"; // Python stdout } // <-- return std::cout to normal
You can explicitly pass the c++ stream and the python object, for example to guard stderr instead.
{ py::scoped_ostream_redirect output{std::cerr, py::module::import("sys").attr("stderr")}; std::cout << "Hello, World!"; }
Subclassed by scoped_estream_redirect
-
class
scoped_estream_redirect
: public scoped_ostream_redirect¶ Like
scoped_ostream_redirect
, but redirects cerr by default. This class is provided primary to makepy::call_guard
easier to make.m.def("noisy_func", &noisy_func, py::call_guard<scoped_ostream_redirect, scoped_estream_redirect>());
-
class_<detail::OstreamRedirect>
add_ostream_redirect
(module_ m, std::string name = "ostream_redirect")¶ This is a helper function to add a C++ redirect context manager to Python instead of using a C++ guard. To use it, add the following to your binding code:
#include <pybind11/iostream.h> ... py::add_ostream_redirect(m, "ostream_redirect");
You now have a Python context manager that redirects your output:
with m.ostream_redirect(): m.print_to_cout_function()
This manager can optionally be told which streams to operate on:
with m.ostream_redirect(stdout=true, stderr=true): m.noisy_function_with_error_printing()
Python built-in functions¶
-
group
python_builtins
Unless stated otherwise, the following C++ functions behave the same as their Python counterparts.
Functions
-
dict
globals
()¶ Return a dictionary representing the global variables in the current execution frame, or
__main__.__dict__
if there is no frame (usually when the interpreter is embedded).
-
template<typename
T
, detail::enable_if_t<std::is_base_of<object, T>::value, int> = 0>
boolisinstance
(handle obj)¶ Return true if
obj
is an instance ofT
. TypeT
must be a subclass ofobject
or a class which was exposed to Python aspy::class_<T>
.
-
dict
Inheritance¶
See Object-oriented code and Classes for more detail.
-
PYBIND11_OVERRIDE
(ret_type, cname, fn, ...)¶ Macro to populate the virtual method in the trampoline class. This macro tries to look up the method from the Python side, deals with the Global Interpreter Lock (GIL) and necessary argument conversions to call this method and return the appropriate type. This macro should be used if the method name in C and in Python are identical. See Overriding virtual functions in Python for more information.
class PyAnimal : public Animal { public: // Inherit the constructors using Animal::Animal; // Trampoline (need one for each virtual function) std::string go(int n_times) override { PYBIND11_OVERRIDE_PURE( std::string, // Return type (ret_type) Animal, // Parent class (cname) go, // Name of function in C++ (must match Python name) (fn) n_times // Argument(s) (...) ); } };
-
PYBIND11_OVERRIDE_PURE
(ret_type, cname, fn, ...)¶ Macro for pure virtual functions, this function is identical to
PYBIND11_OVERRIDE
, except that it throws if no override can be found.
-
PYBIND11_OVERRIDE_NAME
(ret_type, cname, name, fn, ...)¶ Macro to populate the virtual method in the trampoline class. This macro tries to look up a method named ‘fn’ from the Python side, deals with the Global Interpreter Lock (GIL) and necessary argument conversions to call this method and return the appropriate type. See Overriding virtual functions in Python for more information. This macro should be used when the method name in C is not the same as the method name in Python. For example with
__str__
.std::string toString() override { PYBIND11_OVERRIDE_NAME( std::string, // Return type (ret_type) Animal, // Parent class (cname) "__str__", // Name of method in Python (name) toString, // Name of function in C++ (fn) ); }
-
PYBIND11_OVERRIDE_PURE_NAME
(ret_type, cname, name, fn, ...)¶ Macro for pure virtual functions, this function is identical to
PYBIND11_OVERRIDE_NAME
, except that it throws if no override can be found.
-
template<class
T
>
functionget_override
(const T *this_ptr, const char *name)¶ Try to retrieve a python method by the provided name from the instance pointed to by the this_ptr.
- this_ptr
The pointer to the object the overridden method should be retrieved for. This should be the first non-trampoline class encountered in the inheritance chain.
- name
The name of the overridden Python method to retrieve.
- return
The Python method by this name from the object or an empty function wrapper.
Exceptions¶
-
class
error_already_set
: public runtime_error¶ Fetch and hold an error which was already set in Python. An instance of this is typically thrown to propagate python-side errors back through C++ which can either be caught manually or else falls back to the function dispatcher (which then raises the captured error back to python).
Public Functions
-
error_already_set
()¶ Constructs a new exception from the current Python error indicator, if any. The current Python error indicator will be cleared.
-
void
restore
()¶ Give the currently-held error back to Python, if any. If there is currently a Python error already set it is cleared first. After this call, the current object no longer stores the error variables (but the
.what()
string is still available).
-
void
discard_as_unraisable
(object err_context)¶ If it is impossible to raise the currently-held error, such as in destructor, we can write it out using Python’s unraisable hook (sys.unraisablehook). The error context should be some object whose repr() helps identify the location of the error. Python already knows the type and value of the error, so there is no need to repeat that. For example, func could be helpful. After this call, the current object no longer stores the error variables, and neither does Python.
-
-
class
builtin_exception
: public runtime_error¶ C++ bindings of builtin Python exceptions.
Subclassed by buffer_error, cast_error, import_error, index_error, key_error, reference_cast_error, stop_iteration, type_error, value_error
Public Functions
-
void
set_error
() const = 0¶ Set the error using the Python C API.
-
void