int(python): unify pybind11 and nanobind into single-source bindings

Remove the parallel src/python-nanobind/ tree and compile one set of
binding sources per build, selected by OIIO_PYTHON_BINDINGS_BACKEND
(pybind11 or nanobind; drop the "both" mode).

Add py_backend.h with namespace py = pybind11|nanobind and small
oiio_py:: helpers/macros only where the APIs differ. Migrate roi,
typedesc, imagespec, and paramvalue to dual-backend declare_* sources;
fold the former py_oiio_nb helpers and partial module init into
py_oiio.h / py_oiio.cpp behind #if OIIO_PY_BACKEND_NANOBIND.

Install nanobind modules into the same site-packages/OpenImageIO tree
as pybind11 (no separate nanobind package or duplicate tests). Update
CMake, CI, and INSTALL.md accordingly; move MIGRATION_STATUS.md into
src/python/.

Materialize string_view returns as std::string in py_imagespec.cpp so
nanobind can convert them to Python str.

Assisted-by: Cursor / Auto
Signed-off-by: Aleksandr Motsjonov <soswow@gmail.com>

Author: soswow

.github/workflows/ci.yml

@@ -300,7 +300,7 @@ jobs:
 
           - desc: latest releases gcc15 C++23 py3.12 avx2 exr3.4 ocio2.4
             nametag: linux-latest-releases
-            oiio_python_bindings_backend: both
+            oiio_python_bindings_backend: nanobind
             runner: ubuntu-24.04
             # cc_compiler: gcc-13
             # cxx_compiler: g++-13
@@ -601,7 +601,7 @@ jobs:
           - desc: MacOS-14-ARM aclang15/C++20/py3.13
             runner: macos-14
             nametag: macos14-arm-py313
-            oiio_python_bindings_backend: both
+            oiio_python_bindings_backend: nanobind
             cc_compiler: /usr/bin/clang
             cxx_compiler: /usr/bin/clang++
             cxx_std: 20
@@ -685,4 +685,4 @@ jobs:
             ctest_test_timeout: "240"
             setenvs: export OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1
             benchmark: 1
-            oiio_python_bindings_backend: both
+            oiio_python_bindings_backend: nanobind

CMakeLists.txt

@@ -314,12 +314,7 @@ else ()
     set (_py_dev_found Python3_Development.Module_FOUND)
 endif ()
 if (USE_PYTHON AND ${_py_dev_found} AND NOT BUILD_OIIOUTIL_ONLY)
-    if (OIIO_BUILD_PYTHON_PYBIND11)
-        add_subdirectory (src/python)
-    endif ()
-    if (OIIO_BUILD_PYTHON_NANOBIND)
-        add_subdirectory (src/python-nanobind)
-    endif ()
+    add_subdirectory (src/python)
 else ()
     message (STATUS "Not building Python bindings: USE_PYTHON=${USE_PYTHON}, Python3_Development.Module_FOUND=${Python3_Development.Module_FOUND}")
 endif ()

INSTALL.md

@@ -44,8 +44,8 @@ NEW or CHANGED MINIMUM dependencies since the last major release are **bold**.
      * Python >= 3.9 (tested through 3.13).
      * pybind11 >= 2.7 (tested through 3.0)
      * NumPy (tested through 2.4.4)
-     * If you enable the optional nanobind (WIP) backend for source/CMake
-       builds (`OIIO_PYTHON_BINDINGS_BACKEND` is `nanobind` or `both`):
+     * If you enable the nanobind (WIP) backend for source/CMake builds
+       (`OIIO_PYTHON_BINDINGS_BACKEND=nanobind`):
          * nanobind discoverable by CMake, or installed in the active Python
            environment so `python -m nanobind --cmake_dir` works
  * If you want support for PNG files:
@@ -163,11 +163,10 @@ Make wrapper (`make PkgName_ROOT=...`).
 
 `USE_PYTHON=0` : Omits building the Python bindings.
 
-`OIIO_PYTHON_BINDINGS_BACKEND=pybind11|nanobind|both` : Select which Python
-binding backend(s) to configure for source/CMake builds. `both` keeps the
-existing pybind11 module and also builds the nanobind (WIP) module. The
-Python packaging path driven by `pyproject.toml` still targets the production
-pybind11 bindings today.
+`OIIO_PYTHON_BINDINGS_BACKEND=pybind11|nanobind` : Select the Python binding
+backend for source/CMake builds (`pybind11` is the default production
+backend; `nanobind` is the in-progress migration backend). The Python
+packaging path driven by `pyproject.toml` still targets pybind11 today.
 
 `OIIO_BUILD_TESTS=0` : Omits building tests (you probably don't need them
 unless you are a developer of OIIO or want to verify that your build
@@ -259,7 +258,7 @@ Additionally, a few helpful modifiers alter some build-time options:
 | make USE_QT=0 ...             |  Skip anything that needs Qt                                              |
 | make MYCC=xx MYCXX=yy ...     |  Use custom compilers                                                     |
 | make USE_PYTHON=0 ...         |  Don't build the Python binding                                           |
-| make OIIO_PYTHON_BINDINGS_BACKEND=both ... | For source/CMake builds, build the existing pybind11 bindings and the nanobind (WIP) module |
+| make OIIO_PYTHON_BINDINGS_BACKEND=nanobind ... | For source/CMake builds, use the nanobind (WIP) Python bindings instead of pybind11 |
 | make BUILD_SHARED_LIBS=0      |  Build static library instead of shared                                   |
 | make IGNORE_HOMEBREWED_DEPS=1 |  Ignore homebrew-managed dependencies                                     |
 | make LINKSTATIC=1 ...         |  Link with static external libraries when possible                        |

src/cmake/externalpackages.cmake

@@ -118,10 +118,10 @@ endif()
 if (USE_PYTHON)
     find_python()
 endif ()
-if (USE_PYTHON AND OIIO_BUILD_PYTHON_PYBIND11)
+if (USE_PYTHON AND OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11")
     checked_find_package (pybind11 REQUIRED VERSION_MIN 2.7)
 endif ()
-if (USE_PYTHON AND OIIO_BUILD_PYTHON_NANOBIND)
+if (USE_PYTHON AND OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
     discover_nanobind_cmake_dir()
     checked_find_package (nanobind CONFIG REQUIRED)
 endif ()

src/cmake/pythonutils.cmake

@@ -9,30 +9,16 @@ option (PYLIB_INCLUDE_SONAME "If ON, soname/soversion will be set for Python mod
 option (PYLIB_LIB_PREFIX "If ON, prefix the Python module with 'lib'" OFF)
 set (PYMODULE_SUFFIX "" CACHE STRING "Suffix to add to Python module init namespace")
 set (OIIO_PYTHON_BINDINGS_BACKEND "pybind11" CACHE STRING
-     "Which Python binding backend(s) to build: pybind11, nanobind, or both")
+     "Which Python binding backend to build: pybind11 or nanobind")
 set_property (CACHE OIIO_PYTHON_BINDINGS_BACKEND PROPERTY STRINGS
-              pybind11 nanobind both)
+              pybind11 nanobind)
 
-# Normalize and validate the user-facing backend selector early so the rest
-# of the file can make simple boolean decisions.
 string (TOLOWER "${OIIO_PYTHON_BINDINGS_BACKEND}" OIIO_PYTHON_BINDINGS_BACKEND)
-if (NOT OIIO_PYTHON_BINDINGS_BACKEND MATCHES "^(pybind11|nanobind|both)$")
+if (NOT OIIO_PYTHON_BINDINGS_BACKEND MATCHES "^(pybind11|nanobind)$")
     message (FATAL_ERROR
-             "OIIO_PYTHON_BINDINGS_BACKEND must be one of: pybind11, nanobind, both")
+             "OIIO_PYTHON_BINDINGS_BACKEND must be pybind11 or nanobind")
 endif ()
 
-# Derive internal switches used by the top-level CMakeLists and the Python
-# helper macros below.
-set (OIIO_BUILD_PYTHON_PYBIND11 OFF)
-set (OIIO_BUILD_PYTHON_NANOBIND OFF)
-if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11"
-        OR OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "both")
-    set (OIIO_BUILD_PYTHON_PYBIND11 ON)
-endif ()
-if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind"
-        OR OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "both")
-    set (OIIO_BUILD_PYTHON_NANOBIND ON)
-endif ()
 if (WIN32)
     set (PYLIB_LIB_TYPE SHARED CACHE STRING "Type of library to build for python module (MODULE or SHARED)")
 else ()
@@ -79,7 +65,7 @@ macro (find_python)
                                 Python3_Development.Module_FOUND
                                 Python3_Interpreter_FOUND )
 
-    if (OIIO_BUILD_PYTHON_NANOBIND)
+    if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
         # nanobind's CMake package expects the generic FindPython targets and
         # variables (Python::Module, Python_EXECUTABLE, etc.), not the
         # versioned Python3::* targets that the rest of OIIO uses today.
@@ -232,7 +218,7 @@ endmacro ()
 
 macro (setup_python_module_nanobind)
     cmake_parse_arguments (lib "" "TARGET;MODULE"
-                           "SOURCES;LIBS;INCLUDES;SYSTEM_INCLUDE_DIRS;PACKAGE_FILES"
+                           "SOURCES;LIBS;INCLUDES;SYSTEM_INCLUDE_DIRS"
                            ${ARGN})
 
     set (target_name ${lib_TARGET})
@@ -264,24 +250,19 @@ macro (setup_python_module_nanobind)
                            DEBUG_POSTFIX "")
 
     if (SKBUILD)
-        set (_nanobind_install_dir .)
-    else ()
-        set (_nanobind_install_dir ${PYTHON_SITE_DIR})
+        set (PYTHON_SITE_DIR .)
     endif ()
 
-    # Keep nanobind modules isolated in the build tree so they don't alter
-    # how the existing top-level OpenImageIO module is imported during tests.
     set_target_properties (${target_name} PROPERTIES
-            LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/nanobind/OpenImageIO
-            ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/nanobind/OpenImageIO
+            LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/site-packages
+            ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/site-packages
             )
 
     install (TARGETS ${target_name}
-             RUNTIME DESTINATION ${_nanobind_install_dir} COMPONENT user
-             LIBRARY DESTINATION ${_nanobind_install_dir} COMPONENT user)
+             RUNTIME DESTINATION ${PYTHON_SITE_DIR} COMPONENT user
+             LIBRARY DESTINATION ${PYTHON_SITE_DIR} COMPONENT user)
+
+    install (FILES __init__.py stubs/OpenImageIO/__init__.pyi stubs/OpenImageIO/py.typed
+             DESTINATION ${PYTHON_SITE_DIR} COMPONENT user)
 
-    if (lib_PACKAGE_FILES)
-        install (FILES ${lib_PACKAGE_FILES}
-                 DESTINATION ${_nanobind_install_dir} COMPONENT user)
-    endif ()
 endmacro ()

src/cmake/testing.cmake

@@ -247,25 +247,15 @@ macro (oiio_add_all_tests)
     # libraries to run correctly.
     if (USE_PYTHON AND NOT BUILD_OIIOUTIL_ONLY AND NOT SANITIZE)
         if (WIN32)
-            # On Windows CI we run the install target before tests. Use the
-            # installed package path to avoid multi-config output layout quirks.
             set (_installed_python_site_packages
                 "${CMAKE_INSTALL_PREFIX}/${PYTHON_SITE_ROOT_DIR}")
-            oiio_tests_pythonpath_env_entry (_pybind_tests_pythonpath
+            oiio_tests_pythonpath_env_entry (_python_tests_pythonpath
                 "${_installed_python_site_packages}")
         else ()
-            oiio_tests_pythonpath_env_entry (_pybind_tests_pythonpath
+            oiio_tests_pythonpath_env_entry (_python_tests_pythonpath
                 "${CMAKE_BINARY_DIR}/lib/python/site-packages")
         endif ()
-        oiio_tests_pythonpath_env_entry (_nanobind_tests_pythonpath
-            "${CMAKE_BINARY_DIR}/lib/python/nanobind")
-        set (nanobind_python_tests
-             python-imagespec
-             python-paramlist
-             python-roi
-             python-typedesc)
-        set (nanobind_python_test_suffix ".nanobind")
-        if (OIIO_BUILD_PYTHON_PYBIND11)
+        if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11")
             oiio_add_tests (
                 docs-examples-python
                 python-colorconfig
@@ -279,23 +269,20 @@ macro (oiio_add_all_tests)
                 python-texturesys
                 python-typedesc
                 filters
-                ENVIRONMENT "${_pybind_tests_pythonpath}"
+                ENVIRONMENT "${_python_tests_pythonpath}"
                 )
-            # These Python tests also need access to oiio-images
             oiio_add_tests (
                 python-imageinput python-imagebufalgo
                 IMAGEDIR oiio-images
-                ENVIRONMENT "${_pybind_tests_pythonpath}"
+                ENVIRONMENT "${_python_tests_pythonpath}"
                 )
-        else ()
-            set (nanobind_python_test_suffix "")
-        endif ()
-
-        if (OIIO_BUILD_PYTHON_NANOBIND)
+        elseif (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
             oiio_add_tests (
-                ${nanobind_python_tests}
-                SUFFIX ${nanobind_python_test_suffix}
-                ENVIRONMENT "${_nanobind_tests_pythonpath}"
+                python-imagespec
+                python-paramlist
+                python-roi
+                python-typedesc
+                ENVIRONMENT "${_python_tests_pythonpath}"
                 )
         endif ()
     endif ()
@@ -317,7 +304,7 @@ macro (oiio_add_all_tests)
 
     oiio_add_tests ( python-imagebufalgo
         FOUNDVAR hwy_FOUND
-        ENABLEVAR OIIO_USE_HWY  USE_PYTHON OIIO_BUILD_PYTHON_PYBIND11
+        ENABLEVAR OIIO_USE_HWY  USE_PYTHON
         DISABLEVAR BUILD_OIIOUTIL_ONLY SANITIZE
         SUFFIX ".hwy"
         ENVIRONMENT "OPENIMAGEIO_ENABLE_HWY=1"