api_core.rst

C++ API Reference (Core)

Macros

Python object API

Nanobind ships with a wide range of Python wrapper classes like :cppobject, :cpplist, etc. Besides class-specific operations (e.g., :cpplist::append), these classes also implement core operations that can be performed on any Python object. Since it would be tedious to implement this functionality over and over again, it is realized by the following mixin class that lives in the nanobind::detail namespace.

Handles and objects

nanobind provides two styles of Python object wrappers: classes without reference counting deriving from :cpphandle, and reference-counted wrappers deriving from :cppobject. Reference counting bugs can be really tricky to track down, hence it is recommended that you always prefer :cppobject-style wrappers unless there are specific reasons that warrant the use of raw handles.

Without reference counting

With reference counting

Attribute access

Size queries

Type queries

Wrapper classes

Parameterized wrapper classes

Error management

nanobind provides a range of functionality to convert C++ exceptions into equivalent Python exceptions and raise captured Python error state in C++. The :cppexception class is also relevant in this context, but is listed in the reference section on class binding <class_binding>.

Casting

Common binding annotations

The following annotations can be specified in both function and class bindings.

Function binding annotations

The following annotations can be specified using the variable-length Extra parameter of :cppmodule_::def, :cppclass_::def, :cppcpp_function, etc.

Class binding annotations

The following annotations can be specified using the variable-length Extra parameter of the constructor :cppclass_::class_.

Enum binding annotations

The following annotations can be specified using the variable-length Extra parameter of the constructor :cppenum_::enum_. Enums also support the :cppdynamic_attr and :cpptype_slots annotations documented for classes <class_binding_annotations>.

Function binding

Class binding

GIL Management

These two RAII helper classes acquire and release the Global Interpreter Lock (GIL) in a given scope. The :cppgil_scoped_release helper is often combined with the :cppcall_guard, as in

m.def("expensive", &expensive, nb::call_guard<nb::gil_scoped_release>());

This releases the interpreter lock while expensive is running, which permits running it in parallel from multiple Python threads.

Low-level type and instance access

nanobind exposes a low-level interface to provide fine-grained control over the sequence of steps that instantiates a Python object wrapping a C++ instance. An thorough explanation of these features is provided in a separate section <lowlevel>.

Type objects

Instances

The documentation below refers to two per-instance flags with the following meaning:

• ready: is the instance fully constructed? nanobind will not permit passing the instance to a bound C++ function when this flag is unset.
• destruct: should nanobind call the C++ destructor when the instance is garbage-collected?

Global flags

Miscellaneous