🚸 change to nox -s stubs for driving stub generation (#288)

* 🚸 change to `nox -s stubs` for driving stub generation

Signed-off-by: burgholzer <[email protected]>

* 📝 prepare release notes

Signed-off-by: burgholzer <[email protected]>

* ✏️ update docs to reflect new stub generation check requirement

Signed-off-by: burgholzer <[email protected]>

* 👌 address CodeRabbit comments

Signed-off-by: burgholzer <[email protected]>

---------

Signed-off-by: burgholzer <[email protected]>

Author: burgholzer

.github/workflows/reusable-python-linter.yml

@@ -35,7 +35,7 @@ on:
         default: "21.1.7"
         type: string
       check-stubs:
-        description: "Whether to check if the stub files are up to date. Requires 'bindings/generate-stubs.sh' to exist"
+        description: "Whether to check if the stub files are up to date. Requires a nox session called `stubs` to exist."
         default: false
         type: boolean
 
@@ -71,13 +71,9 @@ jobs:
       - name: Check if stub files are up to date
         if: ${{ inputs.check-stubs }}
         run: |
-          if [[ ! -f ./bindings/generate-stubs.sh ]]; then
-            echo "'./bindings/generate-stubs.sh' not found. Please disable the 'check-stubs' input or create a stub-generation script."
-            exit 1
-          fi
-          ./bindings/generate-stubs.sh || true
+          uvx nox -s stubs
           if [[ $(git status --porcelain python) ]]; then
-            echo "Stub files are not up to date. Please run './bindings/generate-stubs.sh' and commit the changes."
+            echo "Stub files are not up to date. Please run 'nox -s stubs' and commit the changes."
             git --no-pager diff python
             exit 1
           fi

CHANGELOG.md

@@ -9,6 +9,14 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ## [Unreleased]
 
+## [1.17.6] - 2025-12-21
+
+_If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#1176)._
+
+### Changed
+
+- 🚸 change to `nox -s stubs` for driving stub generation ([#288]) ([**@burgholzer**])
+
 ## [1.17.5] - 2025-12-19
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#1175)._
@@ -196,7 +204,8 @@ _📚 Refer to the [GitHub Release Notes] for previous changelogs._
 
 <!-- Version links -->
 
-[unreleased]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.17.5...HEAD
+[unreleased]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.17.6...HEAD
+[1.17.6]: https://github.com/munich-quantum-toolkit/workflows/releases/tag/v1.17.6
 [1.17.5]: https://github.com/munich-quantum-toolkit/workflows/releases/tag/v1.17.5
 [1.17.4]: https://github.com/munich-quantum-toolkit/workflows/releases/tag/v1.17.4
 [1.17.3]: https://github.com/munich-quantum-toolkit/workflows/releases/tag/v1.17.3
@@ -218,6 +227,7 @@ _📚 Refer to the [GitHub Release Notes] for previous changelogs._
 
 <!-- PR links -->
 
+[#288]: https://github.com/munich-quantum-toolkit/workflows/pull/288
 [#286]: https://github.com/munich-quantum-toolkit/workflows/pull/286
 [#276]: https://github.com/munich-quantum-toolkit/workflows/pull/276
 [#271]: https://github.com/munich-quantum-toolkit/workflows/pull/271

UPGRADING.md

@@ -4,6 +4,64 @@ This document describes breaking changes and how to upgrade. For a complete list
 
 ## [Unreleased]
 
+## [1.17.6]
+
+### Checking Python stub files
+
+The optional Python linter workflow for checking Python stub files has been redesigned to rely on the presence of a nox session called `stubs`, that shall generate the stub files.
+An example of such a session would be:
+
+```python
+import nox
+import shutil
+from pathlib import Path
+
+@nox.session(reuse_venv=True, venv_backend="uv")
+def stubs(session: nox.Session) -> None:
+    """Generate type stubs for Python bindings using nanobind."""
+    env = {"UV_PROJECT_ENVIRONMENT": session.virtualenv.location}
+    session.run(
+        "uv",
+        "sync",
+        env=env,
+    )
+
+    from nanobind.stubgen import main as nanobind_main  # type: ignore[import-not-found]
+
+    package_root = Path(__file__).parent / "python" / "mqt" / "core"
+    pattern_file = Path(__file__).parent / "bindings" / "core_patterns.txt"
+
+    args = [
+        "--recursive",
+        "--include-private",
+        "--output-dir",
+        str(package_root),
+        "--pattern-file",
+        str(pattern_file),
+        "--module",
+        "mqt.core.ir",
+        "--module",
+        "mqt.core.dd",
+        "--module",
+        "mqt.core.fomac",
+        "--module",
+        "mqt.core.na",
+    ]
+
+    nanobind_main(args)
+
+    pyi_files = list(package_root.glob("**/*.pyi"))
+
+    if shutil.which("prek") is None:
+        session.install("prek")
+
+    success_codes = [0, 1]
+    session.run("prek", "run", "license-tools", "--files", *pyi_files, external=True, success_codes=success_codes)
+    session.run("prek", "run", "ruff-check", "--files", *pyi_files, external=True, success_codes=success_codes)
+    session.run("prek", "run", "ruff-format", "--files", *pyi_files, external=True, success_codes=success_codes)
+    session.run("prek", "run", "ruff-check", "--files", *pyi_files, external=True)
+```
+
 ## [1.17.5]
 
 ### MLIR support
@@ -196,7 +254,8 @@ Consider removing any `-G Ninja` flags from your CMake invocations under Windows
 
 <!-- Version links -->
 
-[unreleased]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.17.5...HEAD
+[unreleased]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.17.6...HEAD
+[1.17.6]: https://github.com/munich-quantum-toolkit/workflows/releases/tag/v1.17.6
 [1.17.5]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.17.3...v1.17.5
 [1.17.3]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.17.0...v1.17.3
 [1.17.0]: https://github.com/munich-quantum-toolkit/workflows/compare/v1.16.0...v1.17.0