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

See also

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

handle::handle()

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

handle::handle(const handle&)

Copy constructor

handle::handle(PyObject *)

Creates a handle from the given raw Python object pointer.

PyObject *handle::ptr() const

Return the PyObject * underlying a handle.

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

void handle::ref_count() const

Return the object’s current reference count

handle handle::get_type() const

Return a handle to the Python type object underlying the instance

template<typename T>
T handle::cast() const

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

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

With reference counting

class object : public handle

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.

object::object(const object &o)

Copy constructor; always increases the reference count

object::object(const handle &h, bool borrowed)

Creates a object from the given handle. The reference count is only increased if the borrowed parameter is set to true.

object::object(PyObject *ptr, bool borrowed)

Creates a object from the given raw Python object pointer. The reference count is only increased if the borrowed parameter is set to true.

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

class module : public object

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 the Extra&& ... extra argument, see section Passing extra arguments to the def function.

Passing extra arguments to the def function

class arg

arg::arg(const char *name)

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 module::def() and class_::def().

sibling::sibling(handle handle)

doc::doc(const char *value)

Create a new docstring with the specified value

name::name(const char *value)

Used to specify the function name