feat(python): Expand dual-backend support in Python bindings

Enhanced the Python bindings to support both pybind11 and nanobind backends by adding new source files to the CMake configuration. Updated the MIGRATION_STATUS.md to reflect the current state of dual-backend integration, detailing the modules that have been migrated and their functionalities. Refactored binding declarations to ensure consistency across both backends, improving the overall structure and maintainability of the code.

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

Author: soswow

src/python-nanobind/CMakeLists.txt

@@ -4,10 +4,18 @@
 
 set (nanobind_srcs
      ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_oiio.cpp
-     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_paramvalue.cpp
      ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_roi.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_typedesc.cpp
      ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_imagespec.cpp
-     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_typedesc.cpp)
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_paramvalue.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_deepdata.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_colorconfig.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_imageinput.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_imageoutput.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_imagebuf.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_imagecache.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_texturesys.cpp
+     ${CMAKE_CURRENT_SOURCE_DIR}/../python/py_imagebufalgo.cpp)
 
 set (nanobind_build_package_dir ${CMAKE_BINARY_DIR}/lib/python/nanobind/OpenImageIO)
 file (MAKE_DIRECTORY ${nanobind_build_package_dir})

src/python/CMakeLists.txt

@@ -8,7 +8,15 @@ set (python_dual_backend_srcs
      py_roi.cpp
      py_typedesc.cpp
      py_imagespec.cpp
-     py_paramvalue.cpp)
+     py_paramvalue.cpp
+     py_deepdata.cpp
+     py_colorconfig.cpp
+     py_imageinput.cpp
+     py_imageoutput.cpp
+     py_imagebuf.cpp
+     py_imagecache.cpp
+     py_texturesys.cpp
+     py_imagebufalgo.cpp)
 
 # Full pybind11 module (pybind11 or both backends).
 if (OIIO_BUILD_PYTHON_PYBIND11)

src/python/MIGRATION_STATUS.md

@@ -5,47 +5,51 @@ Nanobind shares binding sources with pybind11 under `src/python/` (see
 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
+Nanobind-only code paths live in binding `.cpp` files and `py_oiio.cpp` behind
 `OIIO_PY_BACKEND_NANOBIND`. Shared Python↔C++ conversion helpers live in
 `py_oiio.h` for both backends.
 
-## Migrated — full parity with pybind (no known gaps for this surface)
+## Migrated — full dual-backend sources
+
+All modules below compile for both pybind11 and nanobind from `src/python/`:
 
 | Source file | Python / C++ API |
 | --- | --- |
-| `py_roi.cpp` | <code>ROI</code><br>Free functions:<br><ul><li><code>union</code></li><li><code>intersection</code></li><li><code>get_roi</code></li><li><code>get_roi_full</code></li><li><code>set_roi</code></li><li><code>set_roi_full</code></li></ul> |
-| `py_typedesc.cpp` | <code>TypeDesc</code><br>Enums: <code>BASETYPE</code>, <code>AGGREGATE</code>, <code>VECSEMANTICS</code><br>Module <code>Type*</code> constants |
-| `py_imagespec.cpp` | <code>ImageSpec</code> (bound methods/properties, typed <code>attribute</code> / buffer paths via shared helpers). |
-| `py_paramvalue.cpp` | <code>ParamValue</code>, <code>ParamValueList</code><br>Enum: <code>Interp</code> |
-
-## Migrated — partial (gaps or intentional deltas vs pybind)
-
-| Source file | Migrated (vs pybind) | Missing or divergent (vs pybind) |
-| --- | --- | --- |
-| `py_oiio.cpp` (`OpenImageIO` module) | <ul><li><code>attribute</code> (one-arg and typed)</li><li><code>get_int_attribute</code></li><li><code>get_float_attribute</code></li><li><code>get_string_attribute</code></li><li><code>getattribute</code></li><li><code>__version__</code>, <code>VERSION_STRING</code></li></ul> | <ul><li><code>geterror</code></li><li><code>get_bytes_attribute</code></li><li>Module <code>set_colorspace</code> (helper taking <code>ImageSpec</code> — the instance method is on <code>ImageSpec</code> in nanobind)</li><li><code>set_colorspace_rec709_gamma</code></li><li><code>equivalent_colorspace</code></li><li><code>is_imageio_format_name</code></li><li><code>AutoStride</code></li><li><code>openimageio_version</code>, <code>VERSION</code>, <code>VERSION_MAJOR</code>, <code>VERSION_MINOR</code>, <code>VERSION_PATCH</code>, <code>INTRO_STRING</code></li><li>Optional: stack traces when <code>OPENIMAGEIO_DEBUG_PYTHON</code> is set (<code>Sysutil</code>)</li><li><code>make_pyobject</code>: no pybind-style <code>debugfmt</code> when the type is unhandled (returns default quietly)</li></ul> |
-| `__init__.py` (package) | Shared with pybind11: env / DLL path setup, <code>from .OpenImageIO import *</code>. | <strong>TODO:</strong> Python CLI entry-point trampolines when the install layout matches the full wheel. |
-
----
-
-## Not migrated — entire pybind modules
+| `py_roi.cpp` | `ROI`, free functions (`union`, `intersection`, `get_roi`, …) |
+| `py_typedesc.cpp` | `TypeDesc`, enums, module `Type*` constants |
+| `py_imagespec.cpp` | `ImageSpec` |
+| `py_paramvalue.cpp` | `ParamValue`, `ParamValueList`, `Interp` |
+| `py_deepdata.cpp` | `DeepData` |
+| `py_colorconfig.cpp` | `ColorConfig`, module color constants |
+| `py_imageinput.cpp` | `ImageInput` |
+| `py_imageoutput.cpp` | `ImageOutput` |
+| `py_imagebuf.cpp` | `ImageBuf` |
+| `py_imagecache.cpp` | `ImageCache` (wrapped) |
+| `py_texturesys.cpp` | `Wrap`, `MipMode`, `InterpMode`, `TextureOpt`, `TextureSystem` |
+| `py_imagebufalgo.cpp` | `ImageBufAlgo`, `PixelStats`, `CompareResults`, `IBA_*` |
+| `py_oiio.cpp` | Module-level attributes and global helpers |
+
+## Known nanobind deltas (vs pybind11)
+
+| Area | Notes |
+| --- | --- |
+| `half` numpy arrays | Multi-dimensional reads return **float32** numpy (nanobind has no native `half` ndarray). pybind11 returns float16. |
+| `ImageBuf` constructors | Lambda/`buffer` inits use nanobind `__init__` placement-new (same Python API). |
+| `ParamValue` constructors | Same placement-new pattern as before. |
+| Enum `.export_values()` | `py_typedesc.cpp` and `py_imagebufalgo.cpp` set module attrs explicitly on nanobind. |
+| `py_typedesc.cpp` | `py::implicitly_convertible` — verify if needed on nanobind (may be pybind-only). |
 
-These exist only in the pybind11 module today (not in `python_dual_backend_srcs`).
+## Not migrated / packaging
 
-| Source file | Python / C++ API |
+| Item | Notes |
 | --- | --- |
-| `py_imageinput.cpp` | <ul><li><code>ImageInput</code></li><li>open, read, formats, …</li></ul> |
-| `py_imageoutput.cpp` | <code>ImageOutput</code> |
-| `py_imagebuf.cpp` | <code>ImageBuf</code> |
-| `py_imagebufalgo.cpp` | <ul><li><code>ImageBufAlgo</code> (namespace)</li><li><code>PixelStats</code></li><li><code>CompareResults</code></li><li>Exposed <code>IBA_*</code> helpers</li></ul> |
-| `py_texturesys.cpp` | <ul><li><code>Wrap</code></li><li><code>MipMode</code></li><li><code>InterpMode</code></li><li><code>TextureOpt</code></li><li><code>TextureSystem</code></li></ul> |
-| `py_imagecache.cpp` | <code>ImageCache</code> (wrapped) |
-| `py_colorconfig.cpp` | <code>ColorConfig</code> |
-| `py_deepdata.cpp` | <code>DeepData</code> |
-
----
+| `__init__.py` | Shared env setup; CLI entry-point trampolines still TODO for full wheel layout. |
 
 ## Conventions
 
-When adding coverage, prefer mirroring the existing `declare_*` split in `src/python/` unless a file becomes too large.
+- Binding macros: `.OIIO_PY_RW`, `.OIIO_PY_PROP_RO`, `.OIIO_PY_PROP_RW`, `.OIIO_PY_RO`, `.OIIO_PY_RO_STATIC` (see `py_backend.h`).
+- Declare functions use `py_module&`, not `py::module&`.
+- Buffer I/O: `oiio_py_request_buffer()` / `oiio_bufinfo_from_object()` (both backends).
+- `#if defined(OIIO_PY_BACKEND_NANOBIND)` only where backends genuinely differ.
 
-Extend **testsuite** coverage for any migrated code that is not already covered, so **parity with pybind11** is demonstrated rather than only claimed. Follow the existing `testsuite/python-*` scripts and `ref/out.txt` pattern where applicable.
+Extend **testsuite** coverage when adding behavior; run both pybind and `*.nanobind` ctest variants when `OIIO_PYTHON_BINDINGS_BACKEND=both`.

src/python/py_backend.h

@@ -10,6 +10,8 @@
 #    include <nanobind/nanobind.h>
 #    include <nanobind/ndarray.h>
 #    include <nanobind/operators.h>
+#    include <nanobind/stl/array.h>
+#    include <nanobind/stl/optional.h>
 #    include <nanobind/stl/string.h>
 #    include <nanobind/stl/vector.h>
 
@@ -21,6 +23,7 @@ using namespace py::literals;
 #    define OIIO_PY_PROP_RO def_prop_ro
 #    define OIIO_PY_PROP_RW def_prop_rw
 #    define OIIO_PY_RO_STATIC def_prop_ro_static
+#    define OIIO_PY_RO def_ro
 
 namespace oiio_py {
 
@@ -105,6 +108,7 @@ using namespace py::literals;
 #    define OIIO_PY_PROP_RO def_property_readonly
 #    define OIIO_PY_PROP_RW def_property
 #    define OIIO_PY_RO_STATIC def_property_readonly_static
+#    define OIIO_PY_RO def_readonly
 
 namespace oiio_py {
 

src/python/py_colorconfig.cpp

@@ -12,10 +12,8 @@ namespace PyOpenImageIO {
 
 // Declare the OIIO ColorConfig class to Python
 void
-declare_colorconfig(py::module& m)
+declare_colorconfig(py_module& m)
 {
-    using namespace pybind11::literals;
-
     py::class_<ColorConfig>(m, "ColorConfig")
 
         .def(py::init<>())
@@ -192,9 +190,12 @@ declare_colorconfig(py::module& m)
                  return std::nullopt;
              })
         .def("configname", &ColorConfig::configname)
-        .def_static("default_colorconfig", []() -> const ColorConfig& {
-            return ColorConfig::default_colorconfig();
-        });
+        .def_static(
+            "default_colorconfig",
+            []() -> const ColorConfig& {
+                return ColorConfig::default_colorconfig();
+            },
+            oiio_py::ref_internal);
 
     m.attr("supportsOpenColorIO")     = ColorConfig::supportsOpenColorIO();
     m.attr("OpenColorIO_version_hex") = ColorConfig::OpenColorIO_version_hex();

src/python/py_deepdata.cpp

@@ -70,29 +70,24 @@ DeepData_merge_deep_pixels(DeepData& dd, int64_t pixel, const DeepData& src,
 
 // Declare the OIIO DeepData class to Python
 void
-declare_deepdata(py::module& m)
+declare_deepdata(py_module& m)
 {
-    using namespace pybind11::literals;
-
     py::class_<DeepData>(m, "DeepData")
-        .def_property_readonly("pixels",
-                               [](const DeepData& d) { return d.pixels(); })
-        .def_property_readonly("channels",
-                               [](const DeepData& d) { return d.channels(); })
-        .def_property_readonly("A_channel",
-                               [](const DeepData& d) { return d.A_channel(); })
-        .def_property_readonly("AR_channel",
-                               [](const DeepData& d) { return d.AR_channel(); })
-        .def_property_readonly("AG_channel",
-                               [](const DeepData& d) { return d.AG_channel(); })
-        .def_property_readonly("AB_channel",
-                               [](const DeepData& d) { return d.AB_channel(); })
-        .def_property_readonly("Z_channel",
-                               [](const DeepData& d) { return d.Z_channel(); })
-        .def_property_readonly("Zback_channel",
-                               [](const DeepData& d) {
-                                   return d.Zback_channel();
-                               })
+        .OIIO_PY_PROP_RO("pixels", [](const DeepData& d) { return d.pixels(); })
+        .OIIO_PY_PROP_RO("channels",
+                         [](const DeepData& d) { return d.channels(); })
+        .OIIO_PY_PROP_RO("A_channel",
+                         [](const DeepData& d) { return d.A_channel(); })
+        .OIIO_PY_PROP_RO("AR_channel",
+                         [](const DeepData& d) { return d.AR_channel(); })
+        .OIIO_PY_PROP_RO("AG_channel",
+                         [](const DeepData& d) { return d.AG_channel(); })
+        .OIIO_PY_PROP_RO("AB_channel",
+                         [](const DeepData& d) { return d.AB_channel(); })
+        .OIIO_PY_PROP_RO("Z_channel",
+                         [](const DeepData& d) { return d.Z_channel(); })
+        .OIIO_PY_PROP_RO("Zback_channel",
+                         [](const DeepData& d) { return d.Zback_channel(); })
 
         .def(py::init<>())
         .def("init", &DeepData_init, "npixels"_a, "nchannels"_a,