Merge remote-tracking branch 'origin/master' into interop

Author: oremanj

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       fail-fast: false
       matrix:
         os: ['ubuntu-latest', 'windows-2022', 'macos-13']
-        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14.0-alpha.7', 'pypy3.9-v7.3.16', 'pypy3.10-v7.3.17']
+        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14.0-rc.2', 'pypy3.9-v7.3.16', 'pypy3.10-v7.3.17']
 
     name: "Python ${{ matrix.python }} / ${{ matrix.os }}"
     runs-on: ${{ matrix.os }}

.gitignore

@@ -38,6 +38,6 @@ __pycache__
 nanobind.egg-info
 test_*_ext*.so
 test_*_ext*.pyd
-test_*.pyi
+*.pyi
 py\.typed
 .mypy_cache

README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
     <picture>
-      <source media="(prefers-color-scheme: dark)" width="800" srcset="https://rgl.s3.eu-central-1.amazonaws.com/media/uploads/wjakob/2023/03/28/nanobind_logo_dark.png">
+      <source media="(prefers-color-scheme: dark)" width="800" srcset="https://d38rqfq1h7iukm.cloudfront.net/media/uploads/wjakob/2023/03/28/nanobind_logo_dark.png">
       <source media="(prefers-color-scheme: light)" width="800" srcset="https://github.com/wjakob/nanobind/raw/master/docs/images/logo.jpg">
       <img alt="nanobind logo" width="800" src="https://github.com/wjakob/nanobind/raw/master/docs/images/logo.jpg">
     </picture>
@@ -55,5 +55,5 @@ discourse:
 
 The nanobind logo was designed by [AndoTwin Studio](https://andotwinstudio.com)
 (high-resolution download:
-[light](https://rgl.s3.eu-central-1.amazonaws.com/media/uploads/wjakob/2023/03/27/nanobind_logo.jpg),
-[dark](https://rgl.s3.eu-central-1.amazonaws.com/media/uploads/wjakob/2023/03/28/nanobind_logo_dark_1.png)).
+[light](https://d38rqfq1h7iukm.cloudfront.net/media/uploads/wjakob/2023/03/27/nanobind_logo.jpg),
+[dark](https://d38rqfq1h7iukm.cloudfront.net/media/uploads/wjakob/2023/03/28/nanobind_logo_dark_1.png)).

cmake/nanobind-config.cmake

@@ -599,7 +599,7 @@ endfunction()
 # ---------------------------------------------------------------------------
 
 function (nanobind_add_stub name)
-  cmake_parse_arguments(PARSE_ARGV 1 ARG "VERBOSE;INCLUDE_PRIVATE;EXCLUDE_DOCSTRINGS;INSTALL_TIME;EXCLUDE_FROM_ALL" "MODULE;OUTPUT;MARKER_FILE;COMPONENT;PATTERN_FILE" "PYTHON_PATH;DEPENDS")
+  cmake_parse_arguments(PARSE_ARGV 1 ARG "VERBOSE;INCLUDE_PRIVATE;EXCLUDE_DOCSTRINGS;INSTALL_TIME;RECURSIVE;EXCLUDE_FROM_ALL" "MODULE;COMPONENT;PATTERN_FILE;OUTPUT_PATH" "PYTHON_PATH;DEPENDS;MARKER_FILE;OUTPUT")
 
   if (EXISTS ${NB_DIR}/src/stubgen.py)
     set(NB_STUBGEN "${NB_DIR}/src/stubgen.py")
@@ -623,17 +623,23 @@ function (nanobind_add_stub name)
     list(APPEND NB_STUBGEN_ARGS -D)
   endif()
 
-  foreach (TMP IN LISTS ARG_PYTHON_PATH)
-    list(APPEND NB_STUBGEN_ARGS -i "${TMP}")
+  if (ARG_RECURSIVE)
+    list(APPEND NB_STUBGEN_ARGS -r)
+  endif()
+
+  foreach (PYTHON_PATH IN LISTS ARG_PYTHON_PATH)
+    list(APPEND NB_STUBGEN_ARGS -i "${PYTHON_PATH}")
   endforeach()
 
   if (ARG_PATTERN_FILE)
     list(APPEND NB_STUBGEN_ARGS -p "${ARG_PATTERN_FILE}")
   endif()
 
   if (ARG_MARKER_FILE)
-    list(APPEND NB_STUBGEN_ARGS -M "${ARG_MARKER_FILE}")
-    list(APPEND NB_STUBGEN_OUTPUTS "${ARG_MARKER_FILE}")
+    foreach (MARKER_FILE IN LISTS ARG_MARKER_FILE)
+      list(APPEND NB_STUBGEN_ARGS -M "${MARKER_FILE}")
+      list(APPEND NB_STUBGEN_OUTPUTS "${MARKER_FILE}")
+    endforeach()
   endif()
 
   if (NOT ARG_MODULE)
@@ -642,13 +648,38 @@ function (nanobind_add_stub name)
     list(APPEND NB_STUBGEN_ARGS -m "${ARG_MODULE}")
   endif()
 
-  if (NOT ARG_OUTPUT)
-    message(FATAL_ERROR "nanobind_add_stub(): an 'OUTPUT' argument must be specified!")
+  list(LENGTH ARG_OUTPUT OUTPUT_LEN)
+
+  # Some sanity hecks
+  if (ARG_RECURSIVE)
+    if (NOT ARG_INSTALL_TIME)
+      if ((OUTPUT_LEN EQUAL 0) AND NOT ARG_OUTPUT_PATH)
+        message(FATAL_ERROR "nanobind_add_stub(): either 'OUTPUT' or 'OUTPUT_PATH' must be specified when 'RECURSIVE' is set!")
+      endif()
+    endif()
   else()
-    list(APPEND NB_STUBGEN_ARGS -o "${ARG_OUTPUT}")
-    list(APPEND NB_STUBGEN_OUTPUTS "${ARG_OUTPUT}")
+    if ((OUTPUT_LEN EQUAL 0) AND NOT ARG_INSTALL_TIME)
+      message(FATAL_ERROR "nanobind_add_stub(): an 'OUTPUT' argument must be specified.")
+    endif()
+    if ((OUTPUT_LEN GREATER 0) AND ARG_OUTPUT_PATH)
+      message(FATAL_ERROR "nanobind_add_stub(): 'OUTPUT' and 'OUTPUT_PATH' can only be specified together when 'RECURSIVE' is set!")
+    endif()
+    if (OUTPUT_LEN GREATER 1)
+      message(FATAL_ERROR "nanobind_add_stub(): specifying more than one 'OUTPUT' requires that 'RECURSIVE' is set!")
+    endif()
+  endif()
+
+  if (ARG_OUTPUT_PATH)
+    list(APPEND NB_STUBGEN_ARGS -O "${ARG_OUTPUT_PATH}")
   endif()
 
+  foreach (OUTPUT IN LISTS ARG_OUTPUT)
+    if (NOT ARG_RECURSIVE)
+      list(APPEND NB_STUBGEN_ARGS -o "${OUTPUT}")
+    endif()
+    list(APPEND NB_STUBGEN_OUTPUTS "${OUTPUT}")
+  endforeach()
+
   file(TO_CMAKE_PATH ${Python_EXECUTABLE} NB_Python_EXECUTABLE)
 
   set(NB_STUBGEN_CMD "${NB_Python_EXECUTABLE}" "${NB_STUBGEN}" ${NB_STUBGEN_ARGS})

docs/api_cmake.rst

@@ -444,13 +444,46 @@ Nanobind's CMake tooling includes a convenience command to interface with the
           generation of all dependencies (see ``DEPENDS``). When this parameter
           is specified, stub generation is instead postponed to the
           installation phase.
+
+      * - ``RECURSIVE``
+        - If specified, the stub generator automatically traverses the module
+          hierarchy and generates a stub for each discovered submodule. The
+          files are either placed right next to the original Python code, or
+          relative to ``OUTPUT_PATH``.
+
+          In this special mode, you may pass multiple arguments ``OUTPUT`` so
+          that CMake's dependency management can keep track of the generated
+          files.
+
       * - ``MODULE``
-        - Specifies the name of the module that should be imported. Mandatory.
+        - Specifies the name of the module that should be imported. Only
+          a single module can be specified. Mandatory.
+
       * - ``OUTPUT``
-        - Specifies the name of the stub file that should be written. The path
+        - Specifies the name of the stub (``.pyi``) file to be written. The path
           is relative to ``CMAKE_CURRENT_BINARY_DIR`` for build-time stub
           generation and relative to ``CMAKE_INSTALL_PREFIX`` for install-time
-          stub generation. Mandatory.
+          stub generation.
+
+          When ``RECURSIVE`` is set, *multiple* paths may be specified. Note
+          that these are not actually passed to the stub generator and purely
+          used for dependency management within CMake (e.g., to remove files
+          when executing the ``clean`` target, or to track dependencies when
+          stub files are subsequently consumed by other targets).
+
+          This parameter is generally mandatory. When ``INSTALL_TIME`` is set,
+          it can be omitted since dependency tracking is not needed in this
+          case.
+
+      * - ``OUTPUT_PATH``
+        - Overrides the base directory in which stub files should be written.
+          This parameter can only be used when ``INSTALL_TIME`` or
+          ``RECURSIVE`` (or both) are set.
+
+          The path is relative to ``CMAKE_CURRENT_BINARY_DIR`` for build-time
+          stub generation and relative to ``CMAKE_INSTALL_PREFIX`` for
+          install-time stub generation.
+
       * - ``PYTHON_PATH``
         - List of search paths that should be considered when importing the
           module. The paths are relative to ``CMAKE_CURRENT_BINARY_DIR`` for
@@ -462,32 +495,41 @@ Nanobind's CMake tooling includes a convenience command to interface with the
           when :cmake:command:`nanobind_add_stub` is used for build-time stub
           generation. Otherwise, generator expressions should not be used.
           Optional.
+
       * - ``DEPENDS``
         - Any targets listed here will be marked as a dependencies. This should
           generally be used to list the target names of one or more prior
           :cmake:command:`nanobind_add_module` declarations. Note that this
           parameter tracks *build-time* dependencies and does not need to be
           specified when stub generation occurs at install time (see
           ``INSTALL_TIME``). Optional.
+
       * - ``VERBOSE``
         - Show status messages generated by ``stubgen``.
+
       * - ``EXCLUDE_DOCSTRINGS``
         - Generate a stub containing only typed signatures without docstrings.
+
       * - ``INCLUDE_PRIVATE``
         - Also include private members, whose names begin or end with a single
           underscore.
+
       * - ``MARKER_FILE``
         - Typed extensions normally identify themselves via the presence of an
           empty file named ``py.typed`` in each module directory. When this
           parameter is specified, :cmake:command:`nanobind_add_stub` will
           automatically generate such an empty file as well.
+          Multiple marker file paths can be optionally passed to this parameter.
+
       * - ``PATTERN_FILE``
         - Specify a pattern file used to replace declarations in the stub. The
           syntax is described in the section on :ref:`stub generation <stubs>`.
+
       * - ``COMPONENT``
         - Specify a component when ``INSTALL_TIME`` stub generation is used.
           This is analogous to ``install(..., COMPONENT [name])`` in other
           install targets.
+
       * - ``EXCLUDE_FROM_ALL``
         - If specified, the file is only installed as part of a
           component-specific installation when ``INSTALL_TIME`` stub generation

docs/api_core.rst

@@ -1085,7 +1085,7 @@ Wrapper classes
       *Note*: The C string will be deleted when the `str` instance is garbage
       collected.
 
-   .. cpp:function:: template <typename... Args> str format(Args&&... args)
+   .. cpp:function:: template <typename... Args> str format(Args&&... args) const
 
       C++ analog of the Python routine ``str.format``. Can be called with
       positional and keyword arguments.
@@ -1610,7 +1610,10 @@ Casting
    When the `convert` argument is set to ``true`` (the default), the
    implementation may also attempt *implicit conversions* to perform the cast.
 
-   The function raises a :cpp:type:`cast_error` when the conversion fails.
+   The function raises an exception when the conversion fails.
+   If the type caster uses the CPython error API (e.g., ``PyErr_SetString()``
+   or ``PyErr_Format()``) to report a failure, then :cpp:class:`python_error`
+   is raised.  Otherwise, :cpp:type:`cast_error` is raised.
    See :cpp:func:`try_cast()` for an alternative that never raises.
 
 .. cpp:function:: template <typename T, typename Derived> bool try_cast(const detail::api<Derived> &value, T &out, bool convert = true) noexcept
@@ -1632,7 +1635,10 @@ Casting
    policy `policy` is used to handle ownership-related questions when a new
    Python object must be created.
 
-   The function raises a :cpp:type:`cast_error` when the conversion fails.
+   The function raises an exception when the conversion fails.
+   If the type caster uses the CPython error API (e.g., ``PyErr_SetString()``
+   or ``PyErr_Format()``) to report a failure, then :cpp:class:`python_error`
+   is raised.  Otherwise, :cpp:type:`cast_error` is raised.
 
 .. cpp:function:: template <typename T> object cast(T &&value, rv_policy policy, handle parent)
 
@@ -1641,7 +1647,10 @@ Casting
    Python object must be created. A valid `parent` object is required when
    specifying a `reference_internal` return value policy.
 
-   The function raises a :cpp:type:`cast_error` when the conversion fails.
+   The function raises an exception when the conversion fails.
+   If the type caster uses the CPython error API (e.g., ``PyErr_SetString()``
+   or ``PyErr_Format()``) to report a failure, then :cpp:class:`python_error`
+   is raised.  Otherwise, :cpp:type:`cast_error` is raised.
 
 .. cpp:function:: template <typename T> object find(const T &value) noexcept
 
@@ -1655,7 +1664,10 @@ Casting
    value policy `policy` is used to handle ownership-related questions when a
    new Python objects must be created.
 
-   The function raises a :cpp:type:`cast_error` when the conversion fails.
+   The function raises an exception when the conversion fails.
+   If the type caster uses the CPython error API (e.g., ``PyErr_SetString()``
+   or ``PyErr_Format()``) to report a failure, then :cpp:class:`python_error`
+   is raised.  Otherwise, :cpp:type:`cast_error` is raised.
 
 Common binding annotations
 --------------------------

docs/api_extra.rst

@@ -1104,6 +1104,10 @@ convert into an equivalent representation in one of the following frameworks:
 
 .. cpp:class:: cupy
 
+.. cpp:class:: memview
+
+   Builtin Python ``memoryview`` for CPU-resident data.
+
 Eigen convenience type aliases
 ------------------------------
 

docs/changelog.rst

@@ -31,7 +31,95 @@ Version TBD (unreleased)
   and later. This feature is likely to be of **great utility** to anyone who
   is working on porting large or interconnected extension modules from pybind11
   to nanobind. See the extensive :ref:`interoperability documentation <interop>`
-  for more details.
+  for more details. (PR `#1140 <https://github.com/wjakob/nanobind/pull/1140>`__).
+
+Version 2.9.2 (Sep 4, 2025)
+---------------------------
+
+This is a patch release to fix an issue in the new recursive stub generation feature:
+
+- When creating stubs for a module, the generator must decide whether to store
+  declarations locally (e.g., in ``foo.pyi``) or in a subdirectory (e.g., in
+  ``foo/__init__.pyi``). The latter is necessary, e.g., when ``foo`` contains
+  submodules. However, the implemented submodule test was far too conservative
+  and interpreted any imported module (e.g. ``import os``) as a submodule. The
+  patch release fixes this.
+  (commit `a65e1b
+  <https://github.com/wjakob/nanobind/commit/a65e1b36ec0670e7c8d7a3bacfa5cff425fe92fe>`__).
+
+Version 2.9.1 (Sep 4, 2025)
+---------------------------
+
+This is a patch release to fix a regression in the CMake build system:
+
+- nanobind 2.9.0 internally adopted the CMake command ``cmake_path()`` to
+  normalize paths. This was done for cosmetic reasons, since it improves the
+  readability of generated commands. However, ``cmake_path()`` is only
+  available on CMake 3.20+, while nanobind officially supports CMake 3.15+.
+  Version 2.9.1 removes the full path normalization.
+  (commit `f703fd
+  <https://github.com/wjakob/nanobind/commit/f703fd403aed32cd903f5cfdff414bdfd13f6430>`__).
+
+
+Version 2.9.0 (Sep 4, 2025)
+---------------------------
+
+- Nanobind's CMake stub generation command :cmake:command:`nanobind_add_stub`
+  can now automatically traverse submodule hierarchies and generate :ref:`many
+  stub files at once <stubgen_recursive_cmake>`. (PR `#1148
+  <https://github.com/wjakob/nanobind/pull/1148>`__).
+
+- Recursive stub generation now correctly organizes stub files hierarchically (e.g.
+  ``my_ext.pyi`` versus ``my_ext/__init__.pyi``). (commits `ad9d3fe
+  <https://github.com/wjakob/nanobind/commit/ad9d3fe4a631b25dbef0eca54a4ac5f96f064596>`__,
+  `620c1c1
+  <https://github.com/wjakob/nanobind/commit/620c1c13430bed882d76d2c12efadaa4e9f3f37d>`__).
+
+- The stub generator now exposes NumPy array types as ``NDArray[np.float32]``
+  (or similar) instead of ``Annotated[ArrayLike, dict(...)]`` to simplify
+  type-checking. (PR `#1149 <https://github.com/wjakob/nanobind/pull/1149>`__,
+  commit `37dd2c
+  <https://github.com/wjakob/nanobind/commit/37dd2c6d6a44f9657fb08c46b2d5e5c1623a1048>`__).
+
+- Nanobind (finally!) correctly implements in-place updates to dicts, lists,
+  etc. Previously, a C++ operation like
+
+  .. code-block:: cpp
+
+     nb::dict my_dict = ...;
+     my_dict["key"] += 1;
+
+  performed an addition but failed to reassign the updated value to the
+  original key. (PR `#1119 <https://github.com/wjakob/nanobind/pull/1119>`__).
+
+- When cast operations like :cpp:func:`nb::cast() <cast>` fail to convert a
+  value, they previously raised a generic ``std::bad_cast`` exception that
+  loses the context of why the cast failed. When a Python error status is
+  available, they now preferentially raise :cpp:class:`nb::python_error
+  <python_error>`. This helps to track down issues with default argument
+  conversion. (PR `#1137 <https://github.com/wjakob/nanobind/pull/1137>`__).
+
+- Miscellaneous minor fixes and improvements. (PRs
+  `#1092 <https://github.com/wjakob/nanobind/pull/1092>`__,
+  `#1107 <https://github.com/wjakob/nanobind/pull/1107>`__,
+  `#1120 <https://github.com/wjakob/nanobind/pull/1120>`__,
+  `#1124 <https://github.com/wjakob/nanobind/pull/1124>`__.
+  `#1128 <https://github.com/wjakob/nanobind/pull/1128>`__,
+  `#1135 <https://github.com/wjakob/nanobind/pull/1135>`__,
+  `#1138 <https://github.com/wjakob/nanobind/pull/1138>`__,
+  `#1142 <https://github.com/wjakob/nanobind/pull/1142>`__,
+  commits
+  `d99b3f3 <https://github.com/wjakob/nanobind/commit/d99b3f3580b6c956f04851e8ed91e7eb5f259557>`__,
+  `0147904 <https://github.com/wjakob/nanobind/commit/0147904cee4baaa597780b22920f8cf0577af4d6>`__).
+
+- Minor documentation tweaks. (PRs
+  `#1109 <https://github.com/wjakob/nanobind/pull/1109>`__,
+  `#1108 <https://github.com/wjakob/nanobind/pull/1108>`__,
+  `#1114 <https://github.com/wjakob/nanobind/pull/1114>`__,
+  `#1117 <https://github.com/wjakob/nanobind/pull/1117>`__,
+  `#1134 <https://github.com/wjakob/nanobind/pull/1134>`__,
+  `#1132 <https://github.com/wjakob/nanobind/pull/1132>`__,
+  `#1090 <https://github.com/wjakob/nanobind/pull/1090>`__).
 
 Version 2.8.0 (July 16, 2025)
 -----------------------------
@@ -46,10 +134,10 @@ Version 2.8.0 (July 16, 2025)
   from source code literals. (PR `#1051
   <https://github.com/wjakob/nanobind/pull/1051>`__).
 
-- Added :cpp:func:`nb::dict::empty() <dict::empty>`,
+- Added the convenience methods :cpp:func:`nb::dict::empty() <dict::empty>`,
   :cpp:func:`nb::list::empty() <list::empty>`, :cpp:func:`nb::set::empty()
-  <set::empty>`, and :cpp:func:`nb::tuple::empty() <tuple::empty>` convenience
-  methods. (PR `#1052 <https://github.com/wjakob/nanobind/pull/1052>`__)
+  <set::empty>`, and :cpp:func:`nb::tuple::empty() <tuple::empty>`. (PR `#1052
+  <https://github.com/wjakob/nanobind/pull/1052>`__)
 
 - Added a :cpp:func:`nb::dict::get() <dict::get>` function to perform
   dictionary lookups with a fallback value in case of failures. (commit `d38284
@@ -59,11 +147,10 @@ Version 2.8.0 (July 16, 2025)
   when registering modules. However, multi-interpreter extensions remain
   unsupported. (PR `#1059 <https://github.com/wjakob/nanobind/pull/1059>`__).
 
-- Added :cpp:class:`nb::frozenset` that wraps the Python ``frozenset`` type.
+- Added :cpp:class:`nb::frozenset <frozenset>` that wraps the Python ``frozenset`` type.
   (PR `#1068 <https://github.com/wjakob/nanobind/pull/1068>`__)
 
-- Miscellaneous fixes and improvements (
-  commits
+- Miscellaneous fixes and improvements (commits
   `d4b245 <https://github.com/wjakob/nanobind/commit/d4b245ad69f729c3d2095be4c1cb5b94810dae26>`__,
   `667451 <https://github.com/wjakob/nanobind/commit/667451fb4566dcd7151d64d81e118f9ba194a889>`__,
   `62fc99 <https://github.com/wjakob/nanobind/commit/62fc996018d9ea4d51af9c86cf008c2562b4eeab>`__,