Add python stubs to built wheels

Adds support for IDE type completion and static type analysis

Author: chadrik

.github/workflows/wheel_workflow.yml

@@ -144,14 +144,21 @@ jobs:
       - name: Build wheels
         uses: pypa/[email protected]
         env:
+          # pass GITHUB_ACTIONS through to the build container so that custom
+          # processes can tell they are running in CI.
+          CIBW_ENVIRONMENT_PASS_LINUX: GITHUB_ACTIONS
           CIBW_BUILD: ${{ matrix.python }}
           CIBW_ARCHS: ${{ matrix.arch }}
           CIBW_MANYLINUX_X86_64_IMAGE: ${{ matrix.manylinux }}
 
       - uses: actions/upload-artifact@v4
         with:
           name: cibw-wheels-${{ matrix.python }}-${{ matrix.manylinux }}
-          path: ./wheelhouse/*.whl
+          path: |
+            ./wheelhouse/*.whl
+            ./wheelhouse/PyOpenColorIO/__init__.pyi
+          # if stub validation fails we want to upload the stubs for users to review
+          if: success() || failure()
 
   # ---------------------------------------------------------------------------
   # Linux ARM Wheels
@@ -213,7 +220,11 @@ jobs:
       - uses: actions/upload-artifact@v4
         with:
           name: cibw-wheels-${{ matrix.python }}-${{ matrix.manylinux }}
-          path: ./wheelhouse/*.whl
+          path: |
+            ./wheelhouse/*.whl
+            ./wheelhouse/PyOpenColorIO/__init__.pyi
+          # if stub validation fails we want to upload the stubs for users to review
+          if: success() || failure()
 
   # ---------------------------------------------------------------------------
   # macOS Wheels

pyproject.toml

@@ -40,3 +40,35 @@ before-build = "share/ci/scripts/macos/install_docs_env.sh"
 # Disable for now as wheels are built with static dependencies.
 environment = { PATH="$GITHUB_WORKSPACE/doxygen;$PATH", OCIO_PYTHON_LOAD_DLLS_FROM_PATH="0" }
 before-build = 'bash -c "share/ci/scripts/windows/install_docs_env.sh $GITHUB_WORKSPACE/doxygen"'
+
+[[tool.cibuildwheel.overrides]]
+# Trigger the build & validation of the python stubs for certain platforms.
+# The test command acts as a kind of "post-build" callback where it's possible
+# for the stub-generator to import the freshly-built wheel.
+# There are two entry-points which are designed to call generate_stubs.py through
+# this test command:
+# - `make pystubs` is called during local development to generate the
+#   stubs and copy them into the git repo to be committed and reviewed.
+# - in CI, the cibuildwheel action is used to validate that the stubs match what
+#   has been committed to the repo.
+test-requires = "mypy~=1.15.0 stubgenlib~=0.2.0"
+# Note: the python version here must be kept in sync with src/python/stubs/CMakeLists.txt
+select = "cp311-manylinux_*64"
+inherit.test-command = "append"
+test-command = [
+    "python {project}/src/bindings/python/stubs/generate_stubs.py --out-path '/output' --validate-path '{project}/src/bindings/python/stubs/PyOpenColorIO/__init__.pyi'",
+]
+
+[tool.mypy]
+files = [
+    "tests/python/",
+    "src/bindings/python/stubs",
+]
+#mypy_path = [
+#    "src/bindings/python/stubs",
+#]
+allow_redefinition = true
+check_untyped_defs = true
+disable_error_code = [
+    "func-returns-value",
+]

src/bindings/python/CMakeLists.txt

@@ -258,4 +258,30 @@ install(TARGETS PyOpenColorIO
     LIBRARY DESTINATION ${_PyOpenColorIO_SITE_PACKAGE_DIR}
 )
 
-install(FILES package/__init__.py DESTINATION ${_PyOpenColorIO_SITE_PACKAGE_DIR})
+install(FILES stubs/PyOpenColorIO/__init__.pyi DESTINATION ${_PyOpenColorIO_SITE_PACKAGE_DIR})
+install(FILES stubs/PyOpenColorIO/py.typed DESTINATION ${_PyOpenColorIO_SITE_PACKAGE_DIR})
+
+###############################################################################
+
+# Note: the python version must be kept in sync with `[[tool.cibuildwheel.overrides]]` in pyproject.toml.
+# The stubs are generated within a container so the version of python does not need to match
+# the version of python that OpenColorIO is being built against.
+# Note: the version of cibuildwheel should be kept in sync with .github/workflows/wheel.yml
+add_custom_command (COMMAND ${Python_EXECUTABLE} ${CMAKE_SOURCE_DIR}/src/bindings/python/stubs/generate_stubs_local.py
+                        --repo-root ${CMAKE_SOURCE_DIR} --python-version="3.11" --cibuildwheel-version="2.22.0"
+                        --output-dir "${CMAKE_BINARY_DIR}/wheelhouse"
+                    OUTPUT "${CMAKE_BINARY_DIR}/wheelhouse/PyOpenColorIO/__init__.pyi"
+                    DEPENDS "${CMAKE_SOURCE_DIR}/src/bindings/python/stubs/generate_stubs.py"
+                    DEPENDS "${CMAKE_SOURCE_DIR}/src/bindings/python/stubs/generate_stubs_local.py"
+                    COMMENT "pystubs: Generating python stubs"
+                    )
+
+add_custom_command (COMMAND ${CMAKE_COMMAND} -E copy
+                        "${CMAKE_BINARY_DIR}/wheelhouse/PyOpenColorIO/__init__.pyi"
+                        "${CMAKE_SOURCE_DIR}/src/bindings/python/stubs/PyOpenColorIO/__init__.pyi"
+                    OUTPUT "${CMAKE_SOURCE_DIR}/src/bindings/python/stubs/PyOpenColorIO/__init__.pyi"
+                    DEPENDS "${CMAKE_BINARY_DIR}/wheelhouse/PyOpenColorIO/__init__.pyi"
+                    COMMENT "pystubs: Copying generated stubs to source"
+                    )
+
+add_custom_target (pystubs DEPENDS "${CMAKE_SOURCE_DIR}/src/bindings/python/stubs/PyOpenColorIO/__init__.pyi")