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