Reference - pybind11 documentation (original) (raw)

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 first argument and it should not be in quotes. The second macro argument defines a variable of typepy::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!";
});

}

The third macro argument is optional (available since 2.13.0), and can be used to mark the extension module as safe to run without the GIL under a free-threaded CPython interpreter. Passing this argument has no effect on other interpreters.

PYBIND11_MODULE(example, m, py::mod_gil_not_used()) { m.doc() = "pybind11 example module safe to run without the GIL";

// Add bindings here
m.def("foo", []() {
    return "Hello, Free-threaded World!";
});

}

Convenience classes for arbitrary Python types#

Common member functions#

template<typename Derived>
class object_api : public pyobject_tag#

A mixin class which adds common functions to handle, object and various accessors. The only requirement for Derived is to implement PyObject *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.

iterator end() const#

Return a sentinel which ends iteration.

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 a handle or objectsubclass causes a corresponding call to __getitem__. Assigning a handleor object subclass causes a call to __setitem__.

item_accessor operator[](object &&key) const#

See above (the only difference is that the key’s reference is stolen)

item_accessor operator[](const char *key) const#

See above (the only difference is that the 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 a handle or objectsubclass causes a corresponding call to getattr. Assigning a handleor object subclass causes a call to setattr.

obj_attr_accessor attr(object &&key) const#

See above (the only difference is that the key’s reference is stolen)

str_attr_accessor attr(const char *key) const#

See above (the only difference is that the key is provided as a string literal)

args_proxy operator*() const#

Matches * unpacking in Python, e.g. to unpack arguments out of a tupleor list 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>
bool contains(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>
object operator()(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 a object and may need to be converted back into a Python object using handle::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, a error_already_set exception is thrown.

inline bool is(object_api const &other) const#

Equivalent to obj is other in Python.

inline bool is_none() const#

Equivalent to obj is None in Python.

inline 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__.

inline ssize_t ref_count() const#

Return the object’s current reference count.

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.

See also

The object class inherits from handle and adds automatic reference counting features.

Subclassed by args_proxy, kwargs_proxy, object

Public Functions

handle() = default#

The default constructor creates a handle with a nullptr-valued pointer.

template<typename T, detail::enable_if_t<detail::is_pyobj_ptr_or_nullptr_t<T>::value, int> = 0>
inline handle(T ptr)#

Enable implicit conversion from PyObject * and nullptr. Not using [handle(PyObject *ptr)](#classhandle) to avoid implicit conversion from 0.

template<typename T, detail::enable_if_t<detail::all_of<detail::none_of<std::is_base_of<handle, T>, detail::is_pyobj_ptr_or_nullptr_t<T>>, std::is_convertible<T, PyObject*>>::value, int> = 0>
inline handle(T &obj)#

Enable implicit conversion through T::operator PyObject *().

inline PyObject *ptr() const#

Return the underlying PyObject * pointer.

inline 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 from handle and calls this function automatically. Returns a reference to itself.

inline 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 from handle and calls this function automatically. Returns a reference to itself.

template<typename T>
T cast() const#

Attempt to cast the Python object into the given C++ type. A cast_errorwill be throw upon failure.

inline explicit operator bool() const#

Return true when the handle wraps a valid Python object.

inline bool operator==(const handle &h) const#

Deprecated: Check that the underlying pointers are the same. Equivalent to obj1 is obj2 in Python.

With reference counting#

class object : public handle#

Holds a reference to a Python object (with reference counting)

Like 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 handle, it optionally increases the object’s reference count upon construction, and it_always_ decreases the reference count when the object instance goes out of scope and is destructed. When using object instances consistently, it is much easier to get reference counting right at the first attempt.

Subclassed by Optional< T >, Union< Types >, anyset, bool_, buffer, bytearray, bytes, capsule, dict, dtype, ellipsis, exception< type >, float_, function, generic_type, int_, iterable, iterator, list, memoryview, module_, none, sequence, slice, staticmethod, str, tuple, type, weakref

Public Functions

inline object(const object &o)#

Copy constructor; always increases the reference count.

inline object(object &&other) noexcept#

Move constructor; steals the object from other and preserves its reference count.

inline ~object()#

Destructor; automatically calls [handle::dec_ref()](#classhandle%5F1a03747f7b62a7b61eb7d9d1df25bfa7c4)

inline handle release()#

Resets the internal pointer to nullptr without decreasing the object’s reference count. The function returns a raw handle to the original Python object.

template<typename T>
T reinterpret_borrow(handle h)#

Declare that a handle or PyObject * is a certain type and borrow the reference. The target type T must be object 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_borrowpy::object(p); // or py::tuple t = reinterpret_borrowpy::tuple(p); // <-- p must be already be a tuple

template<typename T>
T reinterpret_steal(handle h)#

Like reinterpret_borrow(), but steals the reference.

PyObject *p = PyObject_Str(obj); py::str s = reinterpret_stealpy::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

inline explicit module_(const char *name, const char *doc = nullptr)#

Create a new top-level Python module with the given name and docstring.

Create Python binding for a new function within the module scope. Funccan be a plain C++ function, a function pointer, or a lambda function. For details on the Extra&& ... extra argument, see section Passing extra arguments to def or class_.

inline 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'");

inline void reload()#

Reload the module or throws [error_already_set](#classerror%5F%5Falready%5F%5Fset).

inline 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

static inline module_ import(const char *name)#

Import and return a module or throws [error_already_set](#classerror%5F%5Falready%5F%5Fset).

static inline module_ create_extension_module(const char *name, const char *doc, module_def *def, mod_gil_not_used gil_not_used = mod_gil_not_used(false))#

Create a new top-level module that can be used as the main module of a C extension.

def should point to a statically allocated module_def.

group pytypes

Functions

template<typename Unsigned>
Unsigned as_unsigned(PyObject *o)#

template<typename ...Args>
constexpr bool args_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*().

Subclassed by Iterator< T >

Public Static Functions

static inline iterator sentinel()#

The value which marks the end of the iteration. it == iterator::sentinel()is equivalent to catching StopIteration in Python.

void foo(py::iterator it) { while (it != py::iterator::sentinel()) { // use *it ++it; } }

class type : public object#

Subclassed by Type< T >

Public Static Functions

static inline handle handle_of(handle h)#

Return a type handle from a handle or an object.

static inline type of(handle h)#

Return a type object from a handle or an object.

template<typename T>
static handle handle_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>
static inline type of()#

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

class iterable : public object#

Subclassed by Iterable< T >

class str : public object#

Public Functions

inline explicit str(handle h)#

Return a string representation of the object. This is analogous to the str() function in Python.

class bytes : public object#

class bytearray : public object#

class none : public object#

Subclassed by Never, NoReturn

class ellipsis : public object#

class bool_ : public object#

Subclassed by TypeGuard< T >, TypeIs< T >

class int_ : public object#

class float_ : public object#

class weakref : public object#

class slice : public object#

class capsule : public object#

class tuple : public object#

Subclassed by Tuple< type_caster< Ts >… >, Tuple< Types >, args

class dict : public object#

Subclassed by Dict< K, V >, kwargs

class sequence : public object#

class list : public object#

Subclassed by List< T >

class args : public tuple#

class kwargs : public dict#

class anyset : public object#

Subclassed by frozenset, set

class set : public anyset#

Subclassed by Set< T >

class frozenset : public anyset#

class function : public object#

Subclassed by Callable< Return(Args…)>, cpp_function

class staticmethod : public object#

class buffer : public object#

Subclassed by array

class memoryview : public object#

Public Functions

inline explicit memoryview(const buffer_info &info)#

Creates memoryview from buffer_info.

buffer_info must be created from buffer::request(). Otherwise throws an exception.

For creating a memoryview from objects that support buffer protocol, use memoryview(const object& obj) instead of this constructor.

Public Static Functions

static 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 of ptr and format, which MUST outlive the memoryview constructed here.

See also: Python C API documentation for PyMemoryView_FromBuffer.

Parameters:

static inline 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 of mem, which MUST outlive the memoryview constructed here.

See also: Python C API documentation for PyMemoryView_FromBuffer.

Convenience functions converting to Python types#

template<return_value_policy policy = return_value_policy::automatic_reference, typename ...Args>
tuple make_tuple(Args&&... args_)#

Makes a python iterator from a first and past-the-end C++ InputIterator.

Warning

doxygenfunction: Unable to resolve function “make_iterator” with arguments (Type&, Extra&&…) in doxygen xml output for project “pybind11” from directory: .build/doxygenxml/. Potential matches:

Makes a python iterator over the keys (.first) of a iterator over pairs from a first and past-the-end InputIterator.

Warning

doxygenfunction: Unable to resolve function “make_key_iterator” with arguments (Type&, Extra&&…) in doxygen xml output for project “pybind11” from directory: .build/doxygenxml/. Potential matches:

Makes a python iterator over the values (.second) of a iterator over pairs from a first and past-the-end InputIterator.

Warning

doxygenfunction: Unable to resolve function “make_value_iterator” with arguments (Type&, Extra&&…) in doxygen xml output for project “pybind11” from directory: .build/doxygenxml/. Potential matches:

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!"; }); }

inline void initialize_interpreter(bool init_signal_handlers = true, int argc = 0, const char *const *argv = nullptr, bool add_program_dir_to_path = 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 init_signal_handlers 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.)

The remaining optional parameters, argc, argv, and add_program_dir_to_path are used to populate sys.argv and sys.path. See the PySys_SetArgvEx documentation for details.

inline 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() and finalize_interpreter(). This a move-only guard and only a single instance can exist.

See initialize_interpreter() for a discussion of its constructor arguments.

#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 make py::call_guard easier to make.

m.def("noisy_func", &noisy_func, py::call_guard<scoped_ostream_redirect, scoped_estream_redirect>());

inline class_detail::OstreamRedirect\ add_ostream_redirect(module_ m, const 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

inline 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>
bool isinstance(handle obj)#

Return true if obj is an instance of T. Type T must be a subclass ofobject or a class which was exposed to Python as py::class_<T>.

inline bool isinstance(handle obj, handle type)#

Return true if obj is an instance of the type.

inline bool hasattr(handle obj, handle name)#

inline bool hasattr(handle obj, const char *name)#

inline void delattr(handle obj, handle name)#

inline void delattr(handle obj, const char *name)#

inline object getattr(handle obj, handle name)#

inline object getattr(handle obj, const char *name)#

inline object getattr(handle obj, handle name, handle default_)#

inline object getattr(handle obj, const char *name, handle default_)#

inline void setattr(handle obj, handle name, handle value)#

inline void setattr(handle obj, const char *name, handle value)#

inline ssize_t hash(handle obj)#

inline size_t len(handle h)#

Get the length of a Python object.

inline size_t len_hint(handle h)#

Get the length hint of a Python object. Returns 0 when this cannot be determined.

inline str repr(handle h)#

inline iterator iter(handle obj)#

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 toPYBIND11_OVERRIDE_NAME, except that it throws if no override can be found.

template<class T>
function get_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.

Returns:

The Python method by this name from the object or an empty function wrapper.

Exceptions#

class error_already_set : public std::exception#

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

inline error_already_set()#

Fetches the current Python exception (using PyErr_Fetch()), which will clear the current Python error indicator.

inline const char *what() const noexcept override#

The what() result is built lazily on demand. WARNING: This member function needs to acquire the Python GIL. This can lead to crashes (undefined behavior) if the Python interpreter is finalizing.

inline void restore()#

Restores the currently-held Python error (which will clear the Python error indicator first if already set). NOTE: This member function will always restore the normalized exception, which may or may not be the original Python exception. WARNING: The GIL must be held when this member function is called!

inline void discard_as_unraisable(object err_context)#

If it is impossible to raise the currently-held error, such as in a 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.

inline void discard_as_unraisable(const char *err_context)#

An alternate version of [discard_as_unraisable()](#classerror%5F%5Falready%5F%5Fset%5F1a7dad9b92f8d2132d1f627ea9329c7aeb), where a string provides information on the location of the error. For example, __func__ could be helpful. WARNING: The GIL must be held when this member function is called!

inline bool matches(handle exc) const#

Check if the currently trapped error type matches the given Python exception class (or a subclass thereof). May also be passed a tuple to search for any exception class matches in the given tuple.

class builtin_exception : public std::runtime_error#

C++ bindings of builtin Python exceptions.

Subclassed by attribute_error, buffer_error, cast_error, import_error, index_error, key_error, reference_cast_error, stop_iteration, type_error, value_error

Public Functions

virtual void set_error() const = 0#

Set the error using the Python C API.

Literals#

namespace literals#