Nanobind

https://github.com/wjakob/nanobind
Admin
nanobind is a small, efficient C++/Python binding library that exposes C++ types in Python and vice...
Tokens:79,525
Snippets:991
Trust Score:9.7
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Project Files

Source: https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt

Rules for installing directories and specific files into the defined installation paths.

```cmake
install(
  DIRECTORY include/
  DESTINATION "${NB_INSTALL_INC_DIR}"
)

install(
  DIRECTORY src/
  DESTINATION "${NB_INSTALL_SRC_DIR}"
  PATTERN "*.py" EXCLUDE
)

install(
  DIRECTORY src/
  DESTINATION "${NB_INSTALL_MODULE_DIR}"
  FILES_MATCHING PATTERN "*\.py"
  PATTERN "version.py" EXCLUDE
)

if(NB_USE_SUBMODULE_DEPS)
  install(
    FILES ext/robin_map/include/tsl/robin_map.h
          ext/robin_map/include/tsl/robin_hash.h
          ext/robin_map/include/tsl/robin_growth_policy.h
    DESTINATION "${NB_INSTALL_EXT_DIR}/robin_map/include/tsl"
  )
endif()

install(
  FILES cmake/nanobind-config.cmake
        cmake/darwin-python-path.py
        cmake/darwin-ld-cpython.sym
        cmake/darwin-ld-pypy.sym
  DESTINATION "${NB_INSTALL_CMAKE_DIR}"
)
```

--------------------------------

### Install Meson dependencies

Source: https://github.com/wjakob/nanobind/blob/master/docs/meson.rst

Initialize the subprojects directory and install required wrap packages.

```sh
mkdir -p subprojects
meson wrap install robin-map
meson wrap install nanobind
```

--------------------------------

### Define Installation Rules

Source: https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt

Sets the installation directory for nanobind data files when installation rules are enabled.

```cmake
if(NB_CREATE_INSTALL_RULES AND NOT CMAKE_SKIP_INSTALL_RULES)
  set(NB_INSTALL_DATADIR "nanobind"
    CACHE PATH "Installation path for read-only architecture-independent nanobind data files")

  # Normally these would be configurable by the user, but we can't allow that
```

--------------------------------

### Compile and install Meson projects

Source: https://github.com/wjakob/nanobind/blob/master/docs/meson.rst

Commands to build the extension or perform an editable install.

```sh
meson setup --buildtype release builddir
meson compile -C builddir
```

```sh
python -m pip install -e .
```

--------------------------------

### Verify extension installation

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Import the installed extension in a Python session to verify functionality.

```python
>>> import my_ext
>>> my_ext.hello()
'Hello world!'
```

--------------------------------

### Define Installation Directories

Source: https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt

Sets the base installation paths for include, source, extension, and CMake files.

```cmake
set(NB_INSTALL_INC_DIR "${NB_INSTALL_DATADIR}/include")
set(NB_INSTALL_SRC_DIR "${NB_INSTALL_DATADIR}/src")
set(NB_INSTALL_EXT_DIR "${NB_INSTALL_DATADIR}/ext")
set(NB_INSTALL_MODULE_DIR "${NB_INSTALL_DATADIR}")
set(NB_INSTALL_CMAKE_DIR "${NB_INSTALL_DATADIR}/cmake")
```

--------------------------------

### Install package locally

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Use pip to install the package from the current directory by parsing the pyproject.toml file.

```bash
$ cd <project-directory>
$ pip install .
```

--------------------------------

### Install build dependencies

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Install necessary build-time dependencies manually to prepare for incremental builds.

```bash
$ pip install nanobind scikit-build-core[pyproject]
```

--------------------------------

### Add and install backend module

Source: https://github.com/wjakob/nanobind/blob/master/nanobind-backend/CMakeLists.txt

Registers the nanobind backend module and defines its installation path.

```cmake
nanobind_add_backend(_nb_backend_v1)

install(TARGETS _nb_backend_v1 LIBRARY DESTINATION nanobind_backend)
```

--------------------------------

### Tag-based Polymorphism Setup

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Initial setup for a class hierarchy using an enum for type identification.

```cpp
#include <nanobind/nanobind.h>

namespace nb = nanobind;

enum class PetKind { Cat, Dog };

struct Pet { const PetKind kind; };
struct Dog : Pet { Dog() : Pet{PetKind::Dog} { } };
struct Cat : Pet { Cat() : Pet{PetKind::Cat} { } };

namespace nb = nanobind;

NB_MODULE(my_ext, m) {
    nb::class_<Pet>(m, "Pet");
    nb::class_<Dog>(m, "Dog");
    nb::class_<Cat>(m, "Cat");

    nb::enum_<PetKind>(m, "PetKind")
        .value("Cat", PetKind::Cat)
        .value("Dog", PetKind::Dog);

    m.def("make_pet", [](PetKind kind) -> Pet* {
        switch (kind) {
            case PetKind::Dog: return new Dog();
            case PetKind::Cat: return new Cat();
        }
    });
}
```

--------------------------------

### Navigate and launch Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Enter the build directory and start an interactive Python session.

```bash
cd build
python3
```

--------------------------------

### Install nanobind via Pip

Source: https://github.com/wjakob/nanobind/blob/master/docs/installing.rst

Recommended method to install the package containing C++ and CMake source code.

```bash
python -m pip install nanobind
```

--------------------------------

### Install Python development headers

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Install the necessary Python development package on Ubuntu systems.

```bash
apt install libpython3-dev
```

--------------------------------

### Install nanobind via Conda

Source: https://github.com/wjakob/nanobind/blob/master/docs/installing.rst

Alternative installation for users developing Conda-based extensions with build-time dependencies.

```bash
conda install -c conda-forge nanobind
```

--------------------------------

### Compile and install the extension module

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Defines the nanobind module target and specifies the installation destination for scikit-build-core.

```cmake
# We are now ready to compile the actual extension module
nanobind_add_module(
  # Name of the extension
  _my_ext_impl

  # Target the stable ABI for Python 3.12+, which reduces
  # the number of binary wheels that must be built. This
  # does nothing on older Python versions
  STABLE_ABI

  # Source code goes here
  src/my_ext.cpp
)

# Install directive for scikit-build-core
install(TARGETS _my_ext_impl LIBRARY DESTINATION my_ext)
```

--------------------------------

### Define build options

Source: https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt

Sets project-level options for installation, dependencies, and test configurations.

```cmake
if (CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
  set(NB_MASTER_PROJECT ON)
else()
  set(NB_MASTER_PROJECT OFF)
endif()

option(NB_CREATE_INSTALL_RULES "Create installation rules" ${NB_MASTER_PROJECT})
option(NB_USE_SUBMODULE_DEPS   "Use the nanobind dependencies shipped as a git submodule of this repository" ON)

option(NB_TEST               "Compile nanobind tests?" ${NB_MASTER_PROJECT})
option(NB_TEST_STABLE_ABI    "Test the stable ABI interface?" OFF)
option(NB_TEST_SHARED_BUILD  "Build a shared nanobind library for the test suite?" OFF)
option(NB_TEST_CUDA          "Force the use of the CUDA/NVCC compiler for testing purposes" OFF)
option(NB_TEST_FREE_THREADED "Build free-threaded extensions for the test suite?" ON)

if (NOT MSVC)
  option(NB_TEST_SANITIZERS_ASAN  "Build tests with the address sanitizer?" OFF)
  option(NB_TEST_SANITIZERS_UBSAN "Build tests with the address undefined behavior sanitizer?" OFF)
  option(NB_TEST_SANITIZERS_TSAN  "Build tests with the thread sanitizer?" OFF)
endif()
```

--------------------------------

### Install generated stubs and markers

Source: https://github.com/wjakob/nanobind/blob/master/docs/typing.rst

Use standard CMake install directives to deploy the compiled module, stub file, and marker file.

```cmake
install(TARGETS my_ext DESTINATION ".")
install(FILES py.typed my_ext.pyi DESTINATION ".")
```

--------------------------------

### Setup nanobind namespace alias

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Shortening the nanobind namespace reference for cleaner binding code.

```cpp
namespace nb = nanobind;
```

--------------------------------

### Python keyword-only parameter examples

Source: https://github.com/wjakob/nanobind/blob/master/docs/functions.rst

Demonstrates defining and calling functions with keyword-only parameters and variadic arguments in Python.

```python
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
```

--------------------------------

### Generate stubs at installation time

Source: https://github.com/wjakob/nanobind/blob/master/docs/typing.rst

Use the INSTALL_TIME parameter to delay stub generation until the installation phase, which is useful when the module is not importable during the build.

```cmake
install(TARGETS my_ext DESTINATION ".")

nanobind_add_stub(
  my_ext_stub
  INSTALL_TIME
  MODULE my_ext
  OUTPUT my_ext.pyi
  PYTHON_PATH "."
)
```

--------------------------------

### Generate wheel file

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Create a .whl file for the package without performing a full installation.

```bash
$ pip wheel .
```

--------------------------------

### Install nanobind as a Git submodule

Source: https://github.com/wjakob/nanobind/blob/master/docs/installing.rst

Use this method to reference the library directly without external package managers.

```bash
git submodule add https://github.com/wjakob/nanobind ext/nanobind
git submodule update --init --recursive
```

--------------------------------

### Example usage of expanded arguments in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/functions.rst

Demonstrates calling the C++ extension that expands arguments.

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

--------------------------------

### Trampoline with parameters

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example of using NB_OVERRIDE with additional parameters.

```cpp
std::string bark(int volume) const override {
    NB_OVERRIDE(bark, volume);
}
```

--------------------------------

### Perform incremental builds

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Install the project without build isolation to allow for faster, incremental updates during development.

```bash
$ pip install --no-build-isolation -ve .
```

--------------------------------

### Configure string-based enumeration

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example of using nb::is_str() to create a StrEnum, requiring str_value registrations.

```cpp
nb::enum_<Color>(m, "Color", nb::is_str())
    .str_value("Red",   Color::Red,   "red")
    .str_value("Green", Color::Green, "green")
    .str_value("Blue",  Color::Blue,  "blue");
```

--------------------------------

### Demonstrate reference counting in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/refleaks.rst

Example showing how a self-referencing list maintains a non-zero reference count.

```python
l = []       # 'l' ref. count = 1
l.append(l)  # 'l' ref. count = 2
del l        # 'l' ref. count = 1
```

--------------------------------

### Define a Singleton Class

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example of a C++ class intended to be used as a singleton.

```cpp
class Singleton {
public:
    static Singleton &get_instance();
};
```

--------------------------------

### Displaying object representation

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Example output of a default object representation in Python.

```pycon
>>> print(d)
<my_ext.Dog object at 0x1044540f0>
```

--------------------------------

### Interactive Python usage

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Example session demonstrating the usage of the bound C++ class in Python.

```pycon
>>> import my_ext
>>> d = my_ext.Dog('Max')
>>> print(d)
<my_ext.Dog object at 0x1044540f0>
>>> d.name
'Max'
>>> d.name = 'Charlie'
>>> d.bark()
'Charlie: woof!'
```

--------------------------------

### Define function with keyword and default arguments

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Complete C++ binding code including namespace setup, literal usage, and function definition with default arguments and docstrings.

```cpp
#include <nanobind/nanobind.h>

namespace nb = nanobind;
using namespace nb::literals;

int add(int a, int b = 1) { return a + b; }

NB_MODULE(my_ext, m) {
    m.def("add", &add, "a"_a, "b"_a = 1,
          "This function adds two numbers and increments if only one is provided.");
}
```

--------------------------------

### Generate Package Version File

Source: https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt

Creates and installs a version file for the CMake package configuration.

```cmake
include(CMakePackageConfigHelpers)
write_basic_package_version_file(
  ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake
  COMPATIBILITY SameMajorVersion
)
install(
  FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}-config-version.cmake
  DESTINATION "${NB_INSTALL_CMAKE_DIR}"
)
```

--------------------------------

### Inspect overloaded methods in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example of how overloaded methods appear in the Python help documentation.

```pycon
>>> help(my_ext.Pet)
class Pet(builtins.object)
 |  Methods defined here:
 |
 |  __init__(...)
 |      __init__(self, arg0: str, arg1: int, /) -> None
 |
 |  set(...)
 |      set(self, arg: int, /) -> None
 |      set(self, arg: str, /) -> None
 |
 |      Overloaded function.
 |
 |      1. ``set(self, arg: int, /) -> None``
 |
 |      Set the pet's age
 |
 |      2. ``set(self, arg: str, /) -> None``
 |
 |      Set the pet's name
```

--------------------------------

### Interact with inherited classes in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example usage of the registered Dog class in a Python environment.

```pycon
>>> d = my_ext.Dog("Molly")
>>> d.name
'Molly'
>>> d.bark()
'Molly: woof!'
```

--------------------------------

### Configure enumeration with arithmetic support

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example of passing nb::is_arithmetic() to enable bit-level operations on the enumeration.

```cpp
nb::enum_<Pet::Kind>(pet, "Kind", nb::is_arithmetic())
   ...
```

--------------------------------

### Perform in-place dictionary update

Source: https://github.com/wjakob/nanobind/blob/master/docs/changelog.rst

Example of an in-place dictionary operation in C++ using nanobind.

```cpp
nb::dict my_dict = ...;
my_dict["key"] += 1;
```

--------------------------------

### Configure build system with CMake

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Initialize the build directory using CMake.

```bash
cmake -S . -B build
```

--------------------------------

### Initialize Benchmarking Environment

Source: https://github.com/wjakob/nanobind/blob/master/docs/microbenchmark.ipynb

Imports necessary libraries and configures matplotlib settings for visualization.

```python
import random
import subprocess
import itertools
from collections import defaultdict
import importlib.machinery
import os
import time
import cython
from matplotlib.patches import Rectangle
    
import matplotlib.pyplot as plt
import numpy as np

import matplotlib as mpl
mpl.rcParams['hatch.linewidth'] = 5.0 
cycle = [x['color'] for x in mpl.rcParams['axes.prop_cycle']]
```

--------------------------------

### Idiomatic attribute and dictionary access

Source: https://github.com/wjakob/nanobind/blob/master/docs/changelog.rst

Example of common attribute and dictionary operations that benefit from internal string interning optimizations.

```cpp
nb::object value = obj.attr("name");
dict["name"] = value;
```

--------------------------------

### Define C++ vector bindings

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_extra.rst

Example of binding a C++ struct and a std::vector of that struct using nanobind.

```cpp
struct A {
    int value;
};

nb::class_<A>(m, "A")
    .def(nb::init<int>())
    .def_rw("value", &A::value);

nb::bind_vector<std::vector<A>>(m, "VecA");
```

--------------------------------

### Demonstrate unsafe map element access

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_extra.rst

Example of how deleting a key from a map invalidates references to its elements, leading to potential interpreter crashes.

```python
def unsafe_pop(map: ext.ExampleMap, key: str) -> ext.SomeValue:
    value = map[key]
    del map[key]
    # Oops! `value` now points to a dangling element. Anything you
    # do with it now is liable to crash the interpreter.
    return value  # uh-oh...
```

--------------------------------

### Mark instance ready

Source: https://github.com/wjakob/nanobind/blob/master/docs/lowlevel.rst

Informs nanobind that the instance is fully constructed.

```cpp
nb::inst_mark_ready(py_inst);
assert(nb::inst_ready(py_inst));
```

--------------------------------

### Conflicting type caster and binding example

Source: https://github.com/wjakob/nanobind/blob/master/docs/faq.rst

Example of code that fails to compile because it attempts to use both a type caster and a binding for the same type.

```cpp
#include <nanobind/stl/vector.h>
#include <nanobind/stl/bind_vector.h>

namespace nb = nanobind;

NB_MODULE(my_ext, m) {
    // The following line cannot be compiled
    nb::bind_vector<std::vector<int>>(m, "VectorInt");

    // This doesn't work either
    nb::class_<std::vector<int>>(m, "VectorInt");
}
```

--------------------------------

### Bind STL vector iterator

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_extra.rst

Example of binding a C++ std::vector iterator to a Python class, using keep_alive to manage object lifetimes.

```cpp
using IntVec = std::vector<int>;

nb::class_<IntVec>(m, "IntVec")
   .def("__iter__",
        [](const IntVec &v) {
            return nb::make_iterator(nb::type<IntVec>(), "iterator",
                                     v.begin(), v.end());
        }, nb::keep_alive<0, 1>());
```

--------------------------------

### Initialize nanobind-backend project

Source: https://github.com/wjakob/nanobind/blob/master/nanobind-backend/CMakeLists.txt

Sets the minimum CMake version and project language requirements.

```cmake
cmake_minimum_required(VERSION 3.15...3.30)
project(nanobind_backend LANGUAGES CXX)
```

--------------------------------

### Defining Templated Classes

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example of C++ classes with template parameters.

```cpp
struct Cat {};
struct Dog {};

template <typename PetType> struct PetHouse {
    PetHouse(PetType& pet);
    PetType& get();
};
```

--------------------------------

### Binding an equality operator

Source: https://github.com/wjakob/nanobind/blob/master/docs/typing.rst

Example of a basic class binding for an equality operator.

```cpp
nb::class_<Int>(m, "Int")
    .def(nb::self == nb::self);
```

--------------------------------

### Mutating function parameters

Source: https://github.com/wjakob/nanobind/blob/master/docs/eigen.rst

Example of modifying a passed Eigen matrix reference.

```cpp
void f4(nb::DRef<Eigen::MatrixXf> x) { x *= 2; }
```

--------------------------------

### Compare binding overheads in nanobind

Source: https://github.com/wjakob/nanobind/blob/master/docs/functions.rst

Demonstrates the difference between a fast-path function binding (f1) and a slower binding (f2) that uses keyword arguments.

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

--------------------------------

### Call inspect function from Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/ndarray.rst

Example usage of the inspect function with a NumPy array.

```pycon
>>> my_module.inspect(np.array([[1,2,3], [3,4,5]], dtype=np.float32))
Array data pointer : 0x1c30f60
Array dimension : 2
Array dimension [0] : 2
Array stride    [0] : 3
Array dimension [1] : 3
Array stride    [1] : 1
Device ID = 0 (cpu=1, cuda=0)
Array dtype: int16=0, uint32=0, float32=1
```

--------------------------------

### Compare high-level and low-level module building

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_cmake.rst

Demonstrates how nanobind_add_module simplifies the manual configuration of an extension library.

```cmake
nanobind_add_module(my_ext NB_SHARED LTO my_ext.cpp)
```

```cmake
# Build the core parts of nanobind once
nanobind_build_library(nanobind SHARED)

# Compile an extension library
add_library(my_ext MODULE my_ext.cpp)

# .. and link it against the nanobind parts
target_link_libraries(my_ext PRIVATE nanobind)

# .. enable size optimizations
nanobind_opt_size(my_ext)

# .. enable link time optimization
nanobind_lto(my_ext)

# .. set the default symbol visibility to 'hidden'
nanobind_set_visibility(my_ext)

# .. strip unneeded symbols and debug info from the binary (only active in release builds)
nanobind_strip(my_ext)

# .. disable the stack protector
nanobind_disable_stack_protector(my_ext)

# .. set the Python extension suffix
nanobind_extension(my_ext)

# .. set important compilation flags
nanobind_compile_options(my_ext)

# .. set important linker flags
nanobind_link_options(my_ext)

# Statically link against libstdc++/libgcc when targeting musllinux
nanobind_musl_static_libcpp(my_ext)
```

--------------------------------

### Define struct binding

Source: https://github.com/wjakob/nanobind/blob/master/docs/benchmark.rst

Example of a class-based benchmark declaration where computations are encapsulated in a struct.

```cpp
struct Struct50 {
    uint16_t a; int64_t b; int32_t c; uint64_t d; uint32_t e; float f;
    Struct50(uint16_t a, int64_t b, int32_t c, uint64_t d, uint32_t e, float f)
        : a(a), b(b), c(c), d(d), e(e), f(f) { }
    float sum() const { return a+b+c+d+e+f; }
};

py::class_<Struct50>(m, "Struct50")
    .def(py::init<uint16_t, int64_t, int32_t, uint64_t, uint32_t, float>())
    .def("sum", &Struct50::sum);
```

--------------------------------

### Define meson.build for extension modules

Source: https://github.com/wjakob/nanobind/blob/master/docs/meson.rst

Basic configuration for building a C++ extension module with nanobind.

```meson
project(
  'my_project_name',
  'cpp',
  version: '0.0.1',
  meson_version: '>=1.0.0',
  default_options: ['cpp_std=c++17', 'b_ndebug=if-release'],
)

python = import('python').find_installation()
nanobind_dep = dependency('nanobind')
mod = python.extension_module(
  'my_module_name',
  sources: ['path_to_module.cpp'],
  dependencies: [nanobind_dep],
  install: true,
)
```

--------------------------------

### Configure scikit-build-core settings

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Set recommended defaults for the build process, including versioning and ABI targeting.

```toml
[tool.scikit-build]
# Protect the configuration against future changes in scikit-build-core
minimum-version = "0.4"

# Setuptools-style build caching in a local directory
build-dir = "build/{wheel_tag}"

# Build stable ABI wheels for CPython 3.12+
wheel.py-api = "cp312"
```

--------------------------------

### Initial Polymorphism Behavior

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Demonstration of the default behavior where instances are created as the base class.

```pycon
>>> my_ext.make_pet(my_ext.PetKind.Cat)
<my_ext.Pet object at 0x10305ee10>

>>> my_ext.make_pet(my_ext.PetKind.Dog)
<my_ext.Pet object at 0x10328e530>
```

--------------------------------

### Locate nanobind package

Source: https://github.com/wjakob/nanobind/blob/master/docs/building.rst

Configures CMake to find nanobind based on the installation method used.

```cmake
# Detect the installed nanobind package and import it into CMake
execute_process(
  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT)
find_package(nanobind CONFIG REQUIRED)
```

```cmake
add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/ext/nanobind)
```

--------------------------------

### Define a basic C++ extension

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Create a module named my_ext that exposes an add function to Python.

```cpp
#include <nanobind/nanobind.h>

int add(int a, int b) { return a + b; }

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

--------------------------------

### Extending a Parameterized Generic Type

Source: https://github.com/wjakob/nanobind/blob/master/docs/typing.rst

Example of creating a subclass of a parameterized generic type in nanobind.

```cpp
nb::class_<Subclass>(m, "Subclass", wrapper[nb::type<Foo>()]);
```

--------------------------------

### Generated Python docstring for ndarray return

Source: https://github.com/wjakob/nanobind/blob/master/docs/ndarray.rst

Example of the auto-generated docstring resulting from the framework annotation.

```python
view(self) -> numpy.ndarray[float32, shape=(4, 4), order='F']
```

--------------------------------

### Compile the extension

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Build the extension using the configured CMake build directory.

```bash
cmake --build build
```

--------------------------------

### View module documentation in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Use the help() builtin in Python to view the docstring and module metadata after recompilation.

```pycon
>>> import my_ext
>>> help(my_ext)

Help on module my_ext:

NAME
    my_ext - A simple example python extension

DATA
    add = <nanobind.nb_func object>
        add(a: int, b: int = 1) -> int

        This function adds two numbers and increments if only one is provided

    the_answer = 42

FILE
    /Users/wjakob/my_ext/my_ext.cpython-311-darwin.so
```

--------------------------------

### Partitioning nanobind projects into multiple files

Source: https://github.com/wjakob/nanobind/blob/master/docs/faq.rst

Split large binding projects into separate compilation units to improve build performance and memory usage.

```cpp
void init_ex1(nb::module_ &);
void init_ex2(nb::module_ &);
/* ... */

NB_MODULE(my_ext, m) {
    init_ex1(m);
    init_ex2(m);
    /* ... */
}
```

```cpp
void init_ex1(nb::module_ &m) {
    m.def("add", [](int a, int b) { return a + b; });
}
```

```cpp
void init_ex2(nb::module_ &m) {
    m.def("sub", [](int a, int b) { return a - b; });
}
```

--------------------------------

### Create a backend module with nanobind_add_backend

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_cmake.rst

Used to build a backend module for extensions in split mode.

```cmake
nanobind_add_backend(_backend)   # ships as, e.g., my_package._backend
```

--------------------------------

### Return Eigen matrix by value

Source: https://github.com/wjakob/nanobind/blob/master/docs/eigen.rst

Example of a C++ function returning a dense Eigen matrix.

```cpp
Eigen::MatrixXf f() { ... }
```

--------------------------------

### Implementing manual __dlpack__ and __dlpack_device__ methods

Source: https://github.com/wjakob/nanobind/blob/master/docs/ndarray.rst

Manually expose DLPack methods on a class to allow direct conversion from the object itself.

```cpp
.def("__dlpack__", [](nb::pointer_and_handle<MyArray> self,
                      nb::kwargs kwargs) {
        using array_api_t = nb::ndarray<nb::array_api, double>;
        nb::object aa = nb::cast(array_api_t(self.p->data(), {5}),
                                 nb::rv_policy::reference_internal,
                                 self.h);
        return aa.attr("__dlpack__")(**kwargs);
    })
.def("__dlpack_device__", [](nb::handle /*self*/) {
        return std::make_pair(nb::device::cpu::value, 0);
    })
```

--------------------------------

### Parameterize a list type in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/typing.rst

Example of a function returning a list of integers for static type checking.

```python
def f() -> list[int]: ...

a = f()[0]
```

--------------------------------

### Define build-system dependencies

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Specify the build backend and required packages for the nanobind project.

```toml
[build-system]
requires = ["scikit-build-core >=0.4.3", "nanobind >=1.3.2"]
build-backend = "scikit_build_core.build"
```

--------------------------------

### Configure 32-bit Math Settings

Source: https://github.com/wjakob/nanobind/blob/master/tests/CMakeLists.txt

Forces SSE math instructions on 32-bit UNIX systems to avoid legacy 387 coprocessor issues.

```cmake
if (UNIX AND (CMAKE_SIZEOF_VOID_P EQUAL 4) AND (CMAKE_SYSTEM_PROCESSOR STREQUAL i686))
  # Don't use the legacy 387 math coprocessor in 32 bit builds, this causes tests to fail
  add_compile_options(-mfpmath=sse -msse2)
endif()
```

--------------------------------

### Define C++ class with internal types

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Example C++ structure containing an enumeration and a nested struct.

```cpp
struct Pet {
    enum Kind {
        Dog = 0,
        Cat
    };

    struct Attributes {
        float age = 0;
    };

    Pet(const std::string &name, Kind type) : name(name), type(type) { }

    std::string name;
    Kind type;
    Attributes attr;
};
```

--------------------------------

### Implementing Pickling Support

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Enables pickling by defining __getstate__ and __setstate__ methods using tuples to represent object state.

```cpp
#include <nanobind/stl/tuple.h>

struct Pet {
     std::string name;
     int age;
     Pet(const std::string &name, int age) : name(name), age(age) { }
};

NB_MODULE(my_ext, m) {
    nb::class_<Pet>(m, "Pet")
       // ...
       .def("__getstate__", [](const Pet &pet) { return std::make_tuple(pet.name, pet.age); })
       .def("__setstate__", [](Pet &pet, const std::tuple<std::string, int> &state) {
             new (&pet) Pet(
                 std::get<0>(state),
                 std::get<1>(state)
             );
       });
 }
```

--------------------------------

### Configure stable ABI builds in pyproject.toml

Source: https://github.com/wjakob/nanobind/blob/master/docs/packaging.rst

Settings to reduce the build matrix by targeting the stable ABI and restricting cibuildwheel to a single Python version.

```toml
[tool.scikit-build]
wheel.py-api = "cp310"    # instead of "cp312" above

[tool.cibuildwheel]
build = "cp310-*"
```

--------------------------------

### Invoking a higher-order function in Python

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Example usage of a bound higher-order function that returns a callable object.

```pycon
>>> f = d.bark_later()
>>> f
<nanobind.nb_func object at 0x10537c140>
>>> f()
Charlie: woof!
```

--------------------------------

### Configure split-mode testing backend

Source: https://github.com/wjakob/nanobind/blob/master/tests/CMakeLists.txt

Handles backend module generation and routing for split-mode testing, ensuring compatibility between interpreters and backends.

```cmake
# NB_TEST_SPLIT_MODE runs the test suite in split mode: every test extension
# resolves the compiled backend from a backend module at import time.
# NB_TEST_SPLIT_WHEEL routes the suite through the installed
# 'nanobind_backend' module (from the nanobind-backend wheel) instead of a
# locally built one. Both are internal testing knobs passed via -D.
if (NB_TEST_SPLIT_MODE)
  if (NB_FREE_THREADED AND NOT NB_TEST_FREE_THREADED)
    message(FATAL_ERROR "NB_TEST_SPLIT_MODE=ON on a free-threaded interpreter "
      "requires NB_TEST_FREE_THREADED=ON (a free-threaded backend serves "
      "only free-threaded extensions)")
  endif()

  # Build a local backend module and route every test extension through it
  nanobind_add_backend(nanobind_backend_test)

  # Stub generation imports the extensions, which need their backend
  set(NB_BACKEND_DEPENDS nanobind_backend_test)

  if (NB_TEST_SPLIT_WHEEL)
    # The local backend above still serves the fill() handshake tests
    set(NB_EXTRA_ARGS ${NB_EXTRA_ARGS} BACKEND_MODULE nanobind_backend)
  else()
    set(NB_EXTRA_ARGS ${NB_EXTRA_ARGS} BACKEND_MODULE nanobind_backend_test)
  endif()
endif()
```

--------------------------------

### Detecting nanobind type conflicts

Source: https://github.com/wjakob/nanobind/blob/master/docs/faq.rst

Example of the runtime warning generated when type bindings conflict between extensions.

```text
RuntimeWarning: nanobind: type 'latch' was already registered!
```

--------------------------------

### Configure pyproject.toml for Meson

Source: https://github.com/wjakob/nanobind/blob/master/docs/meson.rst

Define the build system requirements and backend for a Meson-based Python project.

```toml
[project]
name = "my_project_name"
dynamic = ['version']

[build-system]
requires = ['meson-python']

build-backend = 'mesonpy'
```

--------------------------------

### Define trivial function binding

Source: https://github.com/wjakob/nanobind/blob/master/docs/benchmark.rst

Example of a function-heavy benchmark declaration used to test binding overhead.

```cpp
m.def("test_0050", [](uint16_t a, int64_t b, int32_t c, uint64_t d, uint32_t e, float f) {
    return a+b+c+d+e+f;
});
```

--------------------------------

### Verify extension functionality

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Import the compiled module and execute the exposed function.

```pycon
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
>>> my_ext.add(1, 2)
3
```

--------------------------------

### Adjust extension rpath

Source: https://github.com/wjakob/nanobind/blob/master/docs/faq.rst

CMake commands to configure the build and install rpath for the extension to locate shared libraries.

```cmake
set_property(TARGET my_ext APPEND PROPERTY BUILD_RPATH "$<TARGET_FILE_DIR:nanobind>")
set_property(TARGET my_ext APPEND PROPERTY INSTALL_RPATH ".. ?? ..")
```

--------------------------------

### Zero-initialize POD type

Source: https://github.com/wjakob/nanobind/blob/master/docs/lowlevel.rst

Zero-initializes a POD type and marks it as ready.

```cpp
nb::inst_zero(py_inst);
assert(nb::inst_ready(py_inst));
```

--------------------------------

### Example of an ndarray type error

Source: https://github.com/wjakob/nanobind/blob/master/docs/ndarray.rst

Shows the error message generated when passing an incompatible array to a constrained function.

```pycon
>>> my_module.process(np.zeros(1))

TypeError: process(): incompatible function arguments. The following argument types are supported:
1. process(arg: ndarray[dtype=uint8, shape=(*, *, 3), device='cpu'], /) -> None

Invoked with types: numpy.ndarray
```

--------------------------------

### Registering and accessing supplemental type data

Source: https://github.com/wjakob/nanobind/blob/master/docs/lowlevel.rst

Use nb::supplement to reserve space during class registration and nb::type_supplement to access the memory region. The supplemental type must be a POD and trivially default constructible.

```cpp
struct MyTensorMetadata {
    bool stored_on_gpu;
    // ..
    // should be a POD (plain old data) type
};

// Register a new type MyTensor, and reserve space for sizeof(MyTensorMedadata)
nb::class_<MyTensor> cls(m, "MyTensor", nb::supplement<MyTensorMedadata>())

/// Mutable reference to 'MyTensorMedadata' portion in Python type object
MyTensorMedadata &supplement = nb::type_supplement<MyTensorMedadata>(cls);
supplement.stored_on_gpu = true;
```

--------------------------------

### nanobind_musl_static_libcpp

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_cmake.rst

Configures static linking for libstdc++ and libgcc on musllinux platforms.

```APIDOC
## nanobind_musl_static_libcpp(target)

### Description
Passes the linker flags -static-libstdc++ and -static-libgcc to gcc when the environment variable AUDITWHEEL_PLAT contains the string musllinux.

### Parameters
- **target** (string) - Required - The name of the CMake target to apply the linker flags.
```

--------------------------------

### Include nanobind configuration and tests

Source: https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt

Loads the nanobind CMake configuration and optionally adds the test subdirectory.

```cmake
include(cmake/nanobind-config.cmake)

if (NB_TEST)
  add_subdirectory(tests)
endif()
```

--------------------------------

### Bind functions with unique_ptr

Source: https://github.com/wjakob/nanobind/blob/master/docs/ownership.rst

Example of binding C++ functions that create and consume objects via std::unique_ptr.

```cpp
#include <nanobind/stl/unique_ptr.h>

namespace nb = nanobind;

NB_MODULE(my_ext, m) {
    struct Data { };
    nb::class_<Data>(m, "Data");
    m.def("create", []() { return std::make_unique<Data>(); });
    m.def("consume", [](std::unique_ptr<Data> x) { /* no-op */ });
}
```

--------------------------------

### nanobind_add_backend

Source: https://github.com/wjakob/nanobind/blob/master/docs/api_cmake.rst

Builds a backend module for use in split mode extensions.

```APIDOC
## nanobind_add_backend(_backend)

### Description
Builds a backend module that contains the compiled nanobind backend, serving as a dependency for extensions built in split mode.

### Parameters
- **_backend** (string) - Required - The name of the backend module target.
```

--------------------------------

### Diagnose module import errors

Source: https://github.com/wjakob/nanobind/blob/master/docs/faq.rst

Example of an ImportError caused by a mismatch between the module name in CMake and the NB_MODULE macro.

```pycon
>>> import my_ext
ImportError: dynamic module does not define module export function (PyInit_my_ext)
```

--------------------------------

### Verify instance state

Source: https://github.com/wjakob/nanobind/blob/master/docs/lowlevel.rst

Confirms the instance is managed by nanobind and is currently uninitialized.

```cpp
assert(nb::inst_check(py_inst) &&
       py_inst.type().is(py_type) &&
       !nb::inst_ready(py_inst));
```

--------------------------------

### Define argument default values with nanobind

Source: https://github.com/wjakob/nanobind/blob/master/docs/changelog.rst

Demonstrates how to define default values for function arguments, specifically regarding nullable types and compile-time inference.

```cpp
// OK: nanobind can infer that 'x' is nullable
m.def("f", &f, "x"_a = nb::none());

// OK: nanobind can infer that 'x' is nullable
nb::object none_value = nb::none();
m.def("f", &f, "x"_a.none() = none_value);

// Bad: nanobind cannot infer at compile time that 'x' should be nullable
m.def("f", &f, "x"_a = none_value);
```

--------------------------------

### Register custom type slots

Source: https://github.com/wjakob/nanobind/blob/master/docs/lowlevel.rst

Apply nb::type_slots during class registration to install custom CPython type slots.

```cpp
nb::class_<MyClass>(m, "MyClass", nb::type_slots(slots));
```

--------------------------------

### Python Usage of Bound Union

Source: https://github.com/wjakob/nanobind/blob/master/docs/classes.rst

Demonstrates interacting with the bound union from Python.

```pycon
>>> u = my_ext.Example()
>>> u.ival = 42
>>> u.to_string(0)
'42'
>>> u.dval = 1.25
>>> u.to_string(1)
'1.250000'
```

--------------------------------

### Demonstrate keyword argument failure

Source: https://github.com/wjakob/nanobind/blob/master/docs/basics.rst

Example showing a TypeError when calling a bound function with keyword arguments that were not explicitly defined.

```pycon
>>> my_ext.add(a=1, b=2)
TypeError: add(): incompatible function arguments. The following argument types are supported:
    1. add(arg0: int, arg1: int, /) -> int

Invoked with types: kwargs = { a: int, b: int }
```
Tokens:
Raw