Exchanging information#

nanobind offers three fundamentally different ways of exchanging information between Python and C++. Depending on the task at hand, one will usually be preferable over the others, hence it is important to be aware of their advantages and disadvantages.

Option 1: Type Casters#

A type caster translates C++ objects into equivalent Python objects and vice versa. The illustration below shows a translation between C++ (blue) and Python (green) worlds, where a std::vector<int> instance converts from/to a Python list containing int objects.

_images/caster-light.svg _images/caster-dark.svg

Example: The following function doubles the entries of an STL vector and returns the result.

using IntVector = std::vector<int>;

IntVector double_it(const IntVector &in) {
    IntVector out(in.size());
    for (size_t i = 0; i < in.size(); ++i)
        out[i] = in[i] * 2;
    return out;
}

To expose it in Python, we can use the std::vector<...> type caster that is located in an optional header file named nanobind/stl/vector.h:

#include <nanobind/stl/vector.h>

NB_MODULE(my_ext, m) {
    m.def("double_it", &double_it);
}

That’s all there is to it. The Python version of the function features an automatically generated docstring, type checks, and (if needed) error reporting.

>>> import my_ext
>>> my_ext.double_it([1, 2, 3])
[2, 4, 6]

>>> my_ext.double_it([1, 2, 'foo'])
TypeError: double_it(): incompatible function arguments. The following argument types are supported:
    1. double_it(arg: list[int], /) -> list[int]

What are the implications of using type casters?

Pro: this approach is simple and convenient, especially when standard (STL) types are involved. Usually, all that is needed is an #include directive to pull in the right header file. Complex nested types (e.g. vectors of hash tables of strings) work automatically by combining type casters recursively.

The following table lists the currently available type casters along with links to external projects that provide further casters:

Type

Type caster header

char, char*, void*, nullptr_t, bool, int, unsigned int, long, unsigned long, …

Built-in (no include file needed)

std::array<..>

#include <nanobind/stl/array.h>

std::chrono::duration<..>, std::chrono::time_point<..> (more details)

#include <nanobind/stl/chrono.h>

std::complex<..>

#include <nanobind/stl/complex.h>

std::filesystem::path

#include <nanobind/stl/filesystem.h>

std::function<..>

#include <nanobind/stl/function.h>

std::list<..>

#include <nanobind/stl/list.h>

std::map<..>

#include <nanobind/stl/map.h>

std::optional<..>

#include <nanobind/stl/optional.h>

std::pair<..>

#include <nanobind/stl/pair.h>

std::set<..>

#include <nanobind/stl/set.h>

std::string

#include <nanobind/stl/string.h>

std::string_view

#include <nanobind/stl/string_view.h>

std::tuple<..>

#include <nanobind/stl/tuple.h>

std::shared_ptr<..>

#include <nanobind/stl/shared_ptr.h>

std::unique_ptr<..>

#include <nanobind/stl/unique_ptr.h>

std::unordered_set<..>

#include <nanobind/stl/unordered_set.h>

std::unordered_map<..>

#include <nanobind/stl/unordered_map.h>

std::variant<..>

#include <nanobind/stl/variant.h>

std::vector<..>

#include <nanobind/stl/vector.h>

nb::ndarray<..>

#include <nanobind/ndarray.h>

Eigen::Matrix<..>, Eigen::Array<..>, Eigen::Ref<..>, Eigen::Map<..>

#include <nanobind/eigen/dense.h>

Eigen::SparseMatrix<..>

#include <nanobind/eigen/sparse.h>

Apache Arrow types

https://github.com/maximiliank/nanobind_pyarrow

…

Please reach out if you have additions to this list.

Con: Every transition between the Python and C++ side will generally require a conversion step (in this case, to re-create all list elements). This can be wasteful when the other side only needs to access a small part of the data. Conversely, the overhead should not be a problem when the data is fully “consumed” following conversion.

A select few type casters (std::unique_ptr<..>, std::shared_ptr<..>, nb::ndarray, and Eigen::*) are special in the sense that they can perform a type conversion without copying the underlying data. Besides those few exceptions type casting always implies that a copy is made.

Mutable reference issue#

Another subtle limitation of type casters is that they don’t propagate updates through mutable references. Consider the following alternative implementation of the double_it function:

void double_it(IntVector &in) {
    for (int &value : in)
        value *= 2;
}

nanobind can wrap this function without problems, but it won’t behave as expected:

>>> x = [1, 2, 3]
>>> my_ext.double_it(x)
>>> x
[1, 2, 3]  # <-- oops, unchanged!

How could this happen? The reason is that type casters convert function arguments and return values once, but further changes will not automatically propagate across the language barrier because the representations are not intrinsically linked to each other. This problem is not specific to STL types—for example, the following function will similarly not update its argument once exposed in Python.

void double_it(int &in) { in *= 2; }

This is because builtin types like int, str, bool, etc., are all handled by type casters.

A simple alternative to propagate updates while retaining the convenience of type casters is to bind a small wrapper lambda function that returns a tuple with all output arguments. An example:

int foo(int &in) { in *= 2; return std::sqrt(in); }

And the binding code

m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });

In this case, a type caster (#include <nanobind/stl/tuple.h) must be included to handle the std::tuple<int, int> return value.

Option 2: Bindings#

Bindings expose C++ types in Python; the ability to create them is the main feature of nanobind. In the list-of-integer example, they cause Python to interpret std::vector<int> as a new Python type called my_ext.IntVector.

_images/binding-light.svg _images/binding-dark.svg

Example: to switch the previous example to bindings, we first replace the type caster header (nanobind/stl/vector.h) by its binding variant (nanobind/stl/bind_vector.h) and then invoke the nb::bind_vector<T>() function to create a new Python type named IntVector within the module m.

 #include <nanobind/stl/bind_vector.h>

 using IntVector = std::vector<int>;
 IntVector double_it(const IntVector &in) { /* .. omitted .. */ }

 namespace nb = nanobind;

 NB_MODULE(my_ext, m) {
     nb::bind_vector<IntVector>(m, "IntVector");
     m.def("double_it", &double_it);
 }

Any function taking or returning integer vectors will now use the type binding. In the Python session below, nanobind performs an implicit conversion from the Python list [1, 2, 3] to a my_ext.IntVector before calling the double_it function.

>>> import my_ext
>>> my_ext.double_it([1, 2, 3])
my_ext.IntVector([2, 4, 6])

>>> my_ext.double_it.__doc__
'double_it(arg: my_ext.IntVector, /) -> my_ext.IntVector'

Let’s go through the implications of using bindings:

Pro: bindings don’t require the costly conversion step when crossing the language boundary. They also support mutable references, so the issue discussed in the context of type casters does not arise. Sometimes, binding is the only available option: when a C++ type does not have an equivalent Python type, casting simply does not make sense.

Con: Creating good bindings that feel natural in Python requires some additional work. We cheated in this example by relying on the nb::bind_vector<T>() helper function that did all the heavy lifting. Such helpers are currently only available for a few special cases (vectors, ordered/unordered maps, iterators):

Type

Binding helper header

std::vector<..>

#include <nanobind/stl/bind_vector.h> (docs)

std::map<..>

#include <nanobind/stl/bind_map.h> (docs)

std::unordered_map<..>

#include <nanobind/stl/bind_map.h> (docs)

Forward iterators

#include <nanobind/make_iterator.h> (docs)

Other types

See the previous example on binding custom types.

In general, you will need to write the binding code yourself. The previous section on binding custom types showed an example of such a type binding.

Option 3: Wrappers#

The last option is only rarely used, but it can be powerful alternative in some cases. nanobind provides wrapper classes to use Python types within C++. You can think of this as a kind of reverse binding. For example, a Python list can be accessed through the nb::list type:

_images/wrapper-light.svg _images/wrapper-dark.svg

This is what the example looks like when expressed using nb::list and nb::int_.

#include <nanobind/nanobind.h>

namespace nb = nanobind;

nb::list double_it(nb::list l) {
    nb::list result;
    for (nb::handle h: l)
        result.append(h * nb::int_(2));
    return result;
}

NB_MODULE(my_ext, m) {
    m.def("double_it", &double_it);
}

The implications of using wrappers are:

Pro: Wrappers require no copying or type conversion. With them, C++ begins to resemble dynamically typed Python code and can perform highly general operations on Python objects. Wrappers are useful to tap into the powerful Python software ecosystem (NumPy, Matplotlib, PyTorch, etc).

Con: Functions based on wrappers cannot run without Python. In contrast to option 1 (type casters) and 2 (bindings), we can no longer reuse an existing function and process its arguments and return value to interface the Python and C++ worlds: the entire function must be rewritten using nanobind-specific wrapper types. Every operation will translate into a corresponding Python C API call, which means that wrappers aren’t suitable for performance-critical loops or multithreaded computations.

The following wrappers are available and require no additional include directives: any, bytes, callable, capsule, dict, ellipsis, handle, handle_t<T>, bool_, int_, float_, iterable, iterator, list, mapping, module_, object, set, sequence, slice, str, tuple, weakref, type_object, type_object_t<T>, args, and kwargs.

Discussion#

The choices outlined above are more fine-grained than they may appear. For example, it is possible to use type casters, bindings, and wrappers to handle multiple arguments of a single function.

They can also be combined within a single function argument. For example, you can type cast a std::vector<T> containing bindings or wrappers.

In general, we recommend that you use

  1. type casters for STL containers, and

  2. bindings for other custom types.

If the former turn out to be a performance bottleneck, it is easy to replace them with bindings or wrappers later on. Wrappers are only rarely useful; you will usually know it when you need them.