Release 1.24.0

.agents/rules/code-comments.md

@@ -17,4 +17,11 @@ Do not reference specs, tasks, plans, tickets, issue numbers, user stories, or t
 
 ## Type-ignore comments
 
-Use the standard `# type: ignore[<code>]` form (for example `# type: ignore[arg-type]`), never `# ty: ignore`. Only `# type: ignore[...]` is honored by mypy, pyright, and pytype, so a `# ty:` comment suppresses nothing and is dead.
+Use the standard `# type: ignore[<code>]` form (for example `# type: ignore[arg-type]`), never `# ty: ignore`.
+Inline comments carry mypy codes only.
+
+`ty` does not read a bare mypy code as a suppression; it wants either `# ty: ignore[<code>]` or a
+`ty:`-prefixed code inside the standard brackets (`# type: ignore[arg-type, ty:invalid-argument-type]`).
+Do not use either form. Remaining `ty` violations belong in `[[tool.ty.overrides]]` in `pyproject.toml`,
+scoped to the narrowest file or glob that covers them and annotated with the violation count so they can be
+retired incrementally.

.github/workflows/ci.yml

@@ -310,6 +310,215 @@ jobs:
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
+  # ------------------------------------------ Dependency Bounds  ------------------------------------------
+  # `unit-tests` installs what uv.lock pins, so it never exercises the ranges in pyproject.toml.
+  # Upper bounds are tracked separately: an upstream release could turn such a job red on its own.
+
+  # Deterministic enough to gate on, since floors only move when pyproject.toml does. Development
+  # dependencies mask some floors; `dependency-lower-bounds-no-harness` below reaches those.
+  dependency-lower-bounds:
+    env:
+      # workaround for Rich table column width
+      COLUMNS: 140
+    if: |
+      always() && !cancelled() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled') &&
+      needs.files-changed.outputs.python == 'true'
+    needs: ["prepare-environment", "files-changed", "yaml-lint", "python-lint"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v7"
+      # Oldest supported interpreter: pyarrow 14, pyyaml 6.0 and ujson 5.0 have no wheels past
+      # cp312, so a newer one would build them from source. Bump when requires-python changes.
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.10"
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "${{ needs.prepare-environment.outputs.UV_VERSION }}"
+          python-version: "3.10"
+      # Rewrites uv.lock in the checkout, which is discarded with the runner.
+      - name: "Re-resolve at the declared lower bounds"
+        run: uv lock --resolution lowest-direct
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups --all-extras
+      - name: "Report the resolved versions"
+        run: uv pip list
+      - name: Unit Tests
+        run: uv run --frozen pytest --cov infrahub_sdk tests/unit/
+
+  # Proves a plain install works on every supported interpreter, which the uv.lock-based jobs cannot.
+  install-matrix:
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    if: |
+      always() && !cancelled() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled') &&
+      needs.files-changed.outputs.python == 'true'
+    needs: ["prepare-environment", "files-changed", "yaml-lint", "python-lint"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v7"
+        with:
+          # hatch-vcs derives the version from git tags, and a shallow clone has none.
+          fetch-depth: 0
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "${{ needs.prepare-environment.outputs.UV_VERSION }}"
+          python-version: ${{ matrix.python-version }}
+      - name: "Build the wheel"
+        run: uv build --wheel --out-dir dist/
+      # Not `uv sync`: a fresh resolution of the built wheel is what a user actually gets.
+      - name: "Install the wheel with every extra"
+        run: |
+          uv venv --python ${{ matrix.python-version }} .venv-install
+          uv pip install --python .venv-install "$(echo dist/*.whl)[all]"
+      - name: "Report the resolved versions"
+        run: uv pip list --python .venv-install
+      # Run from elsewhere: `python -` puts the working directory on sys.path, so from the checkout
+      # this would import the source tree rather than the wheel.
+      - name: "Import every shipped module"
+        working-directory: ${{ runner.temp }}
+        run: |
+          ${{ github.workspace }}/.venv-install/bin/python - <<'PY'
+          import importlib, pkgutil, sys
+          import infrahub_sdk
+
+          failures = []
+          for module in pkgutil.walk_packages(infrahub_sdk.__path__, "infrahub_sdk."):
+              try:
+                  importlib.import_module(module.name)
+              except BaseException as exc:  # noqa: BLE001
+                  failures.append(f"{module.name}: {type(exc).__name__}: {exc}")
+          for failure in failures:
+              print(f"FAIL {failure}")
+          print(f"{len(failures)} module(s) failed to import")
+          sys.exit(1 if failures else 0)
+          PY
+      - name: "Run the CLI"
+        run: |
+          .venv-install/bin/infrahubctl --help
+          .venv-install/bin/infrahubctl schema --help
+          .venv-install/bin/infrahubctl branch --help
+
+  # With no dependency groups, nothing pulls pytest, pydantic, anyio or typing-extensions above
+  # their declared floors, so this is the only job that validates those four. httpx and
+  # graphql-core stay out of reach: ariadne-codegen requires httpx>=0.28 and graphql-core>=3.2.
+  # It cannot run the unit suite without the harness, so it checks the surface a user touches.
+  dependency-lower-bounds-no-harness:
+    if: |
+      always() && !cancelled() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled') &&
+      needs.files-changed.outputs.python == 'true'
+    needs: ["prepare-environment", "files-changed", "yaml-lint", "python-lint"]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v7"
+        with:
+          # hatch-vcs derives the version from git tags, and a shallow clone has none.
+          fetch-depth: 0
+      # The oldest supported interpreter, for the same wheel-availability reason as the job above.
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.10"
+      - name: Install UV
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "${{ needs.prepare-environment.outputs.UV_VERSION }}"
+          python-version: "3.10"
+      - name: "Build the wheel"
+        run: uv build --wheel --out-dir dist/
+      # From pyproject.toml, not the wheel: `--resolution lowest-direct` only lowers what is named
+      # on the command line, so asking for the wheel leaves its dependencies at their newest.
+      - name: "Resolve the extras at their declared lower bounds"
+        run: |
+          uv pip compile pyproject.toml --extra ctl --extra testing \
+            --resolution lowest-direct --python-version 3.10 -o floors.txt
+      - name: "Install the wheel against those floors, with no dependency groups"
+        run: |
+          uv venv --python 3.10 .venv-floors
+          uv pip install --python .venv-floors -r floors.txt
+          uv pip install --python .venv-floors --no-deps "$(echo dist/*.whl)"
+      - name: "Report the resolved versions"
+        run: uv pip list --python .venv-floors
+      # From outside the checkout, so this tests the wheel in site-packages and not the source tree.
+      - name: "Import every shipped module"
+        working-directory: ${{ runner.temp }}
+        run: |
+          ${{ github.workspace }}/.venv-floors/bin/python - <<'PY'
+          import importlib, pkgutil, sys
+          import infrahub_sdk
+
+          # `testing.docker` needs the testcontainers extra, which is deliberately absent here.
+          skip = {"infrahub_sdk.testing.docker"}
+          failures = []
+          for module in pkgutil.walk_packages(infrahub_sdk.__path__, "infrahub_sdk."):
+              if module.name in skip:
+                  continue
+              try:
+                  importlib.import_module(module.name)
+              except BaseException as exc:  # noqa: BLE001
+                  failures.append(f"{module.name}: {type(exc).__name__}: {exc}")
+          for failure in failures:
+              print(f"FAIL {failure}")
+          print(f"{len(failures)} module(s) failed to import")
+          sys.exit(1 if failures else 0)
+          PY
+      - name: "Run the CLI"
+        run: |
+          .venv-floors/bin/infrahubctl --help
+          .venv-floors/bin/infrahubctl schema --help
+          .venv-floors/bin/infrahubctl branch --help
+      # Collection is where the plugin does its work; importing it would prove far less.
+      - name: "Collect a test through the bundled pytest plugin"
+        working-directory: ${{ runner.temp }}
+        run: |
+          rm -rf plugin-check && mkdir -p plugin-check/templates && cd plugin-check
+          cat > infrahub_config.yml <<'YAML'
+          ---
+          jinja2_transforms:
+            - name: bgp_config
+              description: "Template for BGP config base"
+              query: "bgp_sessions"
+              template_path: "templates/bgp_config.j2"
+          YAML
+          cat > test_bgp.yml <<'YAML'
+          ---
+          infrahub_tests:
+            - resource: "Jinja2Transform"
+              resource_name: "bgp_config"
+              tests:
+                - name: smoke
+                  spec:
+                    kind: "jinja2-transform-smoke"
+          YAML
+          printf 'router bgp {{ asn }}\n' > templates/bgp_config.j2
+          # The default shell is `bash -e` without pipefail, so a pytest failure would otherwise
+          # be reported as a grep failure.
+          set -o pipefail
+          ${{ github.workspace }}/.venv-floors/bin/python -m pytest \
+            --infrahub-repo-config=infrahub_config.yml --strict-markers --collect-only -q \
+            | tee collected.txt
+          grep -q "infrahub_jinja2_transform__bgp_config__smoke" collected.txt
+
   # ------------------------------------------ Integration Tests  ------------------------------------------
   integration-tests-latest-infrahub:
     if: |
@@ -450,6 +659,9 @@ jobs:
       - validate-documentation-style
       - unit-tests
       - integration-tests-latest-infrahub
+      - dependency-lower-bounds
+      - dependency-lower-bounds-no-harness
+      - install-matrix
     runs-on: "ubuntu-latest"
     timeout-minutes: 5
     steps:

AGENTS.md

@@ -53,6 +53,22 @@ infrahub_sdk/
 └── pytest_plugin/      # Custom pytest plugin
 ```
 
+## Branches
+
+| Branch | Holds |
+|--------|-------|
+| `stable` | The released SDK and its fixes |
+| `develop` | SDK features that work with the current Infrahub version |
+| `infrahub-release-x.y` | The SDK that ships with Infrahub `x.y`; created from `infrahub-develop` when Infrahub cuts `release-x.y` |
+| `infrahub-develop` | SDK changes that need the next Infrahub version |
+
+The Infrahub repository pins `python_sdk` to the branch that matches its own: `stable` to `stable`,
+`release-x.y` to `infrahub-release-x.y`, `develop` to `infrahub-develop`.
+
+A bot opens a pull request to sync each branch into the next one, in this order:
+`stable` → `develop` → `infrahub-release-x.y` → `infrahub-develop`. The rules are in
+[opsmill/infrahub-github-bot `config.yaml`](https://github.com/opsmill/infrahub-github-bot/blob/main/config.yaml).
+
 ## Markdown style
 
 When editing `.md` or `.mdx` files (`uv run invoke lint-docs` enforces these):