ci: Upload fixed python stubs as an artifact in CI (#4754)

If the python stubs test fails (because the API changed in some way that needs
the stubs regenerated, but the submitter of the PR did not or could not,
the wheel CI will regenerate the stubs and include them in the failure artifact.

This provides a path for users who can't build the stubs locally.

Signed-off-by: Chad Dombrova <chadrik@gmail.com>

Author: chadrik

.github/workflows/wheel.yml

@@ -163,7 +163,11 @@ jobs:
       - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           name: cibw-wheels-${{ matrix.python }}-${{ matrix.manylinux }}
-          path: ./wheelhouse/*.whl
+          path: |
+            ./wheelhouse/*.whl
+            ./wheelhouse/OpenImageIO/__init__.pyi
+        # if stub validation fails we want to upload the stubs for users to review
+        if: success() || failure()
 
   # ---------------------------------------------------------------------------
   # Linux ARM Wheels
@@ -225,7 +229,11 @@ jobs:
         - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
           with:
             name: cibw-wheels-${{ matrix.python }}-${{ matrix.manylinux }}
-            path: ./wheelhouse/*.whl
+            path: |
+              ./wheelhouse/*.whl
+              ./wheelhouse/OpenImageIO/__init__.pyi
+          # if stub validation fails we want to upload the stubs for users to review
+          if: success() || failure()
 
   # ---------------------------------------------------------------------------
   # macOS Wheels

INSTALL.md

@@ -398,7 +398,7 @@ for more information on customizing and overriding build-tool options and CMake
 This repo contains python type stubs which are generated from `pybind11` signatures.
 The workflow for releasing new stubs is as follows:
 
-- Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
+- Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and `docker`
 - Run `make pystubs` locally to generate updated stubs in `src/python/stubs/__init__.pyi`
 - Run `make test-pystubs` locally to use mypy to test the stubs against the code in 
   the python testsuite.
@@ -411,6 +411,10 @@ The workflow for releasing new stubs is as follows:
   the stubs, so that changes can be reviewed and the rules in `generate_stubs.py` 
   can be updated, if necessary.
 
+Note that if you can't (or don't want to) build the stubs locally, you can 
+download an artifact containing the wheel and `__init__.pyi` file from any job 
+that fails the stub validation.
+
 Test Images
 -----------
 

src/python/stubs/generate_stubs.py

@@ -208,6 +208,7 @@ def main() -> None:
             print("Changes to the source code have resulted in a change to the stubs.")
             print(get_colored_diff(old_text, new_text))
             print("Run `make pystubs` locally and commit the results for review.")
+            print("The resulting __init__.pyi file will be uploaded as an artifact on this job.")
             sys.exit(2)