nanobind

https://nanobind.readthedocs.io/en/latest/
Admin
nanobind is a small, efficient binding library that exposes C++ types in Python and vice versa,...
Tokens:125,334
Snippets:1,692
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and verify package

Source: https://nanobind.readthedocs.io/en/latest/_sources/packaging.rst.txt

Commands for local installation and verification of the extension.

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

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

```bash
$ pip wheel .
```

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

### Install dependencies via Meson Wrap

Source: https://nanobind.readthedocs.io/en/latest/meson.html

Initialize the subprojects directory and install required wrap packages.

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

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

### Install package locally

Source: https://nanobind.readthedocs.io/en/latest/packaging.html

Use pip to install the package from the current directory.

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

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

### Verify package installation

Source: https://nanobind.readthedocs.io/en/latest/packaging.html

Import the extension and call a function to verify the installation.

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

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

### Install nanobind via Pip

Source: https://nanobind.readthedocs.io/en/latest/_sources/installing.rst.txt

Use this command to install the nanobind package, which includes C++ and CMake source code for compiling extension modules. This is the recommended installation method.

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

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

### Install nanobind and robin-map with Meson WrapDB

Source: https://nanobind.readthedocs.io/en/latest/_sources/meson.rst.txt

Create a 'subprojects' directory and use 'meson wrap install' to add nanobind and robin-map as project dependencies.

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

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

### Install Python development headers

Source: https://nanobind.readthedocs.io/en/latest/basics.html

Command to install necessary Python development files on Ubuntu systems.

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

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

### Install build dependencies

Source: https://nanobind.readthedocs.io/en/latest/packaging.html

Install necessary build-time dependencies before enabling incremental builds.

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

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

### Python Trampoline Execution Example

Source: https://nanobind.readthedocs.io/en/latest/_sources/classes.rst.txt

Example output showing the trampoline in action.

```pycon
>>> my_ext.alarm(dog)
Mr. Fluffles: yip!
Mr. Fluffles: yip!
Mr. Fluffles: yip!
```

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

### Install extension in editable mode

Source: https://nanobind.readthedocs.io/en/latest/meson.html

Use pip to perform an editable install without a local build folder.

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

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

### Editable install with pip

Source: https://nanobind.readthedocs.io/en/latest/_sources/meson.rst.txt

Install the package as an editable install using pip, useful when local build folders are not desired.

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

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

### C++ Class Binding for Inheritance

Source: https://nanobind.readthedocs.io/en/latest/_sources/classes.rst.txt

Example setup for C++ classes intended to be extended in Python.

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

namespace nb = nanobind;

struct Dog {
    std::string name;
    std::string bark() const { return name + ": woof!"; }
};

struct DogHouse {
    Dog dog;
};

NB_MODULE(my_ext, m) {
    nb::class_<Dog>(m, "Dog")
       .def(nb::init<const std::string &>())
       .def("bark", &Dog::bark)
       .def_rw("name", &Dog::name);

    nb::class_<DogHouse>(m, "DogHouse")
       .def(nb::init<Dog>())
       .def_rw("dog", &DogHouse::dog);
}
```

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

### Create Parameter Specification

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_extra.rst.txt

Example of creating a ParamSpec instance.

```cpp
m.attr("P") = nb::param_spec("P");
```

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

### Python Stub Generation Examples

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Examples showing how function signatures are represented in .pyi stub files, including full docstrings, abbreviated docstrings, and ellipsis placeholders.

```python
def square(x: int) -> int:
       '''Return the square of the input'''
       return x*x
```

```python
def square(x: int) -> int:
       '''Return the square of the input'''
```

```python
def square(x: int) -> int: ...
```

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

### Define nanobind extension module

Source: https://nanobind.readthedocs.io/en/latest/_sources/packaging.rst.txt

Compiles the extension module and sets up the installation directory.

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

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

### Generate wheel file

Source: https://nanobind.readthedocs.io/en/latest/packaging.html

Create a .whl file instead of performing a direct installation.

```bash
$ pip wheel .
```

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

### Install nanobind via Conda

Source: https://nanobind.readthedocs.io/en/latest/_sources/installing.rst.txt

Install nanobind using Conda, suitable for users developing Conda-based extensions with a build-time dependency on nanobind. This method is an alternative when the PyPI package cannot be used.

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

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

### Define function bindings with keywords and defaults

Source: https://nanobind.readthedocs.io/en/latest/basics.html

Complete example showing the C++ implementation and the corresponding nanobind module definition with argument annotations 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.");
}
```

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

### Nanobind Runtime Warning Example

Source: https://nanobind.readthedocs.io/en/latest/_sources/faq.rst.txt

Example of a warning message triggered when a type is registered multiple times across extensions.

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

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

### Install generated stubs

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Use standard CMake install directives to deploy the compiled module and generated stubs.

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

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

### Enable incremental builds

Source: https://nanobind.readthedocs.io/en/latest/packaging.html

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

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

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

### Enable incremental builds

Source: https://nanobind.readthedocs.io/en/latest/_sources/packaging.rst.txt

Commands to install dependencies and configure the package for incremental rebuilds during development.

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

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

```bash
$ pip install --no-build-isolation -Ceditable.rebuild=true -ve .
```

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

### Verify Inheritance in Python

Source: https://nanobind.readthedocs.io/en/latest/_sources/classes.rst.txt

Example usage of the bound Dog class in Python.

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

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

### Generate stubs at install time

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Use the INSTALL_TIME parameter when the module cannot be imported during the build phase.

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

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

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

### Python Keyword-Only Argument Examples

Source: https://nanobind.readthedocs.io/en/latest/_sources/functions.rst.txt

Demonstrates Python function signatures where arguments are restricted to keyword-only usage.

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

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

### Bind function with arguments and docstring

Source: https://nanobind.readthedocs.io/en/latest/basics.html

Example of the .def declaration using argument names and a docstring to improve Python-side usability.

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

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

### Configure and build with CMake

Source: https://nanobind.readthedocs.io/en/latest/basics.html

Commands to initialize the build system and compile the extension.

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

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

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

### Mark instance as ready

Source: https://nanobind.readthedocs.io/en/latest/_sources/lowlevel.rst.txt

Inform nanobind that the instance is fully constructed after manual initialization.

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

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

### Navigate to build and test extension

Source: https://nanobind.readthedocs.io/en/latest/basics.html

Commands to enter the build directory and verify the extension functionality in Python.

```bash
cd build
python3
```

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

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

### Example of a nanobind reference leak warning

Source: https://nanobind.readthedocs.io/en/latest/_sources/refleaks.rst.txt

A sample output showing the format of leak warnings generated by nanobind during Python shutdown.

```text
nanobind: leaked 1 instances!
 - leaked instance 0x102123728 of type "my_ext.MyClass"
nanobind: leaked 1 types!
 - leaked type "my_ext.MyClass"
nanobind: leaked 1 functions!
 - leaked function "__init__"

nanobind: this is likely caused by a reference counting issue in the binding code.
See https://nanobind.readthedocs.io/en/latest/refleaks.html
```

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

### Navigate to build directory and run Python

Source: https://nanobind.readthedocs.io/en/latest/_sources/basics.rst.txt

After successful compilation, change into the build directory and start an interactive Python session to test your extension. The exact path might differ on Windows.

```bash
cd build
python3

```

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

### Compile nanobind extension with Meson

Source: https://nanobind.readthedocs.io/en/latest/_sources/meson.rst.txt

Use 'meson setup' to configure the build and 'meson compile' to build the extension module. Specify build type and output directory.

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

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

### Enum Operation Examples

Source: https://nanobind.readthedocs.io/en/latest/_sources/changelog.rst.txt

Examples of changed behavior for enum ordering and arithmetic operations.

```python
FooEnum(1) < 1.2
```

```python
FooEnum(2) * 1.5
```

```python
FooEnum(3) - "2"
```

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

### inst_ready

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Queries the ready flag of the instance h.

```APIDOC
## bool inst_ready(handle h)

### Description
Returns the current state of the ready flag for instance h.
```

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

### Module Import Error Example

Source: https://nanobind.readthedocs.io/en/latest/_sources/faq.rst.txt

Example of an ImportError caused by a mismatch between the module name and the export function.

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

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

### Configure build with CMake

Source: https://nanobind.readthedocs.io/en/latest/_sources/basics.rst.txt

Use this CMake command to set up the build system for your nanobind extension. It creates a 'build' directory for all output files.

```bash
cmake -S . -B build

```

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

### Compile extension using Meson

Source: https://nanobind.readthedocs.io/en/latest/meson.html

Commands to set up the build directory and compile the project.

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

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

### View stub generator command line options

Source: https://nanobind.readthedocs.io/en/latest/typing.html

Display the help menu for the nanobind stub generator CLI.

```bash
usage: python -m nanobind.stubgen [-h] [-o FILE] [-O PATH] [-i PATH]
                                  [-m MODULE] [-r] [-M FILE] [-p FILE] [-P]
                                  [-D] [--exclude-values] [-q]

Generate stubs for nanobind-based extensions.

options:
  -h, --help                    show this help message and exit
  -o FILE, --output-file FILE   write generated stubs to the specified file
  -O PATH, --output-dir PATH    write generated stubs to the specified directory
  -i PATH, --import PATH        add the directory to the Python import path (can
                                specify multiple times)
  -m MODULE, --module MODULE    generate a stub for the specified module (can
                                specify multiple times)
  -r, --recursive               recursively process submodules
  -M FILE, --marker-file FILE   generate a marker file (usually named 'py.typed')
  -p FILE, --pattern-file FILE  apply the given patterns to the generated stub
                                (see the docs for syntax, can specify multiple
                                times)
  -P, --include-private         include private members (with single leading or
                                trailing underscore)
  -D, --exclude-docstrings      exclude docstrings from the generated stub
  --exclude-values              force the use of ... for values
  -q, --quiet                   do not generate any output in the absence of failures

```

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

### Copy or move construct instance

Source: https://nanobind.readthedocs.io/en/latest/_sources/lowlevel.rst.txt

Use nb::inst_copy() or nb::inst_move() to initialize an instance from another existing instance.

```cpp
if (copy_instance)
    nb::inst_copy(/* dst = */ py_inst, /* src = */ some_other_instance);
else
    nb::inst_move(/* dst = */ py_inst, /* src = */ some_other_instance);
```

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

### Python Exception Chaining Example

Source: https://nanobind.readthedocs.io/en/latest/_sources/exceptions.rst.txt

A Python code example demonstrating the 'raise from' syntax for chaining exceptions, where a new exception is raised with the original exception as its cause.

```py
try:
        print(1 / 0)
    except Exception as exc:
        raise RuntimeError("could not divide by zero") from exc
```

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

### Install Python development headers (Ubuntu)

Source: https://nanobind.readthedocs.io/en/latest/_sources/basics.rst.txt

If CMake fails to find Python, you may need to install the Python 3 development package. This command is for Ubuntu systems.

```bash
apt install libpython3-dev

```

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

### Shorthand operator notation

Source: https://nanobind.readthedocs.io/en/latest/classes.html

Example of the shorthand notation for operator binding.

```cpp
.def(nb::self * float())
```

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

### Basic Meson.build configuration for nanobind extension

Source: https://nanobind.readthedocs.io/en/latest/_sources/meson.rst.txt

Define project settings, find Python, and configure the extension module using nanobind dependency. Ensure C++17 standard and release build type.

```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,
)
```

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

### Locate nanobind package

Source: https://nanobind.readthedocs.io/en/latest/_sources/building.rst.txt

Methods to inform CMake about the nanobind installation location.

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

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

### Enum Comparison Behavior

Source: https://nanobind.readthedocs.io/en/latest/_sources/changelog.rst.txt

Examples of enum comparison behavior with unsupported types.

```python
some_enum == None
```

```python
some_enum < None
```

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

### Print object representation

Source: https://nanobind.readthedocs.io/en/latest/basics.html

Example of the default string representation of a bound object.

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

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

### MyPy error message

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Example of a type checker error when signatures are incompatible.

```text
error: Argument 1 of "__eq__" is incompatible with supertype "object"; supertype defines the argument type as "object"  [override]
```

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

### View stubgen command line options

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Displays the help menu and available configuration flags for the stubgen command-line interface.

```text
usage: python -m nanobind.stubgen [-h] [-o FILE] [-O PATH] [-i PATH]
                                  [-m MODULE] [-r] [-M FILE] [-p FILE] [-P]
                                  [-D] [--exclude-values] [-q]

Generate stubs for nanobind-based extensions.

options:
  -h, --help                    show this help message and exit
  -o FILE, --output-file FILE   write generated stubs to the specified file
  -O PATH, --output-dir PATH    write generated stubs to the specified directory
  -i PATH, --import PATH        add the directory to the Python import path (can
                                specify multiple times)
  -m MODULE, --module MODULE    generate a stub for the specified module (can
                                specify multiple times)
  -r, --recursive               recursively process submodules
  -M FILE, --marker-file FILE   generate a marker file (usually named 'py.typed')
  -p FILE, --pattern-file FILE  apply the given patterns to the generated stub
                                (see the docs for syntax, can specify multiple
                                times)
  -P, --include-private         include private members (with single leading or
                                trailing underscore)
  -D, --exclude-docstrings      exclude docstrings from the generated stub
  --exclude-values              force the use of ... for values
  -q, --quiet                   do not generate any output in the absence of failures
```

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

### nb::type_slots()

Source: https://nanobind.readthedocs.io/en/latest/lowlevel.html

Allows installation of custom CPython type slots during class construction.

```APIDOC
## nb::type_slots(slots)

### Description
An annotation used within `nb::class_` to install custom `PyType_Slot` entries, providing an escape hatch for advanced CPython type customization.

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

### Parameters
- **slots** (PyType_Slot[]) - An array of function pointers tagged with slot identifiers, terminated by a null entry `{ 0, nullptr }`.
```

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

### Bind Implicit Conversions

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Demonstrates replacing init_implicit with lower-level manual binding and explicit conversion registration.

```cpp
nb::class_<MyType>(m, "MyType")
    .def(nb::init_implicit<const char*>());
```

```cpp
nb::class_<MyType>(m, "MyType")
    .def("__init__",
         [](MyType* t, const char* arg0) {
             new (t) MyType(arg0);
         });

nb::implicitly_convertible<const char*, MyType>();
```

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

### inst_mark_ready

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Sets both ready and destruct flags to true for instance h.

```APIDOC
## void inst_mark_ready(handle h)

### Description
Simultaneously sets the ready and destruct flags of instance h to true.
```

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

### Adjust RPATH in CMake

Source: https://nanobind.readthedocs.io/en/latest/_sources/faq.rst.txt

CMake commands to set the build and install RPATH for the extension.

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

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

### Compile a Custom Backend

Source: https://nanobind.readthedocs.io/en/latest/_sources/split_mode.rst.txt

Use the nanobind_add_backend command to compile a custom backend module.

```cmake
nanobind_add_backend(my_backend)
```

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

### Python usage of a bound union

Source: https://nanobind.readthedocs.io/en/latest/classes.html

Example interaction with the bound union in a Python environment.

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

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

### Bind Constructors with init

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Use the init helper to capture C++ constructor signatures for Python bindings.

```cpp
nb::class_<MyType>(m, "MyType")
    .def(nb::init<const char*, int>());
```

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

### Create Type Variable

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_extra.rst.txt

Example of creating a TypeVar with specific constraints using nanobind.

```cpp
m.attr("T") = nb::type_var("T",
                           "contravariant"_a = true,
                           "covariant"_a = false,
                           "bound"_a = nb::type<MyClass>());
```

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

### Define a Python stub entry

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Example of a basic class stub entry in Python.

```python
class MyClass:
    def my_function(arg: object) -> object: ...
```

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

### Build a nanobind backend module

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_cmake.rst.txt

Use this command to create a Python module containing the compiled nanobind backend for use in split mode.

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

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

### scikit-build-core Configuration

Source: https://nanobind.readthedocs.io/en/latest/_sources/packaging.rst.txt

Recommended settings for build caching and ABI compatibility in pyproject.toml.

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

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

### Generated Python Docstring

Source: https://nanobind.readthedocs.io/en/latest/_sources/ndarray.rst.txt

Example of the auto-generated docstring for a function returning a NumPy array.

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

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

### Project Directory Structure

Source: https://nanobind.readthedocs.io/en/latest/_sources/packaging.rst.txt

The recommended layout for a nanobind project, separating source code from build configuration.

```text
├── README.md
├── CMakeLists.txt
├── pyproject.toml
└── src/
    ├── my_ext.cpp
    └── my_ext/
        └── __init__.py
```

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

### Handling virtual functions with parameters

Source: https://nanobind.readthedocs.io/en/latest/_sources/classes.rst.txt

Shows how to pass parameters through the NB_OVERRIDE macro.

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

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

### Python usage of expanded arguments

Source: https://nanobind.readthedocs.io/en/latest/functions.html

Example of calling the C++ extension that uses expanded arguments.

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

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

### Zero-initialize POD types

Source: https://nanobind.readthedocs.io/en/latest/_sources/lowlevel.rst.txt

Use nb::inst_zero() to zero-initialize POD types and mark them as ready.

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

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

### Define C++ Vector Bindings

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_extra.rst.txt

Example of binding a struct and a 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");
```

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

### Binding an iterable vector

Source: https://nanobind.readthedocs.io/en/latest/_sources/typing.rst.txt

Example of binding a vector that lacks a specific type signature for iteration.

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

nb::class_<IntVec>(m, "IntVec")
   .def("__iter__",
        [](const IntVec &v) -> GeneralIterator { ... })
```

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

### Custom Constructor Patterns

Source: https://nanobind.readthedocs.io/en/latest/_sources/porting.rst.txt

Comparison of custom constructor implementation using lambda functions and placement new.

```cpp
py::class_<MyType>(m, "MyType")
    .def(py::init([](int) { return MyType(...); }));
```

```cpp
nb::class_<MyType>(m, "MyType")
    .def("__init__", [](MyType *t) { new (t) MyType(...); });
```

```cpp
nb::class_<MyType>(m, "MyType")
    .def("__init__", [](MyType *t) { new (t) MyType(MyType::create()); });
```

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

### Define struct-based method binding

Source: https://nanobind.readthedocs.io/en/latest/benchmark.html

Example of the class-based benchmark structure where computations are encapsulated in structs.

```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);
```

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

### dict inst_dict(handle h)

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Returns the instance dictionary.

```APIDOC
## dict inst_dict(handle h)

### Description
Returns h.__dict__ more efficiently than going through the attribute protocol.
```

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

### Binding Arithmetic Enumerations

Source: https://nanobind.readthedocs.io/en/latest/_sources/classes.rst.txt

Example of binding an enumeration with arithmetic support using nb::is_arithmetic().

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

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

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

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_cmake.rst.txt

Demonstrates how the high-level nanobind_add_module command maps to the underlying fine-grained nanobind CMake functions.

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

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

### Inspect array properties via Python

Source: https://nanobind.readthedocs.io/en/latest/_sources/ndarray.rst.txt

Example usage of the inspect function from a Python environment.

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

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

### Partitioning Large Projects for Build Efficiency

Source: https://nanobind.readthedocs.io/en/latest/_sources/faq.rst.txt

Split large binding projects into multiple files to reduce memory usage and enable parallel, incremental builds.

```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; });
}
```

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

### Trampoline Class Implementation

Source: https://nanobind.readthedocs.io/en/latest/_sources/porting.rst.txt

Example of implementing a trampoline class using the NB_TRAMPOLINE and NB_OVERRIDE macros.

```cpp
struct PyAnimal : Animal {
    NB_TRAMPOLINE(Animal);

    std::string name() const override {
        NB_OVERRIDE(name);
    }
};
```

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

### Configure stable ABI builds in pyproject.toml

Source: https://nanobind.readthedocs.io/en/latest/_sources/packaging.rst.txt

Settings to reduce the build matrix to a single stable ABI wheel per platform.

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

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

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

### Implicit Conversion Behavior

Source: https://nanobind.readthedocs.io/en/latest/_sources/functions.rst.txt

Examples of how implicit conversions work by default and how they fail when noconvert() is applied.

```pycon
>>> my_ext.double(2)
4.0
```

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

Invoked with types: int
```

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

### inst_zero

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Zero-initializes the contents of instance h.

```APIDOC
## void inst_zero(handle h)

### Description
Zero-initializes the contents of h and sets the ready and destruct flags to true.
```

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

### Call bound functions from Python

Source: https://nanobind.readthedocs.io/en/latest/_sources/functions.rst.txt

Demonstrates interacting with the bound C++ functions and verifying named parameter support.

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

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

### Missing Library Import Error

Source: https://nanobind.readthedocs.io/en/latest/_sources/faq.rst.txt

Example of an ImportError occurring when the nanobind shared library cannot be located.

```pycon
>>> import my_ext
ImportError: dlopen(my_ext.cpython-311-darwin.so, 0x0002):
Library not loaded: '@rpath/libnanobind.dylib'
```

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

### nanobind_musl_static_libcpp

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_cmake.rst.txt

Configures static linking for musllinux builds.

```APIDOC
## nanobind_musl_static_libcpp(target)

### Description
Passes -static-libstdc++ and -static-libgcc to gcc when targeting musllinux platforms.

### Usage
```cmake
nanobind_musl_static_libcpp(my_target)
```
```

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

### Attribute Access Functions

Source: https://nanobind.readthedocs.io/en/latest/_sources/api_core.rst.txt

Functions for getting, setting, checking, and deleting attributes on Python objects.

```APIDOC
## hasattr(handle h, const char * key)
## hasattr(handle h, handle key)

### Description
Checks if the given object has an attribute specified by a string or handle. Returns false if the attribute does not exist or an internal error occurs.

### Parameters
- **h** (handle) - The object to check.
- **key** (const char* or handle) - The attribute name.

## getattr(handle h, const char * key)
## getattr(handle h, handle key)

### Description
Retrieves an attribute from a Python object. Raises python_error if the operation fails.

## getattr(handle h, const char * key, handle def)
## getattr(handle h, handle key, handle def)

### Description
Retrieves an attribute from a Python object, returning a default value if the attribute is not found or the operation fails.

## setattr(handle h, const char * key, handle value)
## setattr(handle h, handle key, handle value)

### Description
Sets an attribute on a Python object. Raises python_error if the operation fails.

## delattr(handle h, const char * key)
## delattr(handle h, handle key)

### Description
Deletes an attribute from a Python object. Raises python_error if the operation fails.
```

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

### Perform in-place dictionary updates in C++

Source: https://nanobind.readthedocs.io/en/latest/_sources/changelog.rst.txt

Demonstrates the correct way to perform in-place updates on a nanobind dictionary object.

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

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

### Define templated classes for binding

Source: https://nanobind.readthedocs.io/en/latest/classes.html

Example of C++ classes with template parameters intended for nanobind wrapping.

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

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

```

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

### Define trivial function binding

Source: https://nanobind.readthedocs.io/en/latest/benchmark.html

Example of the function-heavy benchmark structure used to measure 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;
});
```

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

### Compile the extension using CMake

Source: https://nanobind.readthedocs.io/en/latest/_sources/basics.rst.txt

After CMake has configured the build, use this command to compile your nanobind extension. This command should be run from your project's root directory.

```bash
cmake --build build

```
Tokens:
Raw