Functions

Binding annotations

Besides keyword and default arguments, docstrings, and return value policies, other function binding annotations can be specified to achieve different goals as described below.

Default arguments revisited

A noteworthy point about the previously discussed way of specifying default arguments is that nanobind immediately converts them into Python objects. Consider the following example:

nb::class_<MyClass>(m, "MyClass")
    .def("f", &MyClass::f, "value"_a = SomeType(123));

nanobind must be set up to deal with values of the type SomeType (via a prior instantiation of nb::class_<SomeType>), or an exception will be thrown.

The “preview” of the default argument in the function signature is generated using the object’s __str__ method. If not available, the signature may not be very helpful, e.g.:

>> help(my_ext.MyClass)

class MyClass(builtins.object)
 |  Methods defined here:
 ....
 |  f(...)
 |      f(self, value: my_ext.SomeType = <my_ext.SomeType object at 0x1004d7230>) -> None

In such cases, you can either refine the implementation of the type in question or manually override how nanobind renders the default value using the .sig("string") method:

nb::class_<MyClass>(m, "MyClass")
    .def("f", &MyClass::f, "value"_a.sig("SomeType(123)") = SomeType(123));

Implicit conversions, and how to suppress them

Consider the following function taking a floating point value as input:

m.def("double", [](float x) { return 2.f * x; });

We can call this function using a Python float, but an int works just as well:

>>> my_ext.double(2)
4.0

nanobind performed a so-called implicit conversion for convenience. The same mechanism generalizes to custom types defining a nb::init_implicit<T>()-style constructor:

nb::class_<A>(m, "A")
    // Following this line, nanobind will automatically convert 'B' -> 'A' if needed
    .def(nb::init_implicit<B>());

This behavior is not always desirable—sometimes, it is better to give up or try another function overload. To achieve this behavior, use the .noconvert() method of the nb::arg annotation to mark the argument as non-converting. An example:

m.def("double", [](float x) { return 2.f * x; }, nb::arg("x").noconvert());

The same experiment now fails with a TypeError:

>>> my_ext.double(2)
TypeError: double(): incompatible function arguments. The following ↵
argument types are supported:
    1. double(x: float) -> float

Invoked with types: int

You may, of course, combine this with the _a shorthand notation (see the section on keyword arguments) or specify unnamed non-converting arguments using nb::arg().noconvert().

Note

The number of nb::arg annotations must match the argument count of the function. To enable no-convert behaviour for just one of several arguments, you will need to specify nb::arg().noconvert() for that argument, and nb::arg() for the remaining ones.

None arguments

A common design pattern in C/C++ entails passing nullptr to pointer-typed arguments to indicate a missing value. Since nanobind cannot know whether a function uses such a convention, it refuses conversions from None to nullptr by default. For example, consider the following binding code:

struct Dog { };
const char *bark(Dog *dog) {
    return dog != nullptr ? "woof!" : "(no dog)";
}

NB_MODULE(my_ext, m) {
    nb::class_<Dog>(m, "Dog")
        .def(nb::init<>());
    m.def("bark", &bark);
}

Calling the function with None raises an exception:

>>> my_ext.bark(my_ext.Dog())
'woof!'
>>> my_ext.bark(None)
TypeError: bark(): incompatible function arguments. The following ↵
argument types are supported:
    1. bark(arg: my_ext.Dog, /) -> str

To switch to a more permissive behavior, call the .none() method of the nb::arg annotation:

m.def("bark", &bark, nb::arg("dog").none());

With this change, the function accepts None, and its signature also changes to reflect this fact.

>>> my_ext.bark(None)
'(no dog)'

>>> my_ext.bark.__doc__
'bark(dog: Optional[my_ext.Dog]) -> str'

You may also specify a None default argument value, in which case the annotation can be omitted:

m.def("bark", &bark, nb::arg("dog") = nb::none());

Note that passing values by pointer (including null pointers) is only supported for bound types. Type casters and wrappers cannot be used in such cases and will produce compile-time errors.

Alternatively, you can also use std::optional<T> to pass an optional argument by value. To use it, you must include the header file associated needed by its type caster:

#include <nanobind/stl/optional.h>

NB_MODULE(my_ext, m) {
    m.def("bark", [](std::optional<Dog> d) { ... }, nb::arg("dog") = nb::none());
}

Overload resolution order

nanobind relies on a two-pass scheme to determine the right implementation when a bound function or method with multiple overloads is called from Python.

The first pass attempts to call each overload while disabling implicit argument conversion—it’s as if every argument had a matching nb::arg().noconvert() annotation as described above. The process terminates successfully when nanobind finds an overload that is compatible with the provided arguments.

If the first pass fails, a second pass retries all overloads while enabling implicit argument conversion. If the second pass also fails, the function dispatcher raises a TypeError.

Within each pass, nanobind tries overloads in the order in which they were registered. Consequently, it prefers an overload that does not require implicit conversion to one that does, but otherwise prefers earlier-defined overloads to later-defined ones. Within the second pass, the precise number of implicit conversions needed does not influence the order.

The special exception nb::next_overload can also influence overload resolution. Raising this exception from an overloaded function causes it to be skipped, and overload resolution resumes. This can be helpful in complex situations where the value of a parameter must be inspected to see if a particular overload is eligible.

Accepting *args and **kwargs

Python supports functions that accept an arbitrary number of positional and keyword arguments:

def generic(*args, **kwargs):
    ...  # do something with args and kwargs

Such functions can also be created using nanobind:

void generic(nb::args args, nb::kwargs kwargs) {
    for (auto v: args)
        nb::print(nb::str("Positional: {}").format(v));
    for (auto kv: kwargs)
        nb::print(nb::str("Keyword: {} -> {}").format(kv.first, kv.second));
}

// Binding code
m.def("generic", &generic);

The class nb::args derives from nb::tuple and nb::kwargs derives from nb::dict.

You may also use them individually or even combine them with ordinary parameters. Note that nb::kwargs must be the last parameter if it is specified, and any parameters after nb::args are implicitly keyword-only, just like in regular Python.

Expanding *args and **kwargs

Conversely, nanobind can also expand standard containers to add positional and keyword arguments to a Python call. The example below shows how to do this using the wrapper types nb::object, nb::callable, nb::list, nb::dict

nb::object my_call(nb::callable callable) {
    nb::list list;
    nb::dict dict;

    list.append("positional");
    dict["keyword"] = "value";

    return callable(1, *list, **dict);
}

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

Here is an example use of the above extension in Python:

>>> def x(*args, **kwargs):
...     print(args)
...     print(kwargs)
...
>>> import my_ext
>>> my_ext.my_call(x)
(1, 'positional')
{'keyword': 'value'}

Keyword-only parameters

Python supports keyword-only parameters; these can’t be filled positionally, thus requiring the caller to specify their name. They can be used to enforce more clarity at call sites if a function has multiple paramaters that could be confused with each other, or to accept named options alongside variadic *args.

def example(val: int, *, check: bool) -> None:
    # val can be passed either way; check must be given as a keyword arg
    pass

example(val=42, check=True)   # good
example(check=False, val=5)   # good
example(100, check=True)      # good
example(200, False)           # TypeError:
    # example() takes 1 positional argument but 2 were given

def munge(*args: int, invert: bool = False) -> int:
    return sum(args) * (-1 if invert else 1)

munge(1, 2, 3)                # 6
munge(4, 5, 6, invert=True)   # -15

nanobind provides a nb::kw_only() annotation that allows you to produce bindings that behave like these examples. It must be placed before the nb::arg() annotation for the first keyword-only parameter; you can think of it as equivalent to the bare *, in a Python function signature. For example, the above examples could be written in C++ as:

void example(int val, bool check);
int munge(nb::args args, bool invert);

m.def("example", &example,
      nb::arg("val"), nb::kw_only(), nb::arg("check"));

// Parameters after *args are implicitly keyword-only:
m.def("munge", &munge,
      nb::arg("args"), nb::arg("invert"));

// But you can be explicit about it too, as long as you put the
// kw_only annotation in the correct position:
m.def("munge", &munge,
      nb::arg("args"), nb::kw_only(), nb::arg("invert"));

Note

nanobind does not support the pos_only() argument annotation provided by pybind11, which marks the parameters before it as positional-only. However, a parameter can be made effectively positional-only by giving it no name (using an empty nb::arg() specifier).

Function templates

Consider the following function signature with a template parameter:

template <typename T> void process(T t);

A template must be instantiated with concrete types to be usable, which is a compile-time operation. The generic version version therefore cannot be used in bindings:

m.def("process", &process); // <-- this will not compile

You must bind each instantiation separately, either as a single function with overloads, or as separately named functions.

// Option 1:
m.def("process", &process<int>);
m.def("process", &process<std::string>);

// Option 2:
m.def("process_int", &process<int>);
m.def("process_string", &process<std::string>);

Lifetime annotations

The nb::keep_alive<Nurse, Patient>() annotation indicates that the argument with index Patient should be kept alive at least until the argument with index Nurse is freed by the garbage collector.

The example below applies the annotation to a hypothetical operation that appends an entry to a log data structure.

nb::class_<Log>(m, "Log")
    .def("append",
         [](Log &log, Entry *entry) -> void { ... },
         nb::keep_alive<1, 2>());

Here, Nurse = 1 refers to the log argument, while Patient = 2 refers to entry. Setting Nurse/Patient = 0 would select the function return value (here, the function doesn’t return anything, so 0 is not a valid choice).

The example uses the annotation to tie the lifetime of the entry to that of log. Without it, Python could potentially delete entry before log, which would be problematic if the log.append() operation causes log to reference entry through a pointer address instead of making a copy. Whether or not this is a good design is another question (for example, shared ownership via std::shared_ptr<T> or intrusive reference counting would avoid the problem altogether).

See the definition of nb::keep_alive for further discussion and limitations of this method.

Call guards

The nb::call_guard<T>() annotation allows any scope guard T to be placed around the function call. For example, this definition:

m.def("foo", foo, nb::call_guard<T>());

is equivalent to the following pseudocode:

m.def("foo", [](args...) {
    T scope_guard;
    return foo(args...); // forwarded arguments
});

The only requirement is that T is default-constructible, but otherwise any scope guard will work. This feature is often combined with nb::gil_scoped_release to release the Python global interpreter lock (GIL) during a long-running C++ routine to permit parallel execution.

Multiple guards should be specified as nb::call_guard<T1, T2, T3...>. Construction occurs left to right, while destruction occurs in reverse.

If your wrapping needs are more complex than nb::call_guard<T>() can handle, it is also possible to define a custom “call policy”, which can observe or modify the Python object arguments and observe the return value. See the documentation of nb::call_policy<Policy> for details.

Higher-order functions

The C++11 standard introduced lambda functions and the generic polymorphic function wrapper std::function<>, which enable powerful new ways of working with functions. Lambda functions come in two flavors: stateless lambda function resemble classic function pointers that link to an anonymous piece of code, while stateful lambda functions additionally depend on captured variables that are stored in an anonymous lambda closure object.

Here is a simple example of a C++ function that takes an arbitrary function (stateful or stateless) with signature int -> int as an argument and runs it with the value 10.

int func_arg(const std::function<int(int)> &f) {
    return f(10);
}

The example below is more involved: it takes a function of signature int -> int and returns another function of the same kind. The return value is a stateful lambda function, which stores the value f in the capture object and adds 1 to its return value upon execution.

std::function<int(int)> func_ret(const std::function<int(int)> &f) {
    return [f](int i) {
        return f(i) + 1;
    };
}

This example demonstrates using python named parameters in C++ callbacks which requires use of the nb::cpp_function conversion function. Usage is similar to defining methods of classes:

nb::object func_cpp() {
    return nb::cpp_function([](int i) { return i+1; },
       nb::arg("number"));
}

After including the extra header file nanobind/stl/function.h, it is almost trivial to generate binding code for all of these functions.

#include <nanobind/stl/function.h>

NB_MODULE(my_ext, m) {
    m.def("func_arg", &func_arg);
    m.def("func_ret", &func_ret);
    m.def("func_cpp", &func_cpp);
}

The following interactive session shows how to call them from Python.

Python 3.11.1 (main, Dec 23 2022, 09:28:24) [Clang 14.0.0 (clang-1400.0.29.202)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import my_ext
>>> def square(i):
...     return i*i
...
>>> my_ext.func_arg(square)
100
>>> square_plus_1 = my_ext.func_ret(square)
>>> square_plus_1(4)
17
>>> plus_1 = my_ext.func_cpp()
>>> plus_1.__doc__
'<anonymous>(number: int) -> int'
>>> plus_1(number=43)
44

Note

This functionality is very useful when generating bindings for callbacks in C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.).

Minimizing binding overheads

The code that dispatches function calls from Python to C++ is in general highly optimized. When it is important to further reduce binding overheads to an absolute minimum, consider removing annotations for keyword and default arguments along with other advanced binding annotations.

In the snippet below, f1 has lower binding overheads compared to f2.

NB_MODULE(my_ext, m) {
    m.def("f1", [](int) { /* no-op */ });
    m.def("f2", [](int) { /* no-op */ }, "arg"_a);
}

This is because f1:

1. Does not use any of the following advanced argument annotations features:

   • Named function arguments, e.g., nb::arg("name") or "name"_a.

   • Default argument values, e.g., nb::arg() = 0 or "name"_a = false.

   • Nullability or implicit conversion flags, e.g., nb::arg().none() or "name"_a.noconvert().

2. Has no nb::keep_alive<Nurse, Patient>() annotations.

3. Takes no variable-length positional (nb::args) or keyword (nb::kwargs) arguments.

4. Has a to total of 8 or fewer function arguments.

If all of the above conditions are satisfied, nanobind switches to a specialized dispatcher that is optimized to handle a small number of positional arguments. Otherwise, it uses the default dispatcher that works in any situation. It is also worth noting that functions with many overloads generally execute more slowly, since nanobind must first select a suitable one.

These differences are mainly of interest when a function that does very little is called at a very high rate, in which case binding overheads can become noticeable.

Regarding point 1 of the above list, note that locking is okay, as long as the annotation does not provide an argument name. In other words, a function binding with a nb::arg().lock() for some of its arguments stays on the fast path. This is mainly of interest for free-threaded extensions.