enhance(python): unify Python binding configuration for pybind11 and nanobind

Refactor CMake configuration to support both pybind11 and nanobind backends through a single option, OIIO_PYTHON_BINDINGS_BACKEND, allowing for flexible builds. Update CMakeLists.txt to conditionally include source directories based on the selected backend. Modify INSTALL.md to clarify usage instructions for enabling either backend or both. Adjust CI workflows to build with the 'both' option, ensuring compatibility with both binding systems. Update various source files to streamline the integration of nanobind and pybind11, including changes to installation paths and test configurations.

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: nanobind
+            oiio_python_bindings_backend: both
             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: nanobind
+            oiio_python_bindings_backend: both
             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: nanobind
+            oiio_python_bindings_backend: both

CMakeLists.txt

@@ -314,7 +314,14 @@ else ()
     set (_py_dev_found Python3_Development.Module_FOUND)
 endif ()
 if (USE_PYTHON AND ${_py_dev_found} AND NOT BUILD_OIIOUTIL_ONLY)
-    add_subdirectory (src/python)
+    if (OIIO_BUILD_PYTHON_PYBIND11
+            OR OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
+        add_subdirectory (src/python)
+    endif ()
+    if (OIIO_BUILD_PYTHON_NANOBIND
+            AND OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "both")
+        add_subdirectory (src/python-nanobind)
+    endif ()
 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 nanobind (WIP) backend for source/CMake builds
-       (`OIIO_PYTHON_BINDINGS_BACKEND=nanobind`):
+     * If you enable the optional nanobind (WIP) backend for source/CMake
+       builds (`OIIO_PYTHON_BINDINGS_BACKEND` is `nanobind` or `both`):
          * 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,10 +163,11 @@ Make wrapper (`make PkgName_ROOT=...`).
 
 `USE_PYTHON=0` : Omits building the Python bindings.
 
-`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_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_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
@@ -258,7 +259,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=nanobind ... | For source/CMake builds, use the nanobind (WIP) Python bindings instead of pybind11 |
+| make OIIO_PYTHON_BINDINGS_BACKEND=both ... | For source/CMake builds, build the existing pybind11 bindings and the nanobind (WIP) module |
 | 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_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11")
+if (USE_PYTHON AND OIIO_BUILD_PYTHON_PYBIND11)
     checked_find_package (pybind11 REQUIRED VERSION_MIN 2.7)
 endif ()
-if (USE_PYTHON AND OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
+if (USE_PYTHON AND OIIO_BUILD_PYTHON_NANOBIND)
     discover_nanobind_cmake_dir()
     checked_find_package (nanobind CONFIG REQUIRED)
 endif ()

src/cmake/pythonutils.cmake

@@ -9,14 +9,29 @@ 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 to build: pybind11 or nanobind")
+     "Which Python binding backend(s) to build: pybind11, nanobind, or both")
 set_property (CACHE OIIO_PYTHON_BINDINGS_BACKEND PROPERTY STRINGS
-              pybind11 nanobind)
+              pybind11 nanobind both)
 
+# 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)$")
+if (NOT OIIO_PYTHON_BINDINGS_BACKEND MATCHES "^(pybind11|nanobind|both)$")
     message (FATAL_ERROR
-             "OIIO_PYTHON_BINDINGS_BACKEND must be pybind11 or nanobind")
+             "OIIO_PYTHON_BINDINGS_BACKEND must be one of: pybind11, nanobind, both")
+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)
@@ -65,7 +80,7 @@ macro (find_python)
                                 Python3_Development.Module_FOUND
                                 Python3_Interpreter_FOUND )
 
-    if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
+    if (OIIO_BUILD_PYTHON_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.
@@ -218,7 +233,7 @@ endmacro ()
 
 macro (setup_python_module_nanobind)
     cmake_parse_arguments (lib "" "TARGET;MODULE"
-                           "SOURCES;LIBS;INCLUDES;SYSTEM_INCLUDE_DIRS"
+                           "SOURCES;LIBS;INCLUDES;SYSTEM_INCLUDE_DIRS;PACKAGE_FILES"
                            ${ARGN})
 
     set (target_name ${lib_TARGET})
@@ -249,20 +264,44 @@ macro (setup_python_module_nanobind)
                            OUTPUT_NAME ${lib_MODULE}
                            DEBUG_POSTFIX "")
 
-    if (SKBUILD)
-        set (PYTHON_SITE_DIR .)
-    endif ()
+    if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "both")
+        if (SKBUILD)
+            set (_nanobind_install_dir .)
+        else ()
+            set (_nanobind_install_dir ${PYTHON_SITE_DIR})
+        endif ()
 
-    set_target_properties (${target_name} PROPERTIES
-            LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/site-packages
-            ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/site-packages
-            )
+        # 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
+                )
 
-    install (TARGETS ${target_name}
-             RUNTIME DESTINATION ${PYTHON_SITE_DIR} COMPONENT user
-             LIBRARY DESTINATION ${PYTHON_SITE_DIR} COMPONENT user)
+        install (TARGETS ${target_name}
+                 RUNTIME DESTINATION ${_nanobind_install_dir} COMPONENT user
+                 LIBRARY DESTINATION ${_nanobind_install_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 ()
+    else ()
+        if (SKBUILD)
+            set (PYTHON_SITE_DIR .)
+        endif ()
+
+        set_target_properties (${target_name} PROPERTIES
+                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 ${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)
+    endif ()
 
 endmacro ()

src/cmake/testing.cmake

@@ -247,15 +247,25 @@ 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 (_python_tests_pythonpath
+            oiio_tests_pythonpath_env_entry (_pybind_tests_pythonpath
                 "${_installed_python_site_packages}")
         else ()
-            oiio_tests_pythonpath_env_entry (_python_tests_pythonpath
+            oiio_tests_pythonpath_env_entry (_pybind_tests_pythonpath
                 "${CMAKE_BINARY_DIR}/lib/python/site-packages")
         endif ()
-        if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11")
+        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)
             oiio_add_tests (
                 docs-examples-python
                 python-colorconfig
@@ -269,20 +279,23 @@ macro (oiio_add_all_tests)
                 python-texturesys
                 python-typedesc
                 filters
-                ENVIRONMENT "${_python_tests_pythonpath}"
+                ENVIRONMENT "${_pybind_tests_pythonpath}"
                 )
+            # These Python tests also need access to oiio-images
             oiio_add_tests (
                 python-imageinput python-imagebufalgo
                 IMAGEDIR oiio-images
-                ENVIRONMENT "${_python_tests_pythonpath}"
+                ENVIRONMENT "${_pybind_tests_pythonpath}"
                 )
-        elseif (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
+        else ()
+            set (nanobind_python_test_suffix "")
+        endif ()
+
+        if (OIIO_BUILD_PYTHON_NANOBIND)
             oiio_add_tests (
-                python-imagespec
-                python-paramlist
-                python-roi
-                python-typedesc
-                ENVIRONMENT "${_python_tests_pythonpath}"
+                ${nanobind_python_tests}
+                SUFFIX ${nanobind_python_test_suffix}
+                ENVIRONMENT "${_nanobind_tests_pythonpath}"
                 )
         endif ()
     endif ()
@@ -304,7 +317,7 @@ macro (oiio_add_all_tests)
 
     oiio_add_tests ( python-imagebufalgo
         FOUNDVAR hwy_FOUND
-        ENABLEVAR OIIO_USE_HWY  USE_PYTHON
+        ENABLEVAR OIIO_USE_HWY  USE_PYTHON OIIO_BUILD_PYTHON_PYBIND11
         DISABLEVAR BUILD_OIIOUTIL_ONLY SANITIZE
         SUFFIX ".hwy"
         ENVIRONMENT "OPENIMAGEIO_ENABLE_HWY=1"

src/python-nanobind/CMakeLists.txt

@@ -0,0 +1,36 @@
+# Copyright Contributors to the OpenImageIO project.
+# SPDX-License-Identifier: Apache-2.0
+# https://github.com/AcademySoftwareFoundation/OpenImageIO
+
+set (nanobind_srcs
+     py_oiio.cpp
+     py_paramvalue.cpp
+     py_roi.cpp
+     py_imagespec.cpp
+     py_typedesc.cpp)
+
+set (nanobind_src_paths "")
+foreach (src ${nanobind_srcs})
+    list (APPEND nanobind_src_paths
+          ${CMAKE_CURRENT_SOURCE_DIR}/../python/${src})
+endforeach ()
+
+set (nanobind_build_package_dir ${CMAKE_BINARY_DIR}/lib/python/nanobind/OpenImageIO)
+file (MAKE_DIRECTORY ${nanobind_build_package_dir})
+configure_file (__init__.py
+                ${nanobind_build_package_dir}/__init__.py
+                COPYONLY)
+
+setup_python_module_nanobind (
+    TARGET    PyOpenImageIONanobind
+    MODULE    _OpenImageIO
+    SOURCES   ${nanobind_src_paths}
+    LIBS      OpenImageIO
+    PACKAGE_FILES __init__.py
+)
+
+target_compile_definitions (PyOpenImageIONanobind
+                            PRIVATE OIIO_PY_BACKEND_NANOBIND
+                                    OIIO_PY_NANOBIND_ISOLATED_PACKAGE)
+target_include_directories (PyOpenImageIONanobind
+                            PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../python)

src/python-nanobind/__init__.py

@@ -0,0 +1,45 @@
+# Copyright Contributors to the OpenImageIO project.
+# SPDX-License-Identifier: Apache-2.0
+# https://github.com/AcademySoftwareFoundation/OpenImageIO
+
+import os
+import sys
+import platform
+
+_here = os.path.abspath(os.path.dirname(__file__))
+
+# Set $OpenImageIO_ROOT if not already set before importing helper modules.
+if not os.getenv("OpenImageIO_ROOT"):
+    if all([os.path.exists(os.path.join(_here, i)) for i in ["share", "bin", "lib"]]):
+        os.environ["OpenImageIO_ROOT"] = _here
+
+if platform.system() == "Windows":
+    # MSVC multi-config builds often put _OpenImageIO*.pyd under OpenImageIO/<Config>/
+    # while this __init__.py lives in OpenImageIO/. Extend the package search path
+    # so `from . import _OpenImageIO` resolves (no CMake per-config output juggling).
+    for _cfg in ("Release", "Debug", "RelWithDebInfo", "MinSizeRel"):
+        _subdir = os.path.join(_here, _cfg)
+        if os.path.isdir(_subdir) and _subdir not in __path__:
+            __path__.append(_subdir)
+
+    _bin_dir = os.path.join(_here, "bin")
+    if os.path.exists(_bin_dir):
+        os.add_dll_directory(_bin_dir)
+    elif sys.version_info >= (3, 8):
+        if os.getenv("OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH", "0") == "1":
+            for path in os.getenv("PATH", "").split(os.pathsep):
+                if os.path.exists(path) and path != ".":
+                    os.add_dll_directory(path)
+
+from . import _OpenImageIO as _ext  # noqa: E402
+from ._OpenImageIO import *  # type: ignore # noqa: E402, F401, F403
+
+__doc__ = """
+OpenImageIO Python package exposing the nanobind migration bindings.
+The production pybind11 bindings are not installed in this configuration.
+"""[1:-1]
+
+__version__ = getattr(_ext, "__version__", "")
+
+# TODO: Restore the Python CLI entry-point trampolines when the nanobind
+# package ships the full wheel-style bin/lib/share layout.

src/python/CMakeLists.txt

@@ -10,7 +10,7 @@ set (python_dual_backend_srcs
      py_imagespec.cpp
      py_paramvalue.cpp)
 
-if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11")
+if (OIIO_BUILD_PYTHON_PYBIND11)
     file (GLOB python_srcs *.cpp)
     setup_python_module (TARGET    PyOpenImageIO
                          MODULE    OpenImageIO
@@ -23,7 +23,9 @@ if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11")
                                UNITY_BUILD_BATCH_SIZE ${UNITY_SMALL_BATCH_SIZE})
     set_source_files_properties (${python_srcs} PROPERTIES
                                  UNITY_GROUP PyOpenImageIO)
-elseif (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
+endif ()
+
+if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind")
     setup_python_module_nanobind (
         TARGET    PyOpenImageIO
         MODULE    OpenImageIO

src/python/MIGRATION_STATUS.md

@@ -2,9 +2,11 @@
 
 Nanobind shares binding sources with pybind11 under `src/python/` (see
 `py_backend.h` and `python_dual_backend_srcs` in `CMakeLists.txt`). Configure
-with `-DOIIO_PYTHON_BINDINGS_BACKEND=nanobind` to build the nanobind target
-`PyOpenImageIO` / module `OpenImageIO`; nanobind-only code paths live in
-`py_oiio.h` / `py_oiio.cpp` behind `OIIO_PY_BACKEND_NANOBIND`.
+with `-DOIIO_PYTHON_BINDINGS_BACKEND=nanobind` for nanobind-only (`PyOpenImageIO`
+/ module `OpenImageIO` in site-packages), or `both` to also build
+`PyOpenImageIONanobind` (`_OpenImageIO` under `lib/python/nanobind/OpenImageIO`).
+Nanobind-only code paths live in `py_oiio.h` / `py_oiio.cpp` behind
+`OIIO_PY_BACKEND_NANOBIND`.
 
 ## Migrated — full parity with pybind (no known gaps for this surface)