ci: Exercise pybind11 and nanobind Python bindings in CI

- Add workflow input and env for OIIO_PYTHON_BINDINGS_BACKEND; run with
  backend=both on selected Linux, macOS, and Windows matrix rows.
- Pass the flag through ci-build.bash into CMake.
- Install pinned nanobind for CMake discovery (pip --require-hashes on Linux
  and Windows; Homebrew on macOS).
- Point nanobind Python tests at lib/python/nanobind (not per-$<CONFIG>).
- Extend the nanobind package __path__ on Windows for MSVC config output dirs.

Assisted-by: Cursor/Composer-2

Signed-off-by: Aleksandr Motsjonov <soswow@gmail.com>

Author: soswow

.github/workflows/build-steps.yml

@@ -88,6 +88,9 @@ on:
         type: string
       build_local_deps:
         type: string
+      oiio_python_bindings_backend:
+        type: string
+        default: ''
     secrets:
         PASSED_GITHUB_TOKEN:
           required: false
@@ -136,6 +139,7 @@ jobs:
       OpenImageIO_BUILD_LOCAL_DEPS: ${{inputs.build_local_deps}}
       SETENVS: ${{inputs.setenvs}}
       DEPCMDS: ${{inputs.depcmds}}
+      OIIO_PYTHON_BINDINGS_BACKEND: ${{ inputs.oiio_python_bindings_backend }}
 
     steps:
       - name: install nodejs20glibc2.17

.github/workflows/ci.yml

@@ -355,6 +355,7 @@ jobs:
       required_deps: ${{ matrix.required_deps || 'all' }}
       optional_deps: ${{ matrix.optional_deps || 'CUDAToolkit;DCMTK;JXL;Nuke;OpenGL;openjph;OpenVDB;Ptex;pystring;Qt5;R3DSDK;' }}${{matrix.optional_deps_append}}
       build_local_deps: ${{ matrix.build_local_deps }}
+      oiio_python_bindings_backend: ${{ matrix.oiio_python_bindings_backend || '' }}
     strategy:
       fail-fast: false
       matrix:
@@ -381,6 +382,7 @@ jobs:
 
           - desc: latest releases gcc13 C++20 py3.12 avx2 exr3.4 ocio2.4
             nametag: linux-latest-releases
+            oiio_python_bindings_backend: both
             runner: ubuntu-24.04
             cc_compiler: gcc-13
             cxx_compiler: g++-13
@@ -656,6 +658,7 @@ jobs:
       required_deps: ${{ matrix.required_deps || 'all' }}
       optional_deps: ${{ matrix.optional_deps || 'Nuke;R3DSDK;' }}${{matrix.optional_deps_append}}
       build_local_deps: ${{ matrix.build_local_deps }}
+      oiio_python_bindings_backend: ${{ matrix.oiio_python_bindings_backend || '' }}
     strategy:
       fail-fast: false
       matrix:
@@ -676,6 +679,7 @@ jobs:
           - desc: MacOS-14-ARM aclang15/C++20/py3.13
             runner: macos-14
             nametag: macos14-arm-py313
+            oiio_python_bindings_backend: both
             cc_compiler: /usr/bin/clang
             cxx_compiler: /usr/bin/clang++
             cxx_std: 20
@@ -739,6 +743,7 @@ jobs:
       required_deps: ${{ matrix.required_deps || 'all' }}
       optional_deps: ${{ matrix.optional_deps || 'BZip2;CUDAToolkit;DCMTK;FFmpeg;GIF;JXL;Libheif;LibRaw;Nuke;OpenCV;OpenGL;OpenJPEG;openjph;OpenCV;OpenVDB;Ptex;pystring;Qt5;Qt6;TBB;R3DSDK;${{matrix.optional_deps_append}}' }}
       build_local_deps: ${{ matrix.build_local_deps }}
+      oiio_python_bindings_backend: ${{ matrix.oiio_python_bindings_backend || '' }}
     strategy:
       fail-fast: false
       matrix:
@@ -753,6 +758,7 @@ jobs:
           - desc: Windows-2025 VS2022
             runner: windows-2025
             nametag: windows-2025
+            oiio_python_bindings_backend: both
             generator: "Visual Studio 17 2022"
             python_ver: "3.12"
             ctest_test_timeout: "240"

src/build-scripts/ci-build.bash

@@ -25,6 +25,10 @@ if [[ "$USE_SIMD" != "" ]] ; then
     OIIO_CMAKE_FLAGS="$OIIO_CMAKE_FLAGS -DUSE_SIMD=$USE_SIMD"
 fi
 
+if [[ -n "${OIIO_PYTHON_BINDINGS_BACKEND:-}" ]] ; then
+    OIIO_CMAKE_FLAGS="$OIIO_CMAKE_FLAGS -DOIIO_PYTHON_BINDINGS_BACKEND=${OIIO_PYTHON_BINDINGS_BACKEND}"
+fi
+
 if [[ -n "$CODECOV" ]] ; then
     OIIO_CMAKE_FLAGS="$OIIO_CMAKE_FLAGS -DCODECOV=${CODECOV}"
 fi

src/build-scripts/ci-requirements-nanobind.txt

@@ -0,0 +1,6 @@
+# CI-only: nanobind for CMake (`python -m nanobind --cmake_dir`). Used on Linux
+# (gh-installdeps) and Windows (gh-win-installdeps) with pip --require-hashes.
+# macOS CI uses `brew install nanobind` instead (install_homebrew_deps.bash).
+# When bumping pip pin: https://pypi.org/pypi/nanobind/<ver>/json → wheel sha256.
+nanobind==2.12.0 \
+    --hash=sha256:a10d3d88e691dcdf22696f9acd893fda3c5a05635763aea238829d274fcad480

src/build-scripts/gh-installdeps.bash

@@ -230,5 +230,16 @@ fi
 df -h .
 df -h /host/root || true
 
+# nanobind's CMake config is discovered via `python -m nanobind --cmake_dir`.
+# Version + wheel hash: src/build-scripts/ci-requirements-nanobind.txt (CodeQL / supply chain).
+if [[ "${OIIO_PYTHON_BINDINGS_BACKEND:-}" == "both" || "${OIIO_PYTHON_BINDINGS_BACKEND:-}" == "nanobind" ]] ; then
+    _oiio_nanobind_requirements_file="$PWD/src/build-scripts/ci-requirements-nanobind.txt"
+    if [[ "$ASWF_ORG" != ""  ]] ; then
+        time pip3 install -r "$_oiio_nanobind_requirements_file" --require-hashes || true
+    else
+        time pip3${PIP_SUFFIX} install -r "$_oiio_nanobind_requirements_file" --require-hashes
+    fi
+fi
+
 # Save the env for use by other stages
 src/build-scripts/save-env.bash

src/build-scripts/gh-win-installdeps.bash

@@ -39,6 +39,11 @@ elif [[ "$PYTHON_VERSION" == "3.14" ]] ; then
 fi
 pip install numpy
 
+if [[ "${OIIO_PYTHON_BINDINGS_BACKEND:-}" == "both" || "${OIIO_PYTHON_BINDINGS_BACKEND:-}" == "nanobind" ]] ; then
+    _oiio_nanobind_requirements_file="$PWD/src/build-scripts/ci-requirements-nanobind.txt"
+    "${Python_EXECUTABLE:-python}" -m pip install -r "$_oiio_nanobind_requirements_file" --require-hashes
+fi
+
 
 # In case we need vcpkg, example:
 # echo "All pre-installed VCPkg installs:"

src/build-scripts/install_homebrew_deps.bash

@@ -57,6 +57,9 @@ if [[ "$OIIO_BREW_INSTALL_PACKAGES" == "" ]] ; then
     if [[ "${USE_QT:=1}" != "0" ]] && [[ "${INSTALL_QT:=1}" != "0" ]] ; then
         OIIO_BREW_INSTALL_PACKAGES+=" qt${QT_VERSION}"
     fi
+    if [[ "${OIIO_PYTHON_BINDINGS_BACKEND:-}" == "both" || "${OIIO_PYTHON_BINDINGS_BACKEND:-}" == "nanobind" ]] ; then
+        OIIO_BREW_INSTALL_PACKAGES+=" nanobind"
+    fi
 fi
 brew install --display-times -q $OIIO_BREW_INSTALL_PACKAGES $OIIO_BREW_EXTRA_INSTALL_PACKAGES || true
 

src/cmake/testing.cmake

@@ -253,14 +253,12 @@ macro (oiio_add_all_tests)
                 "${CMAKE_INSTALL_PREFIX}/${PYTHON_SITE_ROOT_DIR}")
             oiio_tests_pythonpath_env_entry (_pybind_tests_pythonpath
                 "${_installed_python_site_packages}")
-            oiio_tests_pythonpath_env_entry (_nanobind_tests_pythonpath
-                "${CMAKE_BINARY_DIR}/lib/python/nanobind/$<CONFIG>")
         else ()
             oiio_tests_pythonpath_env_entry (_pybind_tests_pythonpath
                 "${CMAKE_BINARY_DIR}/lib/python/site-packages")
-            oiio_tests_pythonpath_env_entry (_nanobind_tests_pythonpath
-                "${CMAKE_BINARY_DIR}/lib/python/nanobind")
         endif ()
+        oiio_tests_pythonpath_env_entry (_nanobind_tests_pythonpath
+            "${CMAKE_BINARY_DIR}/lib/python/nanobind")
         set (nanobind_python_tests
              python-imagespec
              python-paramlist

src/python-nanobind/__init__.py

@@ -14,6 +14,14 @@
         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)