First big round of updates

- Update pymetabind
- Complete nanobind documentation of the new feature
- Change "foreign" to "interop" in some places so that the word "foreign" is more consistently used for the other framework rather than the information exchange between them
- Allow enum types to participate in interop
- Allow nanobind to register implicit conversions from foreign types to nanobind types

Author: oremanj

cmake/nanobind-config.cmake

@@ -238,7 +238,7 @@ function (nanobind_build_library TARGET_NAME)
   endif()
 
   if (TARGET_NAME MATCHES "-local")
-    target_compile_definitions(${TARGET_NAME} PRIVATE NB_DISABLE_FOREIGN)
+    target_compile_definitions(${TARGET_NAME} PRIVATE NB_DISABLE_INTEROP)
   endif()
 
   # Nanobind performs many assertion checks -- detailed error messages aren't

docs/api_cmake.rst

@@ -111,9 +111,9 @@ The high-level interface consists of just one CMake command:
           If this explanation sounds confusing, then you can ignore it. See the
           detailed description below for more information on this step.
       * - ``NO_INTEROP``
-        - Remove support for interoperability with other Python binding
-          frameworks. If you don't need it in your environment, this offers
-          a minor performance and code size benefit.
+        - Remove support for :ref:`interoperability with other Python binding
+          frameworks <interop>`. If you don't need it in your environment, this
+          offers a minor performance and code size benefit.
 
    :cmake:command:`nanobind_add_module` performs the following
    steps to produce bindings.

docs/api_core.rst

@@ -3130,12 +3130,24 @@ Global flags
    functions are still alive when the Python interpreter shuts down. Call this
    function to disable or re-enable leak warnings.
 
+   The configuration affected by this function is global to a :ref:`nanobind
+   domain <type-visibility>`. If you use it, you are encouraged to isolate your
+   extension from others by passing the ``NB_DOMAIN`` parameter to the
+   :cmake:command:`nanobind_add_module()` CMake command, so that your choices
+   don't need to impact unrelated extensions.
+
 .. cpp:function:: void set_implicit_cast_warnings(bool value) noexcept
 
    By default, nanobind loudly complains when it attempts to perform an
    implicit conversion, and when that conversion is not successful. Call this
    function to disable or re-enable the warnings.
 
+   The configuration affected by this function is global to a :ref:`nanobind
+   domain <type-visibility>`. If you use it, you are encouraged to isolate your
+   extension from others by passing the ``NB_DOMAIN`` parameter to the
+   :cmake:command:`nanobind_add_module()` CMake command, so that your choices
+   don't need to impact unrelated extensions.
+
 .. cpp:function:: inline bool is_alive() noexcept
 
    The function returns ``true`` when nanobind is initialized and ready for
@@ -3144,6 +3156,85 @@ Global flags
    this liveness status can be useful to avoid operations that are illegal in
    the latter context.
 
+Interoperability
+----------------
+
+See the :ref:`separate interoperability documentation <interop>` for important
+additional information and caveats about this feature.
+
+.. cpp:function:: void interoperate_by_default(bool export_all = true, bool import_all = true)
+
+   Configure whether this :ref:`nanobind domain <type-visibility>` should exchange
+   type information with other binding libraries (and other nanobind domains)
+   so that functions bound in one can accept and return objects whose types are
+   bound in another. The default, if :cpp:func:`interoperate_by_default` is not
+   called, is to exchange such information only when requested on a per-type
+   basis via calls to :cpp:func:`import_for_interop` or
+   :cpp:func:`export_for_interop`.
+
+   By specifying arguments to :cpp:func:`interoperate_by_default`, it is
+   possible to separately configure whether to enable automatic sharing of
+   our types with others (*export_all*) or automatic use of types shared by
+   others (*import_all*). Once either type of automatic sharing is enabled,
+   it remains enabled for the lifetime of the Python interpreter.
+
+   Automatic export is equivalent to calling :cpp:func:`export_for_interop` on
+   each type produced by a :cpp:class:`nb::class_` or :cpp:struct:`nb::enum_`
+   binding statement in this nanobind domain.
+
+   Automatic import is equivalent to calling :cpp:func:`import_for_interop` on
+   each type exported by a different binding library or nanobind domain, as
+   long as that library is written in C++ and uses a compatible platform ABI.
+   In order to interoperate with a type binding that was created in another
+   language, including pure C, you must still make an explicit call to
+   :cpp:func:`import_for_interop`, providing a template argument so that
+   nanobind can tell which C++ type should be associated with it.
+
+   Enabling automatic export or import affects both types that have already been
+   bound and types that are yet to be bound.
+
+   The configuration affected by this function is global to a nanobind
+   domain. If you use it, you are encouraged to isolate your extension from
+   others by passing the ``NB_DOMAIN`` parameter to the
+   :cmake:command:`nanobind_add_module()` CMake command, so that your choices
+   don't need to impact unrelated extensions.
+
+.. cpp:function:: template <typename T = void> void import_for_interop(handle type)
+
+   Make the Python type object *type*, which was bound using a different binding
+   framework (or different nanobind domain) and then exported using a facility
+   like our :cpp:func:`export_for_interop`, be available so that functions bound
+   in this nanobind domain can accept and return its instances using the
+   C++ type ``T``, or the C++ type that was specified when *type* was bound.
+
+   If no template argument is specified, then *type* must have been bound by
+   another C++ binding library that uses the same :ref:`platform ABI
+   <type-visibility>` as us; the C++ type will be determined by inspecting its
+   binding.
+
+   If a template argument is specified, then nanobind associates that C++ type
+   with the given Python type, trusting rather than verifying that they match.
+   The C++ type ``T`` must perfectly match the memory layout and ABI of the
+   structure used by whoever bound the Python *type*.
+   This is the only way to import types written in other languages than C++
+   (including those in plain C), since nanobind needs a ``std::type_info`` for
+   its type lookups and non-C++ bindings don't provide those directly.
+
+   Repeatedly importing the same Python type as the same C++ type is idempotent.
+   Importing the same Python type as multiple different C++ types will fail.
+
+   A descriptive C++ exception will be thrown if the import fails.
+
+.. cpp:function:: void export_for_interop(handle type)
+
+   Make the Python type object *type*, which was bound in this nanobind domain,
+   be available for import by other binding libraries and other nanobind
+   domains. If they do so, then their bound functions will be able to accept
+   and return instances of *type*.
+
+   Repeatedly exporting the same type is idempotent.
+
+
 Miscellaneous
 -------------
 

docs/changelog.rst

@@ -15,6 +15,24 @@ case, both modules must use the same nanobind ABI version, or they will be
 isolated from each other. Releases that don't explicitly mention an ABI version
 below inherit that of the preceding release.
 
+Version TBD (unreleased)
+------------------------
+
+.. TODO: update the pybind11 version number below before releasing
+
+- nanobind has adopted the new `pymetabind
+  <https://github.com/hudson-trading/pymetabind>`__ standard for interoperating
+  with other Python binding libraries (including other ABI versions of
+  nanobind). When the interoperability feature is activated, which in most cases
+  is as simple as writing :cpp:func:`nb::interoperate_by_default()
+  <interoperate_by_default>`, a function or method that is bound using nanobind
+  can accept and return values of types that were bound using other binding
+  libraries that support pymetabind, notably including pybind11 versions !TBD!
+  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.
+
 Version 2.8.0 (July 16, 2025)
 -----------------------------
 
@@ -295,7 +313,7 @@ Version 2.3.0
 
 There is no version 2.3.0 due to a deployment mishap.
 
-- Added casters for `Eigen::Map<Eigen::SparseMatrix<...>` types from the `Eigen library
+- Added casters for ``Eigen::Map<Eigen::SparseMatrix<...>`` types from the `Eigen library
   <https://eigen.tuxfamily.org/index.php?title=Main_Page>`__. (PR `#782
   <https://github.com/wjakob/nanobind/pull/782>`_).
 

docs/faq.rst

@@ -233,33 +233,35 @@ will:
 
 .. _type-visibility:
 
-How can I avoid conflicts with other projects using nanobind?
--------------------------------------------------------------
-
-Suppose that a type binding in your project conflicts with another extension, for
-example because both expose a common type (e.g., ``std::latch``). nanobind will
-warn whenever it detects such a conflict:
+How can I control whether two extension modules see each other's types?
+-----------------------------------------------------------------------
+
+nanobind creates a variety of internal data structures to support the bindings
+you ask it to make. These are not isolated to a single extension module,
+because it's useful for large binding projects to be able to split related
+bindings into multiple extensions without losing their ability to work with
+one another's types. Instead, extension modules are divided into nanobind
+*domains* based on two attributes: an automatically determined string (the
+nanobind "ABI tag") that captures compatibility-relevant aspects of their
+build environments and nanobind versions, and an ``NB_DOMAIN`` string that
+may be provided at build time (as shown below).
+If multiple extension modules share the same ABI tag and the same ``NB_DOMAIN``
+string, they will wind up in the same nanobind domain, which allows them to
+work together exactly as if they were one big extension.
+
+Sometimes, this causes problems. For example, you might expose a binding
+for a commonly used type (such as ``std::latch``) that some other nanobind
+extension in your Python interpreter also happens to provide a binding for.
+nanobind will warn whenever it detects such a conflict:
 
 .. code-block:: text
 
   RuntimeWarning: nanobind: type 'latch' was already registered!
 
 In the worst case, this could actually break both packages (especially if the
-bindings of the two packages expose an inconsistent/incompatible API).
-
-The higher-level issue here is that nanobind will by default try to make type
-bindings visible across extensions because this is helpful to partition large
-binding projects into smaller parts. Such information exchange requires that
-the extensions:
-
-- use the same nanobind *ABI version* (see the :ref:`Changelog <changelog>` for details).
-- use the same compiler (extensions built with GCC and Clang are isolated from each other).
-- use ABI-compatible versions of the C++ library.
-- use the stable ABI interface consistently (stable and unstable builds are isolated from each other).
-- use debug/release mode consistently (debug and release builds are isolated from each other).
-
-In addition, nanobind provides a feature to intentionally scope extensions to a
-named domain to avoid conflicts with other extensions. To do so, specify the
+bindings of the two packages expose an inconsistent/incompatible API). So it's
+useful to be able to enforce a boundary between extensions sometimes, even if
+they would otherwise be ABI-compatible. To do so, you can specify the
 ``NB_DOMAIN`` parameter in CMake:
 
 .. code-block:: cmake
@@ -268,8 +270,54 @@ named domain to avoid conflicts with other extensions. To do so, specify the
                        NB_DOMAIN my_project
                        my_ext.cpp)
 
-In this case, inter-extension type visibility is furthermore restricted to
-extensions in the ``"my_project"`` domain.
+Two extensions can only be in the same nanobind domain if either they both
+specify the same value for that parameter (``"my_project"`` in this case) or
+neither one specifies the parameter.
+
+As mentioned above, two extensions can also only be in the same nanobind domain
+if they share the same ABI tag. This is determined in two parts, as follows:
+
+- They must use compatible *platform ABI*, so that (for example) a
+  ``std::vector<int>`` created in one can be safely used in the other.
+  That means:
+
+  - They must use the same C++ standard library (MSVC, libc++, or libstdc++),
+    and the same ABI version of it. For example, extensions that use libstdc++
+    must match in terms of whether they use the pre- or post-C++11 ABI, and
+    extensions that use libc++ must use the same `libc++ ABI version
+    <https://libcxx.llvm.org/DesignDocs/ABIVersioning.html>`__.
+
+  - On Windows, they must use the same compiler (MSVC, mingw, or cygwin).
+
+  - If compiled using MSVC, they must use the same major version of the
+    compiler, the same multi-threading style (dynamic ``/MD``,
+    static ``/MT``, or single-threaded), and they must match in terms of
+    whether or not they are built in debugging mode.
+
+- They must use compatible *nanobind ABI*, so that the nanobind internal data
+  structures created in one can be safely used in the other. That means:
+
+  - They must use the same nanobind *ABI version*; see the
+    :ref:`Changelog <changelog>` for details.
+
+  - They must be consistent in their use of Python's stable ABI: either
+    both built against the stable ABI (cmake ``STABLE_ABI`` flag) or both not.
+
+  - They must be consistent in their use of free-threading: either both
+    built with free-threading support (cmake ``FREE_THREADED`` flag) or both not.
+
+  - They must either both use released versions of nanobind or both be built
+    from Git development snapshots, rather than a mix of the two.
+
+If you want to share some types between two extensions that have the same
+platform ABI (the first category in the above list), but are in different
+nanobind domains due to using different nanobind ABI or different specified
+``NB_DOMAIN`` strings, all is not lost! The :ref:`interoperability support
+<interop>` between nanobind and other binding libraries also provides
+interoperability between different nanobind domains, as long as the platform
+ABI matches. It must be specifically enabled, and there are a few things it
+can't do, but for most purposes it's hard to tell the difference from operating
+within the same domain. See the linked documentation for more details.
 
 Can I use nanobind without RTTI or C++ exceptions?
 --------------------------------------------------

docs/index.rst

@@ -128,6 +128,7 @@ The nanobind logo was designed by `AndoTwin Studio
    packaging
    typing
    utilities
+   interop
 
 .. toctree::
    :caption: Advanced

docs/refleaks.rst

@@ -58,8 +58,8 @@ easily disable them by calling :cpp:func:`nb::set_leak_warnings()
     }
 
 Note that is a *global flag* shared by all nanobind extension libraries in the
-same ABI domain. When changing global flags, please isolate your extension from
-others by passing the ``NB_DOMAIN`` parameter to the
+same `nanobind domain <type-visibility>`. When changing global flags, please
+isolate your extension from others by passing the ``NB_DOMAIN`` parameter to the
 :cmake:command:`nanobind_add_module()` CMake command:
 
 .. code-block:: cmake

include/nanobind/nb_cast.h

@@ -189,15 +189,16 @@ struct type_caster<T, enable_if_t<std::is_arithmetic_v<T> && !is_std_char_v<T>>>
 
 template <typename T>
 struct type_caster<T, enable_if_t<std::is_enum_v<T>>> {
-    NB_INLINE bool from_python(handle src, uint8_t flags, cleanup_list *) noexcept {
+    NB_INLINE bool from_python(handle src, uint8_t flags, cleanup_list *cleanup) noexcept {
         int64_t result;
-        bool rv = enum_from_python(&typeid(T), src.ptr(), &result, flags);
+        bool rv = enum_from_python(&typeid(T), src.ptr(), &result, sizeof(T),
+                                   flags, cleanup);
         value = (T) result;
         return rv;
     }
 
     NB_INLINE static handle from_cpp(T src, rv_policy, cleanup_list *) noexcept {
-        return enum_from_cpp(&typeid(T), (int64_t) src);
+        return enum_from_cpp(&typeid(T), (int64_t) src, sizeof(T));
     }
 
     NB_TYPE_CASTER(T, const_name<T>())
@@ -504,6 +505,8 @@ template <typename Type_> struct type_caster_base : type_caster_base_tag {
         } else {
             const std::type_info *type_p =
                 (!has_type_hook && ptr) ? &typeid(*ptr) : nullptr;
+            if (type_p && (void *) ptr != dynamic_cast<void *>(ptr))
+                type_p = nullptr; // don't try to downcast from a non-primary base
             return nb_type_put_p(type, type_p, ptr, policy, cleanup);
         }
     }

include/nanobind/nb_class.h

@@ -106,8 +106,8 @@ struct enum_tbl_t {
 /// Information about a type that persists throughout its lifetime
 struct type_data {
     uint32_t size;
-    uint32_t align : 8;
-    uint32_t flags : 24;
+    uint32_t align : 8; // always zero for an enum
+    uint32_t flags : 24; // type_flags or enum_flags
     const char *name;
     const std::type_info *type;
     PyTypeObject *type_py;
@@ -212,6 +212,7 @@ struct enum_init_data {
     PyObject *scope;
     const char *name;
     const char *docstr;
+    uint32_t size;
     uint32_t flags;
 };
 
@@ -333,15 +334,16 @@ inline void *type_get_slot(handle h, int slot_id) {
 }
 
 // nanobind interoperability with other binding frameworks
-inline void set_foreign_type_defaults(bool export_all, bool import_all) {
-    detail::nb_type_set_foreign_defaults(export_all, import_all);
+inline void interoperate_by_default(bool export_all = true,
+                                    bool import_all = true) {
+    detail::nb_type_set_interop_defaults(export_all, import_all);
 }
 template <class T = void>
-inline void import_foreign_type(handle type) {
+inline void import_for_interop(handle type) {
     detail::nb_type_import(type.ptr(),
                            std::is_void_v<T> ? nullptr : &typeid(T));
 }
-inline void export_type_to_foreign(handle type) {
+inline void export_for_interop(handle type) {
     detail::nb_type_export(type.ptr());
 }
 
@@ -787,6 +789,7 @@ template <typename T> class enum_ : public object {
     NB_INLINE enum_(handle scope, const char *name, const Extra &... extra) {
         detail::enum_init_data ed { };
         ed.type = &typeid(T);
+        ed.size = sizeof(T);
         ed.scope = scope.ptr();
         ed.name = name;
         ed.flags = std::is_signed_v<Underlying>