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.

      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`>
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 `object` subclass causes a corresponding call to `__getitem__`. Assigning a `handle` or `object` 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 a `handle` or `object` subclass causes a corresponding call to `getattr`. Assigning a `handle` or `object` subclass causes a call to `setattr`.

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

  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.

  handle `get_type`() const

    Return a handle to the Python type object underlying the instance.

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

  Subclassed by args_proxy, kwargs_proxy, object

  Public Functions

  `handle`()

    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 from `handle` 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 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_error` will be throw upon failure.

  `operator bool`() const

    Return `true` when the `handle` wraps a valid Python object.

  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 bool_, buffer, bytes, capsule, dict, dtype, exception< type >, float_, function, generic_type, int_, iterable, iterator, list, memoryview, module, none, sequence, set, slice, staticmethod, str, tuple, weakref

  Public Functions

  `object`(const object &o)

    Copy constructor; always increases the reference count.

  `object`(object &&other)

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

  `~object`()

    Destructor; automatically calls `handle::dec_ref()`

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

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_borrow<py::object>(p);
      // or
      py::tuple t = reinterpret_borrow<py::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_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 the `Extra&& ... 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`.

  Public Static Functions

  static module `import`(const char *name)

    Import and return a module or throws `error_already_set`.

group `pytypes`

  Functions

  template<typename `Unsigned`>
  Unsigned `as_unsigned`(PyObject *o)
  `bytes`(const pybind11::str &s)
  `str`(const bytes &b)
  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*()`.

    Public Static Functions

    static 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 `str` : public object

    Public Functions

    `str`(handle h)

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

  class `tuple` : public object

    Subclassed by args

  class `dict` : public object

    Subclassed by kwargs

  class `function` : public object

    Subclassed by cpp_function

  class `buffer` : public object

    Subclassed by array

## 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 `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`>
  struct `base`
    #include <attr.h>

    Annotation indicating that a class derives from another given type.

  template<size_t `Nurse`, size_t `Patient`>
  struct `keep_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.

    Public Functions

    `metaclass`(handle value)

      Override pybind11’s default metaclass.

  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.

  template<typename ...`Ts`>
  struct `call_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
        });

  struct `arg`
    #include <cast.h>

    Annotation for arguments

    Subclassed by arg_v

    Public Functions

    constexpr `arg`(const char *name = nullptr)

      Constructs an argument with the name of the argument; if null or omitted, this is a positional argument.

    template<typename `T`>
    arg_v `operator=`(T &&value) const

      Assign a value to this argument.

    arg &`noconvert`(bool flag = true)

      Indicate that the type should not be converted in the type caster.

    arg &`none`(bool flag = true)

      Indicates that the argument should/shouldn’t allow None (e.g. for nullable pointer args)

    Public Members

    const char *`name`

      If non-null, this is a named kwargs argument.

    bool `flag_noconvert`

      If set, do not allow conversion (requires a supporting type caster!)

    bool `flag_none`

      If set (the default), allow None to be passed to this argument.

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

    arg_v &`none`(bool flag = true)

      Same as `arg::nonone()`, but returns *this as arg_v&, not arg&.

    Public Members

    object `value`

      The default value.

    const char *`descr`

      The (optional) description of the default value.

    std::string `type`

      The C++ type name of the default value (only available when compiled in debug mode)

## 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()` and `finalize_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::cerr << "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>());

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

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

  bool `isinstance`(handle obj, handle type)

    Return true if `obj` is an instance of the `type`.

  bool `hasattr`(handle obj, handle name)
  bool `hasattr`(handle obj, const char *name)
  void `delattr`(handle obj, handle name)
  void `delattr`(handle obj, const char *name)
  object `getattr`(handle obj, handle name)
  object `getattr`(handle obj, const char *name)
  object `getattr`(handle obj, handle name, handle default_)
  object `getattr`(handle obj, const char *name, handle default_)
  void `setattr`(handle obj, handle name, handle value)
  void `setattr`(handle obj, const char *name, handle value)
  ssize_t `hash`(handle obj)
  size_t `len`(handle h)
  size_t `len_hint`(handle h)
  str `repr`(handle h)
  iterator `iter`(handle obj)

## Inheritance

See Object-oriented code and Classes for more detail.

`PYBIND11_OVERLOAD`(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_OVERLOAD_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_OVERLOAD_PURE`(ret_type, cname, fn, ...)

  Macro for pure virtual functions, this function is identical to `PYBIND11_OVERLOAD`, except that it throws if no overload can be found.

`PYBIND11_OVERLOAD_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_OVERLOAD_NAME(
            std::string, // Return type (ret_type)
            Animal,      // Parent class (cname)
            toString,    // Name of function in C++ (name)
            "__str__",   // Name of method in Python (fn)
        );
      }

`PYBIND11_OVERLOAD_PURE_NAME`(ret_type, cname, name, fn, ...)

  Macro for pure virtual functions, this function is identical to `PYBIND11_OVERLOAD_NAME`, except that it throws if no overload can be found.

template<class `T`>
function `get_overload`(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 overload should be retrieved for. This should be the first non-trampoline class encountered in the inheritance chain.
  name: | The name of the overloaded 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).

  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 runtime_error

  C++ bindings of builtin Python exceptions.

  Subclassed by buffer_error, cast_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`

  Functions

  constexpr arg `operator""_a`(const char *name, size_t)

    String literal version of `arg`

  str `operator""_s`(const char *s, size_t size)

    String literal version of `str`