From 7cf82e6d43ee369f9fd79ca4bebcf139cc45af21 Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Tue, 17 Nov 2026 15:00:04 +1300 Subject: [PATCH 1/8] ci: backport API compatibility guard to stable/9 Backport #466 (adb8d602959fbc90a42332559162dbab00c8bb33) following the design in camunda/orchestration-cluster-api-csharp#545. Stable regeneration must not silently release public API breaks. Keep the checker and approval semantics, including re-gating after a release retry resets to a new tip. Retain the target version check, Pyright and generation commands. Select Python >=3.11 for tool jobs without changing the Python 3.10 runtime floor. Adapt the typed test fixture and place guard guidance in the existing instructions. Relates to #465. --- .github/copilot-instructions.md | 4 + .github/workflows/api-compat.yml | 76 ++ .github/workflows/publish.yml | 24 +- AGENTS.md | 399 +++++++ CONTRIBUTING.md | 11 + Makefile | 8 +- scripts/api-compat-gate.sh | 52 + scripts/api_compat.py | 1396 ++++++++++++++++++++++++ scripts/semantic-release-with-retry.sh | 115 ++ tests/acceptance/test_api_compat.py | 986 +++++++++++++++++ 10 files changed, 3069 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/api-compat.yml create mode 100644 AGENTS.md create mode 100644 scripts/api-compat-gate.sh create mode 100644 scripts/api_compat.py create mode 100755 scripts/semantic-release-with-retry.sh create mode 100644 tests/acceptance/test_api_compat.py diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 96896eb52..efeed8776 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -136,6 +136,10 @@ A test that only covers the exact instance provides weaker protection: the same - The green step **proves** the fix resolves it. - A class-scoped test acts as a durable regression guard against future reintroduction of the same pattern. +## API compatibility guard + +PRs to `stable/**` must pass the `API compatibility` check (`scripts/api_compat.py`, tests in `tests/acceptance/test_api_compat.py`), and the Publish workflow repeats it before releasing from a stable branch. It compares `generated/` with the newest published `N.x.y` on PyPI. Only an intended break may be approved, with the `api-break-approved` label on the PR (or the `api_break_approved` input of a manual Publish run for upstream drift). Never apply the label to make a check pass; make the change backward compatible instead. See CONTRIBUTING.md for what counts as breaking. + ## README Code Examples ### API spec examples: prefer ergonomic helpers diff --git a/.github/workflows/api-compat.yml b/.github/workflows/api-compat.yml new file mode 100644 index 000000000..e94d69496 --- /dev/null +++ b/.github/workflows/api-compat.yml @@ -0,0 +1,76 @@ +name: API compatibility + +# Blocks PRs to stable branches whose public Python API would break customer code written +# against the last release published from that branch (see scripts/api_compat.py). When a +# break is intended (e.g. a bug fix that must change the API), apply the +# `api-break-approved` label: the check still runs and lists the breaks, but passes. The +# Publish workflow repeats the check on the code it is about to release. + +on: + pull_request: + branches: + - 'stable/**' + # labeled/unlabeled: re-evaluate when api-break-approved is added or removed. edited: + # re-evaluate when the PR is retargeted to another stable branch. The job must run for + # every such event: a skipped run would replace a failed one and the required check + # would count as passing. + types: [opened, synchronize, reopened, labeled, unlabeled, edited] + +permissions: + contents: read + +concurrency: + group: api-compat-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + api-compat: + name: API compatibility + env: + UV_PYTHON: ">=3.11" + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v6 + + - name: Install uv + uses: astral-sh/setup-uv@v7 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version-file: "pyproject.toml" + + # Both the baseline wheel and generated/ are imported to read their API, so the + # SDK's runtime dependencies must be installed. + - name: Install dependencies + run: uv sync --all-extras --dev + + # Regenerate from the checked-in bundled spec, so a generator change is checked even + # when its regenerated output was not committed. Upstream spec drift is left to the + # release gate, which checks what Publish actually generates. + - name: Generate SDK + run: | + uv run generate.py --generator openapi-python-client --config generator-config-python-client.yaml --skip-tests --bundled-spec external-spec/bundled/rest-api.bundle.json + uv run ruff format generated/ + uv run ruff check generated/ --fix + + - name: Check API compatibility + env: + # stable/: compared with the newest published N.x.y. A branch with no N.x + # release yet (just cut from main) has nothing to compare with and passes. + MAJOR: ${{ github.base_ref }} + APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'api-break-approved') }} + run: | + set -uo pipefail + rc=0 + uv run python scripts/api_compat.py --baseline-major "${MAJOR#stable/}" || rc=$? + if [ "$rc" -eq 1 ] && [ "$APPROVED" = "true" ]; then + echo "::warning::Breaking API changes approved with the api-break-approved label." + echo "Approved with the \`api-break-approved\` label." >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + if [ "$rc" -eq 1 ]; then + echo "::error::If this break is intended (e.g. a bug fix that must change the API), apply the api-break-approved label. Otherwise make the change backward compatible." + fi + exit "$rc" diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 326e64d33..3aee85d5e 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -11,6 +11,12 @@ on: description: "Git ref/branch/tag/SHA in camunda/camunda.git to fetch the OpenAPI spec from (temporary override)." required: false default: "" + api_break_approved: + description: >- + Release even though the public API breaks compatibility with the last release on + this stable branch (for breaks with no PR to label, e.g. from upstream spec drift). + type: boolean + default: false concurrency: group: release-${{ github.ref_name }} @@ -213,6 +219,8 @@ jobs: git push release: + env: + UV_PYTHON: ">=3.11" needs: generate runs-on: ubuntu-latest permissions: @@ -299,12 +307,26 @@ jobs: echo "Version $NEW_VERSION matches branch constraint ${BRANCH_MAJOR}.x" + # Compares the public API about to be released (generated/ as committed by the + # generate job) with the newest release of this stable major on PyPI. This covers + # generated code from upstream spec drift that no PR reviewed. Override: the + # api-break-approved label on any PR merged since that release, or the + # api_break_approved input of a manual run. scripts/semantic-release-with-retry.sh + # repeats it if a retry moves to a newer branch tip. + - name: API compatibility gate (stable branches) + if: steps.check_release.outputs.release_needed == 'true' && startsWith(github.ref_name, 'stable/') + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + DISPATCH_APPROVED: ${{ github.event_name == 'workflow_dispatch' && inputs.api_break_approved }} + run: bash scripts/api-compat-gate.sh "$GITHUB_REF_NAME" + - name: Create release if: steps.check_release.outputs.release_needed == 'true' env: GH_TOKEN: ${{ steps.app-token.outputs.token }} + DISPATCH_APPROVED: ${{ github.event_name == 'workflow_dispatch' && inputs.api_break_approved }} run: | - uv run semantic-release version + bash scripts/semantic-release-with-retry.sh uv run semantic-release publish - name: Build package diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..5a88fa8ed --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,399 @@ +# AGENTS.md + +> **Note:** This file delegates to a central AGENTS.md. Read and apply it before proceeding. + +**URL:** +https://raw.githubusercontent.com/camunda/.github/refs/heads/main/AGENTS.md + +Treat the central file's contents as if they were written directly in this file. +Instructions below extend those guidelines and take precedence if there is any conflict. + + +> **Note:** This file also delegates to the shared SDK AGENTS.md. Read and apply it too. + +**URL:** +https://raw.githubusercontent.com/camunda/sdk-infra/refs/heads/main/policies/AGENTS.md + +It holds the conventions shared by all Camunda SDK repos (commits, bug fixes, tests, opening issues). Precedence on conflict: this file, then the shared SDK file, then the central Camunda file. + + +## Repo-specific instructions + +### Role & boundary + +This repo is the Python SDK Generator for the Camunda 8 Orchestration Cluster API. It produces the `camunda_orchestration_sdk` package in `generated/` from an OpenAPI spec, layering custom runtime logic and post-processing hooks on top of `openapi-python-client`. + +- **Project type**: Python SDK generator + client library +- **Source language**: Python 3.10+ for the published SDK; Python 3.11+ to run the generator (see `hooks/post_gen/0030_py310_compat.py`) +- **Build/dependency**: `uv` (primary), `make` (orchestration) +- **Generation**: `openapi-python-client` with custom Python hooks +- **Runtime**: `httpx`, `pydantic`, `asyncio` +- **Testing**: `pytest`, `pytest-asyncio` + +Upstream dependencies — when they misbehave, fix them at the source rather than working around them here: + +- [`camunda-schema-bundler`](https://github.com/camunda/camunda-schema-bundler) — fetches and bundles the upstream OpenAPI spec. +- [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) — generates `generated/camunda_orchestration_sdk/`. +- [`camunda/camunda`](https://github.com/camunda/camunda) — source of the OpenAPI spec. + +**Path map:** + +| Path | Ownership and intent | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `generate.py` | Main entry point for generation. | +| `runtime/` | Hand-written runtime logic (e.g. `JobWorker`) **injected** into the generated SDK. Primary edit surface for runtime behavior. | +| `hooks/pre_gen/` | Hooks that modify the raw OpenAPI spec before generation. | +| `hooks/post_gen/` | Hooks that modify the generated Python files (flatten client, patch imports, etc.). Primary edit surface for fixing generator output. | +| `generated/` | **Generated.** Produced by `make generate`. Never hand-edit. The published `camunda_orchestration_sdk` package lives under `generated/`. | +| `stubs/` | Generated `.pyi` stub files mirroring the `generated/` package, used by downstream tooling (e.g. API changelog generation). Type-checked by ty. | +| `tests/acceptance/` | Fast unit tests that validate the generated code's structure and logic. No live Camunda required. | +| `tests/integration/` | Integration tests against a real Camunda instance. | +| `examples/readme.py` | Source of truth for `README.md` code examples — type-checked by ty. | +| `docker/` | Local Camunda compose stack for integration tests. | +| `scripts/` | Build, bundle, and sync helpers. | + +## Working on an issue + +Every change must be traceable to a tracked, claimed, in-progress work item **before implementation starts**. This keeps work legible so reviewers and other agents can direct effort and detect drift. + +- **Start from a tracked issue or PR.** Do not begin implementation without a GitHub issue (or an already-open PR) describing the work. If none exists, create one first. +- **Claim it.** Assign the issue to yourself (or the human you are working for) and move it into an in-progress state so it is visibly owned. +- **Reference it.** The branch, commits, and PR must reference the issue (e.g. `Closes #123`), so the trail from motivation to change is explicit. +- **One concern per issue/PR.** If work uncovers an unrelated problem, file a separate issue rather than expanding the current one. + +The only exceptions are trivial, self-evident fixes (typos, broken links, formatting) where the change *is* its own justification. When in doubt, open an issue. + +## Documentation (Audiences) + +This repo serves two audiences. When updating documentation, choose the correct file: + +- **End users of the published SDK**: document in `README.md` (installation, configuration, and how to use `CamundaClient` / `CamundaAsyncClient`). Keep generator internals out of the README. +- **Contributors / SDK generator maintainers**: document in `CONTRIBUTING.md` (generation workflow, hooks, runtime injection, testing, release/build details). +- **Deep technical reference**: use `docs/*.md` for focused design notes and longer-form explanations. + +If the user request is ambiguous (e.g. "update the docs"), clarify which audience they mean before editing. + +## Build instructions + +Always use `uv` for package management and running scripts. The `Makefile` provides convenient shortcuts, but understanding the underlying `uv` commands is helpful depending on the task. + +> Contributor workflows (generation, hooks, testing) are documented in `CONTRIBUTING.md`. Prefer keeping this file focused on execution conventions for the coding agent. + +### 1. Bootstrap & install + +Ensure `uv` is installed. Then install dependencies: + +```bash +uv sync +``` + +### 2. Generate SDK (critical step) + +Before running tests, type checks, or using the SDK, you **must** generate it. This script fetches the OpenAPI spec, runs the generator, and executes post-processing hooks (including copying runtime code). + +```bash +make generate +# OR manually: +# uv run generate.py --generator openapi-python-client --config generator-config-python-client.yaml --skip-tests +``` + +**Validation**: Check that `generated/camunda_orchestration_sdk` exists and contains `client.py` and `models/`. + +### 3. Run tests + +The repository has two types of tests: + +- **Acceptance tests**: fast, no live Camunda required. Run after every generation. + + ```bash + make test + # OR: uv run pytest -q tests/acceptance + ``` + +- **Integration tests**: require a local Camunda server. + + 1. Start server: `cd docker && docker compose up -d` + 2. Run tests: + + ```bash + make itest + # OR: CAMUNDA_INTEGRATION=1 uv run pytest -q tests/integration + ``` + +### 4. Linting & formatting + +```bash +make lint +# OR: uv run ruff check . +``` + +To fix auto-fixable issues: + +```bash +uv run ruff check . --fix +``` + +### 5. Type checking + +Type checking runs `ty` on the generated code and test files. + +```bash +make typecheck +# OR: uv run ty check +``` + +*Precondition*: The SDK must be generated first (`make generate`). + +**Always green**: The `main` branch must have **0 errors** from `uv run ty check`. Any change that introduces ty errors must be fixed before merging. Do not dismiss new errors as "pre-existing" without verifying by checking the baseline. If a change produces errors, fix them — do not leave regressions. + +**After pipeline changes**: When modifying hooks, runtime code, or any part of the generation pipeline, always run `make lint` and `make typecheck` and fix any errors before considering the change complete. + +### 6. Clean + +To remove generated artifacts: + +```bash +make clean +``` + +## Project layout + +### Architecture & generation flow + +1. **Spec retrieval**: `generate.py` fetches the OpenAPI spec. +2. **Pre-gen hooks**: scripts in `hooks/pre_gen/` modify the raw OpenAPI spec (e.g. renaming fields). +3. **Core generation**: `openapi-python-client` runs using `generator-config-python-client.yaml`. +4. **Post-gen hooks**: scripts in `hooks/post_gen/` modify the generated Python files (e.g. flattening client structure, patching imports). +5. **Runtime injection**: the content of `runtime/` is copied into `generated/camunda_orchestration_sdk/runtime/`. + +### Important files + +- `pyproject.toml`: project dependencies and build settings. Use `uv` to manage this. +- `Makefile`: standard workflows. +- `generator-config-python-client.yaml`: configuration for the `openapi-python-client` generator. +- `docker/docker-compose.yaml`: local development server. + +### Dependencies + +- **Runtime**: `httpx`, `attrs`, `pydantic`, `python-dateutil`, `loguru`, `python-dotenv`, `typing-extensions`. +- **Development**: `pytest`, `pytest-asyncio`, `pyyaml`, `openapi-python-client`, `jsonref`, `ruff`, `ty`, `python-semantic-release`, `sphinx`, `sphinx-markdown-builder`, `sphinx-book-theme`, `psutil`, `pydantic-settings`, `fastapi`, `uvicorn`. + +## Commit message guidelines + +We use Conventional Commits (enforced by `python-semantic-release`). + +Format: + +``` +(optional scope): + + + +BREAKING CHANGE: +``` + +Allowed type values (common set): + +``` +feat +fix +chore +docs +style +refactor +test +ci +build +perf +``` + +Rules: + +- Subject length: 5–100 characters. +- Use imperative mood ("add support", not "added support"). +- Lowercase subject (except proper nouns). No PascalCase subjects. +- Keep subject concise; body can include details, rationale, links. +- Prefix breaking changes with `BREAKING CHANGE:` either in body or footer. + +### Review-comment fix-ups + +Commits that address PR review comments must use the `chore` type (e.g. `chore:` or `chore():`), **not** the `fix` type. +`fix` commits trigger a patch release and a CHANGELOG entry — review iterations are not user-facing bug fixes. + +``` +# Correct +chore: address review comments — clarify dry-run output + +# Wrong — will pollute the CHANGELOG +fix: address review comments — clarify dry-run output +``` + +### Breaking change commits + +Breaking change markers (`BREAKING CHANGE:` in the body/footer) trigger a major version bump and a CHANGELOG entry. **Never** use these markers for intra-branch corrections on a feature branch — they pollute the release history and cause unnecessary major version increments. + +PR CI includes a breaking change guard that fails when it detects these markers. If the breaking change is intentional, add the `breaking-change-approved` label to the PR. Otherwise, rewrite the commit history to remove the markers before merging. + +### Separate generator changes from regenerated output + +When a change modifies the generator (hooks under `hooks/`, `generate.py`, generator config, `runtime/` files that get copied verbatim, build scripts) **and** that change causes `generated/*` (and/or `stubs/*`) to differ, **split the work into two commits**: + +1. **First commit** — generator change only: hook / `runtime/` / config / script / test edits. No `generated/*` or `stubs/*` changes. +2. **Second commit** — regenerated output: `generated/*` and `stubs/*` produced by running the pipeline against the first commit. + +Why: + +- **Cherry-picks stay clean.** Backports to `stable/*` only need the generator commit; the target branch's release CI regenerates `generated/*` itself. Mixing the two means the cherry-pick drags generated diff through, which conflicts with whatever generated state the target branch has. +- **Reviewers can read the change.** Generator commits are small and meaningful; regenerated commits are large and mechanical. Mixing them makes the review effectively unreadable. +- **`git blame` stays useful** for both surfaces. + +Naming convention for the second commit (mirrors the existing release-pipeline convention `chore(generation): update generated SDK [skip ci]`): + +``` +chore(generation): regenerate SDK for +``` + +If `make generate` modifies `generated/*` or `stubs/*` after the generator commit, `git add` those directories and commit them separately — do **not** amend them back into the generator commit. + +The pre-push checklist below still applies: always run `make generate && make lint && make typecheck && make test` before pushing, and commit any regenerated drift before the push. + +## Pre-push checklist + +Before pushing any commits, **always** run: + +1. `make generate` — regenerates `generated/` from the bundled spec. +2. `make lint` — ruff lint. +3. `make typecheck` — `ty` on generated + tests + stubs. +4. `make test` — acceptance tests. + +If any step modifies tracked files (e.g. `generated/*` drift, README snippet drift, stub drift), commit those changes before pushing — and respect the **separate-commits rule** above when the modified files are under `generated/` or `stubs/`. + +## Bug fix process (red/green refactor) + +Every bug fix **must** follow the red/green refactor discipline: + +1. **Red** — Write a failing test **first**, before changing any production code. The test must fail for the reason you expect (the bug). Commit this separately or demonstrate the failure clearly in the PR. +2. **Green** — Apply the minimal production fix that makes the test pass. +3. **Refactor** (optional) — Clean up while keeping all tests green. + +### Test scope: target the defect class, not just the instance + +The regression test must be broad enough to detect the **class of defect**, not only the specific instance you are fixing. For example, if the bug is "generated model X has a wrong field type", the test should verify that **all** generated models have correct field types — not just model X. + +A test that only covers the exact instance provides weaker protection: the same category of bug can recur in a different model without being caught. + +### Why + +- The failing test **proves** the test can detect this category of defect. +- The green step **proves** the fix resolves it. +- A class-scoped test acts as a durable regression guard against future reintroduction of the same pattern. + +### There are no flaky tests + +We do not acknowledge the existence of "flaky tests". A test that passes sometimes and fails other times is reporting one of two things: + +1. **A test defect** — the test contains a race, an unbounded timeout, an order-of-operation assumption, an unsynchronised readiness signal, or a dependency on wall-clock timing. Fix the test so its outcome is deterministic for the behaviour it claims to assert. +2. **A product defect** — the production code has a race, a missed signal, an unhandled error path, or a resource it leaks under load. Fix the product. + +Either way, an intermittent failure is a real defect that must be diagnosed and fixed before the change merges. Do not retry the CI job, mark the test `@pytest.mark.skip`, or describe the failure as "flaky" or "unrelated" in the PR description. "Re-run and hope" is a coping strategy, not engineering. + +When triaging an intermittent CI failure: + +- Reproduce locally if possible (loops, resource pressure, timeout reduction). If you cannot reproduce, reason from first principles about what *could* differ between local and CI (load, filesystem semantics, signal delivery latency, parallel test interaction). +- Identify the specific race or assumption. Common shapes: polling for an output line that is printed *before* the relevant handler is registered; timeouts that double as correctness assertions; tests that share a temp directory across runs; tests that depend on event ordering across two processes. +- Pick category 1 vs category 2 explicitly in the fix commit message, and explain which signal the test was previously relying on and which deterministic signal it now relies on. +- If timeouts must be generous to absorb runner load, the timeout is a safety net — not a correctness signal. State this in a comment so future maintainers don't tighten it back into a race. + +## Backporting generator fixes to `stable/*` branches + +Generator fixes are **safe and expected to backport** to maintained `stable/N` branches (currently `stable/9` and `stable/10`) by cherry-pick. The typical trigger is a Renovate bump of a generator dependency (e.g. `openapi-python-client`) that breaks generation on `stable/N`: land a generator-only fix on `main`, then cherry-pick it to `stable/N` so the bump can succeed. + +**Generator code** is everything that produces `generated/camunda_orchestration_sdk/` and `stubs/` from the bundled spec: + +- `hooks/pre_gen/` and `hooks/post_gen/` +- `runtime/` — hook `0300_copy_runtime.py` copies it into the generated package on every regen, so a `runtime/` fix propagates through the next generation +- `generate.py`, `bundle.py`, `generator-config-python-client.yaml` +- Spec bundling via `camunda-schema-bundler` (`scripts/bundle-spec.sh`) + +**Not generator fixes** (do not backport without discussion): + +- Direct edits to `generated/` or `stubs/` (regenerated; `stubs/` by hook `1400_generate_stubs.py`). +- Changes that alter the public API surface, the runtime behavior of generated clients, or published SDK semantics. + +### Why it is safe + +`.github/workflows/publish.yml` runs on every push to `stable/**`: it bundles the spec and runs `make generate-local`, regenerating `generated/` and `stubs/` before any release. A generator-only cherry-pick therefore: + +1. Does not change generated output under the branch's currently pinned generator version (verify locally — see below). +2. Lets the next Renovate bump of the generator dependency regenerate successfully. +3. Introduces no behavioral change in whatever N.x patch is published next. + +Regeneration is not publication. The workflow publishes only when semantic-release finds a release-eligible commit since the last tag (e.g. `fix:`); `chore:` commits — including routine Renovate updates and regenerated-output commits — complete without a release. Renovate vulnerability fixes are committed as `fix(deps)` and do cut a patch. If a backport needs to ship on its own, its commit type must be release-eligible. + +This relies on generator changes and regenerated output living in separate commits — see [Separate generator changes from regenerated output](#separate-generator-changes-from-regenerated-output). Cherry-pick only the generator commit. + +### Workflow + +1. Land the fix on `main` via a normal PR first. +2. For each `stable/N` that needs it: + ```bash + git fetch origin stable/N + git checkout -b backport/stable-N/ origin/stable/N + git cherry-pick + ``` +3. If the cherry-pick conflicts, resolve conservatively. If a conflict suggests the fix does not fit that branch's generator pipeline, ask before forcing it. +4. Open a PR against `stable/N` titled ` (backport # to stable/N)`, linking the original PR and stating the verification below. + +### Verification before opening the backport PR + +- The cherry-pick applied cleanly, or conflict resolution is documented. +- The change is generator-class only (no `generated/`, `stubs/`, or behavioral changes). +- Where feasible, run `make generate` on the branch with its pinned generator version and confirm `git diff --stat generated/ stubs/` is empty. + Stable branches track a moving upstream spec branch (e.g. `stable/10` builds from camunda `stable/8.10`), so a diff can come from upstream spec drift. Regenerate once without the cherry-pick to separate that from the backport's effect. +- `make lint` and `make typecheck` pass. +- For PRs to `stable/N`, `make api-compat MAJOR=N` is green (see below). + +### API compatibility guard + +PRs to `stable/**` must pass the `API compatibility` check (`scripts/api_compat.py`, tests in `tests/acceptance/test_api_compat.py`), and the Publish workflow repeats it before releasing from a stable branch. It compares `generated/` with the newest published `N.x.y` on PyPI. Only an intended break may be approved, with the `api-break-approved` label on the PR (or the `api_break_approved` input of a manual Publish run for upstream drift). Never apply the label to make a check pass; make the change backward compatible instead. See CONTRIBUTING.md for what counts as breaking. + +### Anti-patterns + +- **Don't** cherry-pick commits that touch `generated/` or `stubs/` — the target branch regenerates them. +- **Don't** bundle a generator fix with unrelated behavioral changes in one commit. Split them on `main` first so the backport is surgical. +- **Don't** backport without landing on `main` first, unless `main` cannot reproduce the issue (rare; flag it explicitly in the PR). + +## README Code Examples + +### API spec examples: prefer ergonomic helpers + +The `examples/operation-map.json` file maps OpenAPI `operationId`s to example regions that are displayed in the Camunda docs API reference (via `docusaurus-plugin-openapi-docs`). + +When an ergonomic helper method exists for a generated operation, the operation-map entry **must** point to the helper — not to the raw generated method. Users should see the best developer experience by default. + +Example: `create_deployment` maps to `DeployResources` (`deploy_resources_from_files` helper) instead of the raw `create_deployment` (requires manual multipart form construction). This preference is consistent across all three SDK repos (C#, TypeScript, Python). + +Code blocks in `README.md` are **injected from compilable example files** — do not edit them inline. + +- **Source of truth**: `examples/readme.py` (type-checked by ty during build) +- **Sync script**: `scripts/sync-readme-snippets.py` +- **CI gate**: `python3 scripts/sync-readme-snippets.py --check` (fails if README is out of sync) + +### How it works + +1. Wrap code in `examples/readme.py` with `# region RegionName` / `# endregion RegionName` tags. +2. In `README.md`, place `` immediately before the fenced code block. +3. Run `python3 scripts/sync-readme-snippets.py` to update README (or the build does it automatically). +4. Composite regions: `` concatenates regions A and B separated by a blank line. +5. Exempt blocks: use `` above a code block to exclude it from injection enforcement (e.g. pseudo-code). + +The script auto-upgrades legacy `` markers to the new descriptive format. + +### Adding or updating a README example + +1. Add/edit the region-tagged code in `examples/readme.py`. +2. Add/verify the `` marker in `README.md`. +3. Run `python3 scripts/sync-readme-snippets.py` to sync. +4. Run `uv run ty check` to confirm the example type-checks. + +**Never edit a snippet-marked code block directly in README.md** — it will be overwritten on the next sync. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9c8b11bfd..dcb52f5f3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,12 +115,23 @@ make itest - `make itest` – generate SDK and run integration tests (requires running server) - `make lint` – run ruff linter - `make typecheck` – run pyright type checker +- `make api-compat MAJOR=` – compare the public API of `generated/` with the newest published `N.x.y` release - `make docs-api` – generate API documentation to `./public/` - `make preview-docs` – generate and serve docs locally - `make clean` – remove the `generated/` directory - `make clean_spec` – remove the `.openapi-cache/` directory - `make clean-docs` – remove generated documentation +### API compatibility on stable branches + +`stable/N` regenerates from a moving upstream spec, so a release can change the public API without anyone reviewing it. `scripts/api_compat.py` compares the API of `generated/` with the newest non-prerelease `N.x.y` on PyPI and lists every change that would break code written against it: removed modules, classes, functions, attributes or enum members; new required parameters; narrowed parameter types; and result values that became wider (for example a response field turning `str | None` or `str | Unset`). Request models may widen; response models may narrow. Exit codes: `0` compatible, `1` breaking, `2` setup error. + +- The `API compatibility` check runs on every PR to `stable/**`. It regenerates from the checked-in bundled spec first. +- The Publish workflow repeats the check before releasing from `stable/**`. +- If a break is intended (e.g. a bug fix that must change the API), apply the `api-break-approved` label to the PR. The check still lists the breaks but passes, and the release gate accepts any break approved this way on a PR merged since the baseline release. For a break with no PR to label (upstream spec drift), re-run Publish manually with `api_break_approved`. + +Run it locally with `make api-compat MAJOR=10`. + ### README Code Examples Code blocks in `README.md` are **injected from compilable example files** — do not edit them inline. diff --git a/Makefile b/Makefile index 287fa4c9f..4fb732436 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: install generate clean test itest docs-api docs-md docs-link-check bundle-spec typecheck-examples clean-docs preview-docs sync-readme sync-readme-check check +.PHONY: install generate clean test itest docs-api docs-md docs-link-check bundle-spec typecheck-examples clean-docs preview-docs sync-readme sync-readme-check check api-compat # Git ref/branch/tag/SHA in https://github.com/camunda/camunda.git to fetch the OpenAPI spec from. # Override like: `make generate SPEC_REF=45369-fix-spec` @@ -57,6 +57,12 @@ lint: typecheck: uv run pyright +# Compare the public API of generated/ with the newest published MAJOR.x.y release. +# Usage: make api-compat MAJOR=10 (exit 1 lists breaking changes) +api-compat: + @test -n "$(MAJOR)" || { echo "usage: make api-compat MAJOR="; exit 2; } + uv run python scripts/api_compat.py --baseline-major $(MAJOR) + check: lint typecheck typecheck-examples: diff --git a/scripts/api-compat-gate.sh b/scripts/api-compat-gate.sh new file mode 100644 index 000000000..9b0c8506d --- /dev/null +++ b/scripts/api-compat-gate.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +# Release gate for stable/: compare the public API at HEAD (generated/) with the +# newest release of the major on PyPI, and fail unless any break is approved. +# +# Called by the "API compatibility gate" step of .github/workflows/publish.yml, and again +# by scripts/semantic-release-with-retry.sh after it resets to a newer branch tip, so the +# commit that gets released is always the commit that was checked. +# +# Approval: the api-break-approved label on any PR merged since that release, or +# DISPATCH_APPROVED=true (the api_break_approved input of a manual run). +# Needs GH_TOKEN and GITHUB_REPOSITORY. Exit codes: 0 pass, 1 blocked, 2 setup error. +set -uo pipefail + +BRANCH="${1:?usage: api-compat-gate.sh }" +major="${BRANCH#stable/}" +# The newest published release of this stable major, not the nearest tag: a stable +# branch is cut from main at a prerelease. +version=$(uv run python scripts/api_compat.py --print-baseline-major "$major") || exit 2 +if [ -z "$version" ]; then + echo "::notice::No ${major}.x release published yet; nothing to compare against." + exit 0 +fi +tag="v${version}" +git rev-parse -q --verify "refs/tags/${tag}" >/dev/null || { + echo "::error::Baseline ${version} has no ${tag} tag to list the PRs merged since." + exit 2 +} +echo "Baseline: ${tag} (checking $(git rev-parse --short HEAD))" +rc=0 +uv run python scripts/api_compat.py --baseline-version "$version" || rc=$? +[ "$rc" -eq 1 ] || exit "$rc" +if [ "${DISPATCH_APPROVED:-false}" = "true" ]; then + echo "::warning::Breaking API changes approved by the api_break_approved input of this run." + exit 0 +fi +shas=$(git log --format=%H "${tag}..HEAD") || { + echo "::error::cannot list the commits since ${tag}." + exit 2 +} +approved="" +for sha in $shas; do + prs=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${sha}/pulls" \ + --jq '.[] | select(.merged_at != null) | select(any(.labels[]; .name == "api-break-approved")) | "#\(.number)"') || exit 2 + approved="${approved} ${prs}" +done +approved=$(echo "$approved" | xargs -n1 2>/dev/null | sort -u | xargs) +if [ -n "$approved" ]; then + echo "::warning::Breaking API changes approved with the api-break-approved label on: ${approved}" + exit 0 +fi +echo "::error::Release blocked: the public API breaks compatibility with ${tag}. If intended, label the PR that made the change api-break-approved (or re-run this workflow manually with api_break_approved), then re-run." +exit 1 diff --git a/scripts/api_compat.py b/scripts/api_compat.py new file mode 100644 index 000000000..3482547c6 --- /dev/null +++ b/scripts/api_compat.py @@ -0,0 +1,1396 @@ +#!/usr/bin/env python3 +"""Public API compatibility check against the last published release of a major. + +Stable branches regenerate from a moving upstream spec, and the release pipeline commits +that drift without review. This compares the public API of a published release (the +baseline, downloaded from PyPI) with the package in ``generated/`` and lists every change +that would stop customer code written against the baseline from type-checking or running. + +Each package is imported in its own subprocess and described as JSON: modules and their +public names, classes (members, constructor, enum members, bases) and every annotation, +resolved to a canonical type tree. The two descriptions are then compared. + +Direction matters for types. A value the SDK hands to the caller (a return type, an +attribute of a result model) may only narrow: ``str`` becoming ``str | None`` breaks +``x.upper()``. A value the caller hands to the SDK (a parameter, a request model field) +may only widen. Data models (attrs, dataclasses, TypedDicts, pydantic) are classified by +how the baseline API reaches them: reached only through parameters -> request model +(constructor checked, attribute reads not); reached only through return values -> result +model (attribute reads checked, constructor not); both -> both. A model that no API +accepts or returns (an orphan schema) only has to keep existing. + +Exit codes: 0 compatible, 1 breaking changes found, 2 tool or setup error. +""" + +from __future__ import annotations + +import argparse +import ast +import collections.abc +import enum +import hashlib +import importlib +import inspect +import json +import os +import pkgutil +import re +import subprocess +import sys +import tempfile +import textwrap +import traceback +import types +import typing +import urllib.request +import warnings +import zipfile +from collections.abc import Iterator +from pathlib import Path +from typing import Any + +PACKAGE = "camunda_orchestration_sdk" +DISTRIBUTION = "camunda-orchestration-sdk" +PYPI_URL = "https://pypi.org/pypi/{dist}/json" +REPO_ROOT = Path(__file__).resolve().parents[1] + +INPUT = "input" +OUTPUT = "output" + +Json = dict[str, Any] + + +class SetupError(Exception): + """The check could not run (network, download, import). Maps to exit code 2.""" + + +# -------------------------------------------------------------------------------------- +# Baseline resolution (PyPI) +# -------------------------------------------------------------------------------------- + +_RELEASE_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$") + + +def fetch_pypi_metadata(dist: str = DISTRIBUTION) -> Json: + url = PYPI_URL.format(dist=dist) + try: + with urllib.request.urlopen(url, timeout=60) as resp: + return json.load(resp) + except Exception as exc: + raise SetupError(f"cannot read {url}: {exc}") from exc + + +def latest_release(metadata: Json, major: int) -> str | None: + """Newest non-prerelease, non-yanked ``major.x.y`` on the registry, or None.""" + best: tuple[int, int, int] | None = None + for version, files in metadata.get("releases", {}).items(): + m = _RELEASE_RE.match(version) + if not m or int(m.group(1)) != major: + continue + if not files or all(f.get("yanked") for f in files): + continue + key = (int(m.group(1)), int(m.group(2)), int(m.group(3))) + if best is None or key > best: + best = key + return None if best is None else ".".join(map(str, best)) + + +def download_baseline(metadata: Json, version: str, dest: Path) -> Path: + """Download and unpack the release's pure-Python wheel; return the import root.""" + files = metadata.get("releases", {}).get(version) + if not files: + raise SetupError(f"{DISTRIBUTION} {version} is not published on PyPI") + wheels = [f for f in files if f.get("filename", "").endswith("-py3-none-any.whl")] + if not wheels: + raise SetupError(f"{DISTRIBUTION} {version} has no py3-none-any wheel") + wheel = wheels[0] + try: + with urllib.request.urlopen(wheel["url"], timeout=120) as resp: + payload = resp.read() + except Exception as exc: + raise SetupError(f"cannot download {wheel['url']}: {exc}") from exc + expected = wheel.get("digests", {}).get("sha256") + if not expected or hashlib.sha256(payload).hexdigest() != expected: + raise SetupError(f"sha256 mismatch for {wheel['filename']}") + archive = dest / wheel["filename"] + archive.write_bytes(payload) + root = dest / "site" + with zipfile.ZipFile(archive) as zf: + zf.extractall(root) + return root + + +# -------------------------------------------------------------------------------------- +# Describing a package (runs in a subprocess with the package root first on sys.path) +# -------------------------------------------------------------------------------------- + +_ABCS = [ + getattr(collections.abc, name) + for name in collections.abc.__all__ + if isinstance(getattr(collections.abc, name), type) +] + +_NUMERIC_PROMOTION = { + "builtins:int": {"builtins:float", "builtins:complex"}, + "builtins:float": {"builtins:complex"}, +} + +# Variance of each type argument of a generic: "+" covariant, "-" contravariant, "=" +# invariant. A trailing "*" repeats the last entry. Generics not listed are invariant. +_VARIANCE = { + "builtins:tuple": "+*", + "builtins:frozenset": "+", + "builtins:type": "+", + "collections.abc:Iterable": "+", + "collections.abc:Iterator": "+", + "collections.abc:Reversible": "+", + "collections.abc:Collection": "+", + "collections.abc:Container": "+", + "collections.abc:Sequence": "+", + "collections.abc:Set": "+", + "collections.abc:KeysView": "+", + "collections.abc:ValuesView": "+", + "collections.abc:ItemsView": "++", + "collections.abc:Mapping": "=+", + "collections.abc:Awaitable": "+", + "collections.abc:AsyncIterable": "+", + "collections.abc:AsyncIterator": "+", + "collections.abc:Generator": "+-+", + "collections.abc:Coroutine": "+-+", + "collections.abc:AsyncGenerator": "+-", +} + + +def _variance(origin: str, index: int) -> str: + spec = _VARIANCE.get(origin, "=*") + if spec.endswith("*"): + spec = spec[:-1] + return spec[min(index, len(spec) - 1)] + return spec[index] if index < len(spec) else "=" + + +# Special methods that are construction or serialisation hooks, not API callers use. +_HOOK_DUNDERS = frozenset( + { + "__init_subclass__", + "__class_getitem__", + "__post_init__", + "__attrs_pre_init__", + "__attrs_post_init__", + "__attrs_init__", + "__getstate__", + "__setstate__", + "__replace__", + # Generated by the 3.14 compiler for annotated class bodies (PEP 649). + "__annotate__", + "__annotate_func__", + } +) + + +def _is_public_dunder(name: str, raw: Any) -> bool: + """A special method callers reach through syntax (``with``, ``x[k]``, ``len(x)``).""" + return ( + name.startswith("__") + and name.endswith("__") + and name not in _HOOK_DUNDERS + and not hasattr(object, name) # __init__, __eq__, __repr__, ...: always present + and (inspect.isfunction(raw) or isinstance(raw, (staticmethod, classmethod))) + ) + + +def _canon(cls: type) -> str: + return f"{cls.__module__}:{cls.__qualname__}" + + +def _is_private_module(name: str) -> bool: + return any(part.startswith("_") for part in name.split(".")[1:]) + + +def _defined_names(module: types.ModuleType) -> list[str]: + """Names bound at module level by the module's own code (not imports).""" + explicit = getattr(module, "__all__", None) + if explicit is not None: + return [str(n) for n in explicit] + path = getattr(module, "__file__", None) + if not path or not path.endswith(".py"): + return [] + tree = ast.parse(Path(path).read_text(encoding="utf-8")) + names: list[str] = [] + + def visit(body: list[ast.stmt]) -> None: + for node in body: + if isinstance( + node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef) + ): + names.append(node.name) + elif isinstance(node, ast.Assign): + for target in node.targets: + if isinstance(target, ast.Name): + names.append(target.id) + elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name): + names.append(node.target.id) + elif isinstance(node, ast.If): + if not ( + isinstance(node.test, ast.Name) + and node.test.id == "TYPE_CHECKING" + ): + visit(node.body) + visit(node.orelse) + elif isinstance(node, ast.Try): + visit(node.body) + for handler in node.handlers: + visit(handler.body) + visit(node.orelse) + visit(node.finalbody) + + visit(tree.body) + return [n for n in dict.fromkeys(names) if not n.startswith("_")] + + +class Describer: + def __init__(self, package: str) -> None: + self.package = package + self.symbols: dict[str, Json] = {} + self.classes: dict[str, Json] = {} + self.supertypes: dict[str, list[str]] = {} + self._root_ns: dict[str, Any] = {} + self._tc_cache: dict[str, dict[str, Any]] = {} + + # ---- entry point ------------------------------------------------------------- + + def describe(self, expected_root: Path) -> Json: + root = importlib.import_module(self.package) + origin = Path(getattr(root, "__file__", "") or "").resolve() + if expected_root.resolve() not in origin.parents: + raise SetupError( + f"{self.package} was imported from {origin}, not from {expected_root}" + ) + for name in ("models",): + sub = getattr(root, name, None) + if isinstance(sub, types.ModuleType): + self._root_ns.update(vars(sub)) + self._root_ns.update(vars(root)) + + broken: dict[str, str] = {} + + def onerror(name: str) -> None: + broken[name] = repr(sys.exc_info()[1]) + + modules = {self.package} | { + info.name + for info in pkgutil.walk_packages( + root.__path__, self.package + ".", onerror=onerror + ) + } + for modname in sorted(modules | broken.keys()): + if _is_private_module(modname): + continue + # A module that does not import cannot be used; record it rather than abort, + # so a release that shipped one can still serve as a baseline. + try: + module = importlib.import_module(modname) + except Exception as exc: + self.symbols[modname] = {"kind": "module", "broken": repr(exc)} + continue + self.symbols[modname] = {"kind": "module"} + for attr in _defined_names(module): + if attr.startswith("_") or not hasattr(module, attr): + continue + obj = getattr(module, attr) + if isinstance(obj, typing.TypeVar): + continue + self.symbols[f"{modname}:{attr}"] = self._describe_obj(obj, module, attr) + return { + "package": self.package, + "symbols": self.symbols, + "classes": self.classes, + "supertypes": self.supertypes, + } + + # ---- objects ----------------------------------------------------------------- + + def _describe_obj(self, obj: Any, module: types.ModuleType, attr: str) -> Json: + if isinstance(obj, types.ModuleType): + return {"kind": "module"} + if isinstance(obj, type): + self._add_class(obj) + return {"kind": "class", "ref": _canon(obj)} + if inspect.isroutine(obj): + return {"kind": "function", "sig": self._signature(obj, vars(module))} + if typing.get_origin(obj) is not None or isinstance(obj, types.UnionType): + return {"kind": "alias", "type": self._type(obj, vars(module))} + # The declared type, if any: `X: T | None = T()` may become None later. + try: + ann = inspect.get_annotations(module).get(attr, type(obj)) + except Exception: + ann = type(obj) + return {"kind": "value", "type": self._type(ann, self._ns(vars(module)))} + + def _ns(self, *namespaces: dict[str, Any]) -> dict[str, Any]: + merged = dict(self._root_ns) + for ns in namespaces: + merged.update(self._type_checking_imports(ns)) + merged.update(ns) + return merged + + def _type_checking_imports(self, ns: dict[str, Any]) -> dict[str, Any]: + """Names a module imports only under ``if TYPE_CHECKING:`` (for annotations).""" + modname = ns.get("__name__") + if not isinstance(modname, str) or modname not in sys.modules: + return {} + if modname in self._tc_cache: + return self._tc_cache[modname] + found: dict[str, Any] = {} + path = ns.get("__file__") + if isinstance(path, str) and path.endswith(".py"): + tree = ast.parse(Path(path).read_text(encoding="utf-8")) + imports: list[ast.stmt] = [ + stmt + for node in tree.body + if isinstance(node, ast.If) + and isinstance(node.test, (ast.Name, ast.Attribute)) + and ast.unparse(node.test).endswith("TYPE_CHECKING") + for stmt in node.body + if isinstance(stmt, (ast.Import, ast.ImportFrom)) + ] + if imports: + scope: dict[str, Any] = { + "__name__": modname, + "__package__": ns.get("__package__"), + } + code = compile(ast.Module(body=imports, type_ignores=[]), path, "exec") + exec(code, scope) # the module's own imports, already trusted above + found = {k: v for k, v in scope.items() if not k.startswith("__")} + self._tc_cache[modname] = found + return found + + def _record_supertypes(self, cls: type) -> None: + key = _canon(cls) + if key in self.supertypes: + return + names = [_canon(c) for c in cls.__mro__] + for abc in _ABCS: + try: + if issubclass(cls, abc): + names.append(_canon(abc)) + except TypeError: + pass + self.supertypes[key] = list(dict.fromkeys(names)) + + def _typevar_key(self, var: typing.TypeVar) -> str: + return f"{var.__module__}:{var.__name__}" + + def _substitute_typevars(self, value: Any, substitutions: dict[str, Json]) -> Any: + if isinstance(value, list): + return [self._substitute_typevars(item, substitutions) for item in value] + if not isinstance(value, dict): + return value + if value.get("k") == "typevar" and value["n"] in substitutions: + return substitutions[value["n"]] + return { + key: self._substitute_typevars(child, substitutions) + for key, child in value.items() + } + + def _class_specializations( + self, cls: type, ns: dict[str, Any] + ) -> dict[type, dict[str, Json]]: + specializations: dict[type, dict[str, Json]] = {} + + def visit(current: type, substitutions: dict[str, Json]) -> None: + if current in specializations: + return + specializations[current] = substitutions + current_ns = self._ns(vars(sys.modules[current.__module__])) + for base in getattr(current, "__orig_bases__", current.__bases__): + origin = typing.get_origin(base) or base + if not isinstance(origin, type) or not self._is_ours(origin): + continue + args = typing.get_args(base) + base_substitutions: dict[str, Json] = {} + for index, param in enumerate(getattr(origin, "__parameters__", ())): + actual = args[index] if index < len(args) else typing.Any + described = self._type(actual, current_ns) + base_substitutions[self._typevar_key(param)] = self._substitute_typevars( + described, substitutions + ) + visit(origin, base_substitutions) + + initial = { + self._typevar_key(param): self._type(param, ns) + for param in getattr(cls, "__parameters__", ()) + } + visit(cls, initial) + return specializations + + def _is_ours(self, cls: type) -> bool: + mod = getattr(cls, "__module__", "") or "" + return mod == self.package or mod.startswith(self.package + ".") + + def _add_class(self, cls: type) -> None: + self._record_supertypes(cls) + key = _canon(cls) + if key in self.classes or not self._is_ours(cls): + return + info: Json = {"bases": [_canon(c) for c in cls.__mro__[1:] if c is not object]} + self.classes[key] = info + module_ns = vars(sys.modules[cls.__module__]) + ns = self._ns(module_ns) + specializations = self._class_specializations(cls, ns) + + if isinstance(cls, enum.EnumMeta): + info["kind"] = "enum" + info["members"] = { + name: repr(member.value) for name, member in cls.__members__.items() + } + elif typing.is_typeddict(cls): + info["kind"] = "typeddict" + try: + annotations = typing.get_type_hints( + cls, globalns=ns, localns=ns, include_extras=True + ) + except Exception: + annotations = inspect.get_annotations(cls) + required = getattr(cls, "__required_keys__", frozenset()) + info["keys"] = { + key_name: { + "type": self._type( + typing.get_args(ann)[0] + if getattr(typing.get_origin(ann), "__name__", "") + in ("Required", "NotRequired") + else ann, + ns, + ), + "required": ( + getattr(typing.get_origin(ann), "__name__", "") == "Required" + if getattr(typing.get_origin(ann), "__name__", "") + in ("Required", "NotRequired") + else key_name in required + ), + } + for key_name, ann in annotations.items() + } + return + elif _is_protocol(cls): + info["kind"] = "protocol" + elif hasattr(cls, "__attrs_attrs__"): + info["kind"] = "attrs" + elif hasattr(cls, "__dataclass_fields__"): + info["kind"] = "dataclass" + elif hasattr(cls, "model_fields") and hasattr(cls, "model_validate"): + info["kind"] = "pydantic" + else: + info["kind"] = "class" + + if info["kind"] != "enum": + init = inspect.getattr_static(cls, "__init__", None) + get_overloads = getattr(typing, "get_overloads", None) + has_init_overloads = ( + inspect.isfunction(init) and get_overloads is not None and bool(get_overloads(init)) + ) + init_overloads = ( + self._signature(init, ns, skip_first=True) if has_init_overloads else None + ) + if init_overloads and init_overloads.get("overloads"): + info["init"] = self._substitute_typevars( + init_overloads, specializations.get(cls, {}) + ) + else: + try: + ctor = inspect.signature(cls) + except (TypeError, ValueError): + ctor = None + if ctor is not None: + info["init"] = self._substitute_typevars( + self._signature_from(ctor, ns, is_async=False), + specializations.get(cls, {}), + ) + + attributes: dict[str, Json] = {} + members: dict[str, Json] = {} + for klass in reversed(cls.__mro__): + if not self._is_ours(klass): + continue + klass_ns = self._ns(vars(sys.modules[klass.__module__])) + substitutions = specializations.get(klass, {}) + for name, ann in inspect.get_annotations(klass).items(): + if name.startswith("_"): + continue + attributes[name] = self._substitute_typevars( + self._type(ann, klass_ns), substitutions + ) + for name, raw in vars(klass).items(): + if name.startswith("_") and not _is_public_dunder(name, raw): + continue + if info["kind"] == "enum" and name in cls.__members__: + continue + member = self._describe_member(raw, klass_ns) + if member is not None: + members[name] = self._substitute_typevars(member, substitutions) + if info["kind"] == "class": + for name, t in self._init_attributes(klass, klass_ns).items(): + attributes.setdefault(name, self._substitute_typevars(t, substitutions)) + for name, member in list(members.items()): + # A defaulted field's class-level value is the default, not the member's type. + if member["kind"] == "value" and name in attributes: + del members[name] + else: + attributes.pop(name, None) + info["attributes"] = attributes + info["methods"] = members + + def _init_attributes(self, klass: type, ns: dict[str, Any]) -> dict[str, Json]: + """Public ``self.x = ...`` assignments in ``__init__``, read from its source.""" + init = vars(klass).get("__init__") + if not inspect.isfunction(init): + return {} + try: + tree = ast.parse(textwrap.dedent(inspect.getsource(init))) + params = inspect.signature(init).parameters + except (OSError, TypeError, ValueError, SyntaxError): + return {} + fn = tree.body[0] + if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)) or not fn.args.args: + return {} + self_name = fn.args.args[0].arg + found: dict[str, Json] = {} + for node in ast.walk(fn): + if isinstance(node, ast.AnnAssign): + targets, ann, value = [node.target], node.annotation, node.value + elif isinstance(node, ast.Assign): + targets, ann, value = node.targets, None, node.value + else: + continue + for target in targets: + if not ( + isinstance(target, ast.Attribute) + and isinstance(target.value, ast.Name) + and target.value.id == self_name + and not target.attr.startswith("_") + ): + continue + if ann is not None: + t = self._type(ast.unparse(ann), ns) + elif isinstance(value, ast.Name) and value.id in params: + t = self._type(params[value.id].annotation, {**ns, **init.__globals__}) + else: + t = {"k": "any"} + found.setdefault(target.attr, t) + return found + + def _describe_member(self, raw: Any, ns: dict[str, Any]) -> Json | None: + if isinstance(raw, property): + ret = inspect.signature(raw.fget).return_annotation if raw.fget else None + return {"kind": "property", "type": self._type(ret, ns)} + if isinstance(raw, staticmethod): + return { + "kind": "method", + "binding": "static", + "sig": self._signature(raw.__func__, ns), + } + if isinstance(raw, classmethod): + return { + "kind": "method", + "binding": "class", + "sig": self._signature(raw.__func__, ns, skip_first=True), + } + if inspect.isfunction(raw): + return { + "kind": "method", + "binding": "instance", + "sig": self._signature(raw, ns, skip_first=True), + } + if hasattr(raw, "__get__") and hasattr(raw, "func"): # functools.cached_property + ret = inspect.signature(raw.func).return_annotation + return {"kind": "property", "type": self._type(ret, ns)} + if isinstance(raw, (types.MemberDescriptorType, types.GetSetDescriptorType)): + return None + return {"kind": "value", "type": self._type(type(raw), ns)} + + # ---- signatures -------------------------------------------------------------- + + def _signature( + self, + func: Any, + ns: dict[str, Any], + *, + skip_first: bool = False, + with_overloads: bool = True, + ) -> Json: + globs = getattr(func, "__globals__", None) + ns = self._ns(ns, globs) if isinstance(globs, dict) else ns + try: + sig = inspect.signature(func) + except (TypeError, ValueError): + return {"params": [], "returns": {"k": "any"}, "async": False, "opaque": True} + if skip_first: + params = list(sig.parameters.values())[1:] + sig = sig.replace(parameters=params) + is_async = inspect.iscoroutinefunction(func) or inspect.isasyncgenfunction(func) + described = self._signature_from(sig, ns, is_async=is_async) + if not with_overloads: + return described + get_overloads = getattr(typing, "get_overloads", None) + if get_overloads is None: + raise SetupError("recording @overload signatures needs Python 3.11+") + overloads = [ + self._signature(o, ns, skip_first=skip_first, with_overloads=False) + for o in get_overloads(func) + ] + if overloads: + # Type checkers see only the overloads; their async-ness is the implementation's. + for o in overloads: + o["async"] = is_async + described["overloads"] = overloads + return described + + def _signature_from( + self, sig: inspect.Signature, ns: dict[str, Any], *, is_async: bool + ) -> Json: + return { + "params": [ + { + "name": p.name, + "kind": p.kind.name, + "has_default": p.default is not inspect.Parameter.empty, + "type": self._type(p.annotation, ns), + } + for p in sig.parameters.values() + ], + "returns": self._type(sig.return_annotation, ns), + "async": is_async, + } + + # ---- types ------------------------------------------------------------------- + + def _type(self, ann: Any, ns: dict[str, Any]) -> Json: + if ann is inspect.Parameter.empty or ann is inspect.Signature.empty: + return {"k": "any"} + if isinstance(ann, typing.ForwardRef): + ann = ann.__forward_arg__ + for _ in range(3): # quoted names inside a postponed annotation + if not isinstance(ann, str): + break + text = ann + try: + ann = eval(text, ns) # annotations of code already imported above + except Exception: + return {"k": "unresolved", "text": text} + if ann is None or ann is type(None): + return {"k": "none"} + if ann is typing.Any: + return {"k": "any"} + if isinstance(ann, typing.TypeVar): + if ann.__bound__ is not None: + bound = self._type(ann.__bound__, ns) + domain_kind = "bound" + elif ann.__constraints__: + bound = {"k": "union", "items": [self._type(c, ns) for c in ann.__constraints__]} + domain_kind = "constraints" + else: + bound = {"k": "name", "n": "builtins:object"} + domain_kind = "unbounded" + return { + "k": "typevar", + "n": f"{ann.__module__}:{ann.__name__}", + "display": ann.__name__, + "domain_kind": domain_kind, + "domain": bound, + } + if repr(ann) in ("typing.Self", "typing_extensions.Self", "typing.LiteralString"): + return {"k": "any"} + if getattr(ann, "__supertype__", None) is not None: # typing.NewType + return { + "k": "newtype", + "n": f"{ann.__module__}:{ann.__qualname__}", + "super": self._type(ann.__supertype__, ns), + } + origin = typing.get_origin(ann) + args = typing.get_args(ann) + if origin is typing.Union or isinstance(ann, types.UnionType): + items: list[Json] = [] + for arg in args: + t = self._type(arg, ns) + items.extend(t["items"] if t["k"] == "union" else [t]) + return {"k": "union", "items": items} + if origin is typing.Literal: + return { + "k": "literal", + "values": [[_canon(type(v)), repr(v)] for v in args], + } + if origin is typing.Annotated: + return self._type(args[0], ns) + if origin is collections.abc.Callable: + if args and isinstance(args[0], list): + params = [self._type(a, ns) for a in args[0]] + else: + params = None + ret = self._type(args[-1], ns) if args else {"k": "any"} + return {"k": "callable", "params": params, "returns": ret} + if origin is not None and isinstance(origin, type): + self._record_supertypes(origin) + return { + "k": "generic", + "n": _canon(origin), + "args": [ + {"k": "ellipsis"} if a is Ellipsis else self._type(a, ns) + for a in args + ], + } + if isinstance(ann, type): + self._add_class(ann) + return {"k": "name", "n": _canon(ann)} + return {"k": "unresolved", "text": repr(ann)} + + +def _is_protocol(cls: type) -> bool: + return bool(getattr(cls, "_is_protocol", False)) and typing.Protocol in getattr( + cls, "__mro__", () + ) + + +def describe_in_subprocess(root: Path, package: str) -> Json: + """Describe ``package`` as importable from ``root``, isolated from this process.""" + cmd = [sys.executable, str(Path(__file__).resolve()), "--describe", str(root)] + cmd += ["--package", package] + env = dict(os.environ) + env.pop("PYTHONPATH", None) + proc = subprocess.run(cmd, capture_output=True, text=True, env=env, check=False) + if proc.returncode != 0: + raise SetupError( + f"describing {package} from {root} failed:\n{proc.stderr.strip()[-4000:]}" + ) + return json.loads(proc.stdout) + + +# -------------------------------------------------------------------------------------- +# Comparison +# -------------------------------------------------------------------------------------- + + +def render(t: Json) -> str: + k = t["k"] + if k == "any": + return "Any" + if k == "none": + return "None" + if k == "ellipsis": + return "..." + if k == "typevar": + return t["display"] + if k in ("name", "newtype"): + mod, qual = t["n"].split(":", 1) + return qual if mod != "typing" else f"typing.{qual}" + if k == "union": + return " | ".join(render(i) for i in t["items"]) + if k == "literal": + return "Literal[" + ", ".join(v for _, v in t["values"]) + "]" + if k == "generic": + name = render({"k": "name", "n": t["n"]}) + if not t["args"]: + return name + return f"{name}[" + ", ".join(render(a) for a in t["args"]) + "]" + if k == "callable": + params = "..." if t["params"] is None else ", ".join(map(render, t["params"])) + return f"Callable[[{params}], {render(t['returns'])}]" + return t.get("text", "?") + + +def render_sig(sig: Json) -> str: + stars = {"VAR_POSITIONAL": "*", "VAR_KEYWORD": "**"} + params = ", ".join( + f"{stars.get(p['kind'], '')}{p['name']}: {render(p['type'])}" for p in sig["params"] + ) + return f"({params}) -> {render(sig['returns'])}" + + +class Checker: + def __init__(self, old: Json, new: Json) -> None: + self.old = old + self.new = new + self.breaks: list[str] = [] + self.directions: dict[str, set[str]] = {} + + def run(self) -> list[str]: + self._classify_models() + for key, old_sym in sorted(self.old["symbols"].items()): + self._check_symbol(key, old_sym) + for key in sorted(self.old["classes"]): + if key in self.new["classes"]: + self._check_class(key) + return sorted(dict.fromkeys(self.breaks)) + + def _break(self, where: str, what: str) -> None: + self.breaks.append(f"{where}: {what}") + + # ---- assignability ----------------------------------------------------------- + + def _supers(self, side: Json, name: str) -> list[str]: + return side["supertypes"].get(name, [name]) + + def assignable(self, src: Json, dst: Json, src_side: Json, dst_side: Json) -> bool: + """Whether a value typed ``src`` (described in src_side) fits ``dst``.""" + sk, dk = src["k"], dst["k"] + if sk == "any" or dk == "any": + return True + if dk == "name" and dst["n"] == "builtins:object": + return True + if sk == "union": + return all(self.assignable(i, dst, src_side, dst_side) for i in src["items"]) + if dk == "union": + return any(self.assignable(src, i, src_side, dst_side) for i in dst["items"]) + # A type variable keeps its identity and the domain of values it accepts. + if sk == "typevar": + if dk == "typevar": + return ( + src["n"] == dst["n"] + and src["domain_kind"] == dst["domain_kind"] + and self.assignable(src["domain"], dst["domain"], src_side, dst_side) + ) + return self.assignable(src["domain"], dst, src_side, dst_side) + if dk == "typevar": + return False + if sk == "unresolved" or dk == "unresolved": + return sk == dk and src["text"] == dst["text"] + if sk == "none": + return dk == "none" + if sk == "literal": + if dk == "literal": + return all(v in dst["values"] for v in src["values"]) + return all( + self._name_fits(cls, dst, src_side) for cls, _ in src["values"] + ) + if sk == "newtype": + if dk == "newtype" and dst["n"] == src["n"]: + return True + return self.assignable(src["super"], dst, src_side, dst_side) + if sk == "callable": + if dk != "callable": + return dk == "name" and dst["n"] == "collections.abc:Callable" + if not self.assignable(src["returns"], dst["returns"], src_side, dst_side): + return False + if src["params"] is None or dst["params"] is None: + return True + if len(src["params"]) != len(dst["params"]): + return False + return all( + self.assignable(d, s, dst_side, src_side) + for s, d in zip(src["params"], dst["params"], strict=True) + ) + if sk in ("name", "generic"): + if dk == "newtype": + return False + if not self._name_fits(src["n"], dst, src_side): + return False + if sk == "generic" and dk == "generic": + sa, da = src["args"], dst["args"] + if not sa or not da: + return True + if len(sa) != len(da): + return False + return all( + a["k"] == b["k"] == "ellipsis" + or self._arg_fits(a, b, _variance(dst["n"], i), src_side, dst_side) + for i, (a, b) in enumerate(zip(sa, da, strict=True)) + ) + return True + return False + + def _arg_fits( + self, src: Json, dst: Json, variance: str, src_side: Json, dst_side: Json + ) -> bool: + forward = variance == "-" or self.assignable(src, dst, src_side, dst_side) + backward = variance == "+" or self.assignable(dst, src, dst_side, src_side) + return forward and backward + + def _name_fits(self, src_name: str, dst: Json, src_side: Json) -> bool: + if dst["k"] not in ("name", "generic"): + return False + target = dst["n"] + if target in self._supers(src_side, src_name): + return True + return target in _NUMERIC_PROMOTION.get(src_name, ()) + + def widened_output(self, old_t: Json, new_t: Json) -> bool: + return not self.assignable(new_t, old_t, self.new, self.old) + + def narrowed_input(self, old_t: Json, new_t: Json) -> bool: + return not self.assignable(old_t, new_t, self.old, self.new) + + # ---- model direction --------------------------------------------------------- + + def _data_class(self, name: str) -> bool: + info = self.old["classes"].get(name) + return bool(info) and info["kind"] in ("attrs", "dataclass", "typeddict", "pydantic") + + def _classify_models(self) -> None: + pending: list[tuple[Json, str]] = [] + + def sig_roots(sig: Json) -> None: + for p in sig["params"]: + pending.append((p["type"], INPUT)) + pending.append((sig["returns"], OUTPUT)) + for form in sig.get("overloads", []): + sig_roots(form) + + for sym in self.old["symbols"].values(): + if sym["kind"] == "function": + sig_roots(sym["sig"]) + for info in self.old["classes"].values(): + if info["kind"] in ("enum", "typeddict"): + continue + data = info["kind"] in ("attrs", "dataclass", "pydantic") + if not data and "init" in info: + sig_roots(info["init"]) + for name, member in info["methods"].items(): + if member["kind"] == "method": + if data and name == "from_dict": + continue + sig_roots(member["sig"]) + elif member["kind"] == "property": + pending.append((member["type"], OUTPUT)) + if not data: + for t in info["attributes"].values(): + pending.append((t, OUTPUT)) + + while pending: + t, direction = pending.pop() + for name, d in self._walk(t, direction): + if not self._data_class(name): + continue + seen = self.directions.setdefault(name, set()) + if d in seen: + continue + seen.add(d) + info = self.old["classes"][name] + if info["kind"] == "typeddict": + pending.extend((k["type"], d) for k in info["keys"].values()) + else: + pending.extend((a, d) for a in info["attributes"].values()) + + def _walk(self, t: Json, direction: str) -> Iterator[tuple[str, str]]: + k = t["k"] + if k in ("name", "generic"): + yield t["n"], direction + for a in t.get("args", []): + yield from self._walk(a, direction) + elif k == "union": + for i in t["items"]: + yield from self._walk(i, direction) + elif k == "callable": + flipped = OUTPUT if direction == INPUT else INPUT + for p in t["params"] or []: + yield from self._walk(p, flipped) + yield from self._walk(t["returns"], direction) + elif k == "typevar": + yield from self._walk(t["domain"], direction) + + def model_directions(self, name: str) -> set[str]: + # A model no API accepts or returns (an orphan schema) only has to keep existing. + return self.directions.get(name, set()) + + # ---- symbols ----------------------------------------------------------------- + + def _check_symbol(self, key: str, old_sym: Json) -> None: + new_sym = self.new["symbols"].get(key) + where = key + if new_sym is None: + self._break(where, f"{old_sym['kind']} removed") + return + if new_sym["kind"] != old_sym["kind"]: + self._break(where, f"changed from {old_sym['kind']} to {new_sym['kind']}") + return + if old_sym["kind"] == "module": + if "broken" in new_sym and "broken" not in old_sym: + self._break(where, f"module no longer imports: {new_sym['broken']}") + return + if old_sym["kind"] == "function": + self._check_signature(where, old_sym["sig"], new_sym["sig"]) + elif old_sym["kind"] == "class" and old_sym["ref"] != new_sym["ref"]: + self._break(where, f"now refers to {new_sym['ref']} instead of {old_sym['ref']}") + elif old_sym["kind"] == "alias": + if self.widened_output(old_sym["type"], new_sym["type"]) or self.narrowed_input( + old_sym["type"], new_sym["type"] + ): + self._break( + where, + f"type alias changed from {render(old_sym['type'])} " + f"to {render(new_sym['type'])}", + ) + elif old_sym["kind"] == "value" and self.widened_output( + old_sym["type"], new_sym["type"] + ): + self._break( + where, + f"type widened from {render(old_sym['type'])} to {render(new_sym['type'])}", + ) + + def _check_signature( + self, where: str, old: Json, new: Json, *, implemented: bool = False + ) -> None: + if old.get("opaque") or new.get("opaque"): + return + if "overloads" not in old and "overloads" not in new: + self._check_form(where, old, new, implemented) + return + # Callers type-check against the overloads, not the implementation: every + # baseline form must still be accepted by some current form. + new_forms = new.get("overloads") or [new] + for form in old.get("overloads") or [old]: + if not any( + not self._form_breaks(where, form, nf, implemented) for nf in new_forms + ): + self._break(where, f"no longer supports the signature {render_sig(form)}") + + def _form_breaks(self, where: str, old: Json, new: Json, implemented: bool) -> bool: + saved, self.breaks = self.breaks, [] + try: + self._check_form(where, old, new, implemented) + return bool(self.breaks) + finally: + self.breaks = saved + + def _check_param_type( + self, where: str, label: str, p: Json, q: Json, implemented: bool + ) -> None: + if self.narrowed_input(p["type"], q["type"]): + self._break( + where, + f"parameter '{label}' no longer accepts {render(p['type'])} " + f"(now {render(q['type'])})", + ) + if implemented and self.widened_output(p["type"], q["type"]): + self._break( + where, + f"implementations of parameter '{label}' now receive " + f"{render(q['type'])} (was {render(p['type'])})", + ) + + def _check_form(self, where: str, old: Json, new: Json, implemented: bool) -> None: + if old["async"] != new["async"]: + self._break(where, "changed between sync and async") + new_params = {p["name"]: (i, p) for i, p in enumerate(new["params"])} + old_names = {p["name"] for p in old["params"]} + old_var = { + p["kind"]: p for p in old["params"] if p["kind"] in ("VAR_POSITIONAL", "VAR_KEYWORD") + } + for i, p in enumerate(old["params"]): + name, kind = p["name"], p["kind"] + if kind in ("VAR_POSITIONAL", "VAR_KEYWORD"): + star = "*" if kind == "VAR_POSITIONAL" else "**" + var = next((q for q in new["params"] if q["kind"] == kind), None) + if var is None: + self._break(where, f"no longer accepts {star}{name}") + else: + self._check_param_type(where, f"{star}{name}", p, var, implemented) + continue + hit = new_params.get(name) + if hit is None: + self._break(where, f"parameter '{name}' removed") + continue + j, q = hit + if q["kind"] in ("VAR_POSITIONAL", "VAR_KEYWORD"): + self._break(where, f"parameter '{name}' removed") + continue + if kind != "POSITIONAL_ONLY" and q["kind"] == "POSITIONAL_ONLY": + self._break(where, f"parameter '{name}' can no longer be passed by keyword") + # Optional parameters can be passed positionally too. + if kind in ("POSITIONAL_ONLY", "POSITIONAL_OR_KEYWORD"): + if q["kind"] == "KEYWORD_ONLY": + self._break( + where, f"parameter '{name}' can no longer be passed positionally" + ) + elif j != i: + self._break(where, f"parameter '{name}' moved from position {i} to {j}") + if p["has_default"] and not q["has_default"]: + self._break(where, f"parameter '{name}' is now required") + self._check_param_type(where, name, p, q, implemented) + for q in new["params"]: + if q["name"] in old_names or q["kind"] in ("VAR_POSITIONAL", "VAR_KEYWORD"): + continue + if not q["has_default"]: + self._break(where, f"new required parameter '{q['name']}'") + elif implemented: + self._break(where, f"implementations must accept new parameter '{q['name']}'") + if ( + q["kind"] == "POSITIONAL_OR_KEYWORD" + and old_var.get("VAR_POSITIONAL") is not None + and old_var.get("VAR_KEYWORD") is not None + ): + self._break( + where, + f"new parameter '{q['name']}' can bind both positional and keyword " + "arguments previously accepted by *args and **kwargs", + ) + # Arguments the baseline's *args/**kwargs took now bind to this parameter. + captured = [] + if q["kind"] in ("POSITIONAL_ONLY", "POSITIONAL_OR_KEYWORD"): + captured.append(("*", old_var.get("VAR_POSITIONAL"))) + if q["kind"] in ("POSITIONAL_OR_KEYWORD", "KEYWORD_ONLY"): + captured.append(("**", old_var.get("VAR_KEYWORD"))) + for star, var in captured: + if var is not None and self.narrowed_input(var["type"], q["type"]): + self._break( + where, + f"new parameter '{q['name']}' no longer accepts " + f"{render(var['type'])} passed through {star}{var['name']} " + f"(now {render(q['type'])})", + ) + if self.widened_output(old["returns"], new["returns"]): + self._break( + where, + f"return type widened from {render(old['returns'])} " + f"to {render(new['returns'])}", + ) + if implemented and self.narrowed_input(old["returns"], new["returns"]): + self._break( + where, + f"implementations' return type narrowed from {render(old['returns'])} " + f"to {render(new['returns'])}", + ) + + # ---- classes ----------------------------------------------------------------- + + def _check_class(self, key: str) -> None: + old = self.old["classes"][key] + new = self.new["classes"][key] + where = key + if old["kind"] != new["kind"] and "protocol" in (old["kind"], new["kind"]): + self._break(where, f"changed from {old['kind']} to {new['kind']}") + return + for base in old["bases"]: + if base not in new["bases"]: + self._break(where, f"no longer derives from {base}") + + if old["kind"] == "enum": + new_members = new.get("members", {}) + for name, value in old["members"].items(): + if name not in new_members: + self._break(f"{where}.{name}", "enum member removed") + elif new_members[name] != value: + self._break( + f"{where}.{name}", + f"enum value changed from {value} to {new_members[name]}", + ) + return + + if old["kind"] == "typeddict": + self._check_typeddict(where, old, new) + return + + data = old["kind"] in ("attrs", "dataclass", "pydantic") + dirs = self.model_directions(key) if data else {INPUT, OUTPUT} + protocol = old["kind"] == "protocol" + + if "init" in old and "init" in new and INPUT in dirs and not protocol: + self._check_signature(f"{where}()", old["init"], new["init"]) + + reads = OUTPUT in dirs or protocol + for name, old_t in old["attributes"].items(): + new_t = new["attributes"].get(name) + if new_t is None: + replacement = new["methods"].get(name) + if replacement is None: + self._break(f"{where}.{name}", "attribute removed") + elif replacement["kind"] == "method": + self._break(f"{where}.{name}", "changed from attribute to method") + elif replacement["kind"] == "property": + new_t = replacement["type"] + if new_t is None: + continue + if not reads: + continue + if self.widened_output(old_t, new_t): + self._break( + f"{where}.{name}", + f"type widened from {render(old_t)} to {render(new_t)}", + ) + if protocol and self.narrowed_input(old_t, new_t): + self._break( + f"{where}.{name}", + f"implementations' type narrowed from {render(old_t)} " + f"to {render(new_t)}", + ) + + for name, old_m in old["methods"].items(): + new_m = new["methods"].get(name) + member = f"{where}.{name}" + if new_m is None: + new_t = new["attributes"].get(name) + if new_t is None: + self._break(member, f"{old_m['kind']} removed") + elif old_m["kind"] == "method": + self._break(member, "changed from method to attribute") + elif old_m["kind"] == "property" and self.widened_output( + old_m["type"], new_t + ): + self._break( + member, + f"type widened from {render(old_m['type'])} to {render(new_t)}", + ) + continue + if new_m["kind"] != old_m["kind"]: + self._break(member, f"changed from {old_m['kind']} to {new_m['kind']}") + elif old_m["kind"] == "method": + # Instance calls work for every binding; class-level calls need class/static. + if old_m["binding"] != new_m["binding"] and ( + protocol or new_m["binding"] == "instance" + ): + self._break( + member, + f"changed from {old_m['binding']} method to " + f"{new_m['binding']} method", + ) + self._check_signature(member, old_m["sig"], new_m["sig"], implemented=protocol) + elif old_m["kind"] == "property" and self.widened_output( + old_m["type"], new_m["type"] + ): + self._break( + member, + f"type widened from {render(old_m['type'])} to {render(new_m['type'])}", + ) + elif old_m["kind"] == "value" and self.widened_output( + old_m["type"], new_m["type"] + ): + self._break( + member, + f"type widened from {render(old_m['type'])} to {render(new_m['type'])}", + ) + if protocol: + for name in new["methods"].keys() | new["attributes"].keys(): + if name not in old["methods"] and name not in old["attributes"]: + self._break(f"{where}.{name}", "new member required of implementations") + + def _check_typeddict(self, where: str, old: Json, new: Json) -> None: + dirs = self.model_directions(where) + old_keys, new_keys = old["keys"], new["keys"] + for name, ok in old_keys.items(): + nk = new_keys.get(name) + if nk is None: + self._break(f"{where}[{name!r}]", "key removed") + continue + if OUTPUT in dirs: + if ok["required"] and not nk["required"]: + self._break(f"{where}[{name!r}]", "key is no longer always present") + if self.widened_output(ok["type"], nk["type"]): + self._break( + f"{where}[{name!r}]", + f"type widened from {render(ok['type'])} to {render(nk['type'])}", + ) + if INPUT in dirs: + if not ok["required"] and nk["required"]: + self._break(f"{where}[{name!r}]", "key is now required") + if self.narrowed_input(ok["type"], nk["type"]): + self._break( + f"{where}[{name!r}]", + f"no longer accepts {render(ok['type'])} (now {render(nk['type'])})", + ) + if INPUT in dirs: + for name, nk in new_keys.items(): + if name not in old_keys and nk["required"]: + self._break(f"{where}[{name!r}]", "new required key") + + +def find_breaks(old: Json, new: Json) -> list[str]: + return Checker(old, new).run() + + +# -------------------------------------------------------------------------------------- +# CLI +# -------------------------------------------------------------------------------------- + + +def _summary(lines: list[str]) -> None: + path = os.environ.get("GITHUB_STEP_SUMMARY") + if path: + with open(path, "a", encoding="utf-8") as fh: + fh.write("\n".join(lines) + "\n") + + +def _run(args: argparse.Namespace) -> int: + if args.describe: + sys.path.insert(0, args.describe) + # Deprecated aliases warn on access; describing them is not using them. + warnings.simplefilter("ignore") + json.dump(Describer(args.package).describe(Path(args.describe)), sys.stdout) + return 0 + + metadata: Json | None = None + if args.print_baseline_major is not None: + metadata = fetch_pypi_metadata() + print(latest_release(metadata, args.print_baseline_major) or "") + return 0 + + current_root = Path(args.current).resolve() + with tempfile.TemporaryDirectory(prefix="api-compat-") as tmp: + if args.baseline_dir: + baseline_root = Path(args.baseline_dir).resolve() + label = str(baseline_root) + else: + metadata = fetch_pypi_metadata() + if args.baseline_version: + version = args.baseline_version + else: + version = latest_release(metadata, args.baseline_major) + if version is None: + print( + f"::notice::No {args.baseline_major}.x release of {DISTRIBUTION} " + "is published yet; nothing to compare against." + ) + return 0 + baseline_root = download_baseline(metadata, version, Path(tmp)) + label = f"{DISTRIBUTION} {version}" + print(f"Baseline: {label}") + print(f"Current: {current_root}") + old = describe_in_subprocess(baseline_root, args.package) + new = describe_in_subprocess(current_root, args.package) + + breaks = find_breaks(old, new) + if not breaks: + print(f"Compatible: no breaking changes to the public API since {label}.") + _summary([f"### API compatibility\n\nNo breaking changes since `{label}`."]) + return 0 + print(f"{len(breaks)} breaking change(s) to the public API since {label}:") + for b in breaks: + print(f" - {b}") + _summary( + [f"### API compatibility\n\n{len(breaks)} breaking change(s) since `{label}`:\n"] + + [f"- `{b}`" for b in breaks] + ) + return 1 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + which = parser.add_mutually_exclusive_group(required=True) + which.add_argument("--baseline-major", type=int, help="compare with the newest N.x.y") + which.add_argument("--baseline-version", help="compare with this published version") + which.add_argument("--baseline-dir", help="compare with a package root on disk") + which.add_argument( + "--print-baseline-major", + type=int, + metavar="N", + help="print the newest published N.x.y (empty if none) and exit", + ) + which.add_argument("--describe", help=argparse.SUPPRESS) + parser.add_argument( + "--current", + default=str(REPO_ROOT / "generated"), + help="package root of the build to check (default: generated/)", + ) + parser.add_argument("--package", default=PACKAGE, help=argparse.SUPPRESS) + args = parser.parse_args(argv) + try: + return _run(args) + except SetupError as exc: + print(f"::error::api-compat: {exc}", file=sys.stderr) + return 2 + except Exception as exc: # any other failure is a tool error, never a verdict + traceback.print_exc() + print(f"::error::api-compat failed: {exc!r}", file=sys.stderr) + return 2 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/semantic-release-with-retry.sh b/scripts/semantic-release-with-retry.sh new file mode 100755 index 000000000..6c7ca70b0 --- /dev/null +++ b/scripts/semantic-release-with-retry.sh @@ -0,0 +1,115 @@ +#!/usr/bin/env bash +# Run `semantic-release version`, retrying (up to 3 attempts) only when it fails because +# another commit landed on the release branch while the release was running. +# +# Called by the "Create release" step of .github/workflows/publish.yml. +# +# `semantic-release version` commits `chore(release): X [skip ci]`, tags it, and pushes +# the commit and tag to the branch. It aborts ("Upstream branch has changed") or has its +# push rejected if the branch moved since checkout, as happens when a Renovate PR merges +# mid-release. Nothing is published at that point: the GitHub release is created only +# after the push succeeds, and PyPI publishing is a later workflow step. So it is safe to +# throw away the unpushed release commit and tag, move to the new branch tip, and run it +# again; semantic-release recomputes the next version from the tags on every run. +# +# We deliberately do not use `version --no-push`: in python-semantic-release it also +# disables creation of the GitHub release ("No vcs release will be created because +# pushing changes is disabled"). +# +# Each attempt starts from a clean slate and re-validates what it is about to release: +# - `dist/` is removed first. `semantic-release version` runs the configured build +# (`uv build`) BEFORE its upstream check and push, so a failed attempt leaves +# distributions for its version in the untracked `dist/`, which `git reset --hard` does +# not touch. If the retry computed a different version, the abandoned one would sit +# next to the real one and be uploaded by `semantic-release publish` / PyPI. +# - on `stable/` the version the attempt is about to release is recomputed with +# `version --print` and checked against the branch (same rule as the workflow's +# "Validate version matches stable branch" step), because a retry may have picked up +# a concurrent breaking-change commit. `--print` and the real run read the same local +# HEAD, and the real run's push only succeeds if origin is still at that HEAD, so the +# validated version is the one that gets pushed. Nothing is pushed if it fails. +# - on `stable/`, after a reset the public API is re-checked with +# scripts/api-compat-gate.sh (the workflow's gate step covered the first attempt's +# HEAD), so code that landed in the concurrent push cannot be released unchecked. +# +# Never force-pushes. Any other failure, or a race lost after the release commit was +# already pushed, fails immediately and loudly. +set -euo pipefail + +BRANCH="${GITHUB_REF_NAME:-$(git rev-parse --abbrev-ref HEAD)}" +MAX_ATTEMPTS=3 +REPO_ROOT="$(git rev-parse --show-toplevel)" +API_COMPAT_GATE="$(dirname "${BASH_SOURCE[0]}")/api-compat-gate.sh" +LOG_DIR="${RUNNER_TEMP:-${TMPDIR:-/tmp}}" +# semantic-release's own check, plus git's wording for a rejected push, which varies by +# git version and code path. +RACE_RE='(upstream branch has changed|non-fast-forward|fetch first|stale info|rejected because|failed to update ref|\[rejected\])' + +for attempt in $(seq 1 "$MAX_ATTEMPTS"); do + echo "semantic-release version attempt ${attempt}/${MAX_ATTEMPTS}" + + # One log per attempt, so a retry does not overwrite the record of why the previous + # attempt failed. Kept outside the work tree so semantic-release never sees them. + LOG="${LOG_DIR}/semantic-release-attempt-${attempt}.out" + + # Drop distributions left by a previous (abandoned) attempt; see the header. + rm -rf "${REPO_ROOT}/dist" + + # Validate the version this attempt would release before anything is committed or pushed. + if [[ "$BRANCH" == stable/* ]]; then + # stdout is just the version; the human-readable messages go to stderr. + candidate=$(uv run semantic-release version --print 2>"${LOG_DIR}/semantic-release-print-${attempt}.err" | tail -1) || candidate="" + if [ -z "$candidate" ]; then + cat "${LOG_DIR}/semantic-release-print-${attempt}.err" >&2 || true + echo "::error::could not determine the version to release on ${BRANCH}; not releasing." + exit 1 + fi + branch_major="${BRANCH#stable/}" + if [[ ! "$candidate" =~ ^${branch_major}\. ]]; then + echo "::error::Version $candidate doesn't match branch constraint ${branch_major}.x" + exit 1 + fi + if [ "$attempt" -gt 1 ]; then + bash "$API_COMPAT_GATE" "$BRANCH" || exit $? + fi + fi + + set +e + uv run semantic-release version 2>&1 | tee "$LOG" + status=${PIPESTATUS[0]} + set -e + + if [ "$status" -eq 0 ]; then + exit 0 + fi + + if [ "$attempt" -eq "$MAX_ATTEMPTS" ]; then + echo "::error::semantic-release version failed after ${attempt} attempt(s); giving up." + exit "$status" + fi + + if ! grep -qiE "$RACE_RE" "$LOG"; then + echo "::error::semantic-release version failed for a reason other than a concurrent push; not retrying." + exit "$status" + fi + + failed_head=$(git rev-parse HEAD) + git fetch origin "$BRANCH" + + # If the release commit already reached the remote, a retry would release it twice. + if git merge-base --is-ancestor "$failed_head" "origin/${BRANCH}" && + [[ "$(git log -1 --format=%s "$failed_head")" == "chore(release):"* ]]; then + echo "::error::the release commit is already on origin/${BRANCH}; not retrying." + exit "$status" + fi + + echo "Release on ${BRANCH} lost a race with a concurrent push; resetting to origin/${BRANCH} and retrying." + # Drop the local tag(s) semantic-release created on the unpushed release commit, or the + # retry could not recreate the same tag. Then restore any tag that does exist remotely. + git tag --points-at "$failed_head" | xargs -r git tag -d + git fetch origin --tags + # Safe: the only local commit is the release commit semantic-release made and failed + # to push; nothing depends on it. + git reset --hard "origin/${BRANCH}" + sleep 5 +done diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py new file mode 100644 index 000000000..a9cf40726 --- /dev/null +++ b/tests/acceptance/test_api_compat.py @@ -0,0 +1,986 @@ +"""Tests for the stable-branch API compatibility checker (``scripts/api_compat.py``). + +Every case starts from one baseline package shaped like the generated SDK (attrs models +with ``Unset``, an enum, a client class, module-level functions). A break case applies a +single textual mutation to it and must be reported; a compatible case must not be. The +baseline compared with itself is asserted green first, so a break case can only fail +because of its mutation. +""" + +import importlib.util +import json +import os +import subprocess +import sys +import textwrap +from pathlib import Path +from typing import Any + +import pytest + +pytestmark = pytest.mark.skipif( + sys.version_info < (3, 11), + reason="stdlib overload signatures are only introspectable on Python 3.11+", +) + +_SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "api_compat.py" +_spec = importlib.util.spec_from_file_location("api_compat", _SCRIPT) +assert _spec and _spec.loader +api_compat = importlib.util.module_from_spec(_spec) +sys.modules["api_compat"] = api_compat +_spec.loader.exec_module(api_compat) + +PKG = "acfix" + +BASELINE: dict[str, str] = { + "__init__.py": """ + from .client import Client + from .models import Color, RequestModel, ResultModel + """, + "types.py": """ + class Unset: + def __bool__(self) -> bool: + return False + + UNSET: Unset = Unset() + """, + "models/__init__.py": """ + from .color import Color + from .request_model import RequestModel + from .result_model import ResultModel + + __all__ = ("Color", "RequestModel", "ResultModel") + """, + "models/color.py": """ + from enum import Enum + + class Color(str, Enum): + RED = "red" + BLUE = "blue" + """, + "models/page.py": """ + # No `from __future__ import annotations`: 3.14 then adds __annotate_func__. + class Page: + total: int + """, + "models/payload.py": """ + from __future__ import annotations + + from typing import TypedDict + + try: + from typing import NotRequired + except ImportError: + from typing_extensions import NotRequired + + class Payload(TypedDict): + required: str + optional: NotRequired[str] + """, + "models/settings.py": """ + from __future__ import annotations + + import dataclasses + + @dataclasses.dataclass + class Settings: + name: str + flag: bool = False + + @classmethod + def from_dict(cls, data: dict[str, str]) -> Settings: + return cls(name=data["name"]) + + @staticmethod + def default() -> Settings: + return Settings(name="") + """, + "models/orphan.py": """ + from __future__ import annotations + + import attrs + + @attrs.define + class Orphan: + value: str + """, + "models/request_model.py": """ + from __future__ import annotations + + import attrs + + from ..types import UNSET, Unset + + @attrs.define + class RequestModel: + name: str + limit: int | None = None + color: Color | Unset = UNSET + + @classmethod + def from_dict(cls, src_dict: dict[str, object]) -> RequestModel: + return cls(name=str(src_dict["name"])) + + from .color import Color + """, + "models/result_model.py": """ + from __future__ import annotations + + from typing import TYPE_CHECKING + + import attrs + + from ..types import UNSET, Unset + + if TYPE_CHECKING: + from .color import Color + + @attrs.define + class ResultModel: + name: str + count: int + color: Color + tags: list[str] | Unset = UNSET + """, + "client.py": """ + from __future__ import annotations + + from collections.abc import Sequence + from typing import Generic, TypeVar, overload + + from .models.request_model import RequestModel + from .models.result_model import ResultModel + from .models.page import Page + from .models.payload import Payload + from .models.settings import Settings + + T = TypeVar("T") + B = TypeVar("B", bound=str | bytes) + C = TypeVar("C", str, bytes, int) + + DEFAULT_LIMIT = 10 + + class ApiError(Exception): + def __init__(self, status_code: int, content: bytes) -> None: + self.status_code = status_code + self.content = content + + class Box(Generic[T]): + def get(self) -> T: + raise NotImplementedError + + class GenericBase(Generic[T]): + value: T + + class IntBox(GenericBase[int]): + pass + + class Limits: + MAX = 10 + + class OverloadedCtor: + @overload + def __init__(self, value: int) -> None: ... + + @overload + def __init__(self, value: str) -> None: ... + + def __init__(self, value: int | str) -> None: + pass + + def echo_bound(value: B) -> B: + return value + + def echo_constraints(value: C) -> C: + return value + + class Client: + def int_box(self) -> IntBox: + raise NotImplementedError + + def limits(self) -> Limits: + raise NotImplementedError + + def submit(self, payload: Payload) -> None: + pass + + def page(self) -> Page: + raise NotImplementedError + + def settings(self) -> Settings: + raise NotImplementedError + + def __enter__(self) -> Client: + return self + + def __exit__(self, *args: object) -> None: + pass + + async def __aenter__(self) -> Client: + return self + + def __getitem__(self, key: str) -> ResultModel: + raise NotImplementedError + + @overload + def pick(self, x: int) -> int: ... + + @overload + def pick(self, x: str) -> str: ... + + def pick(self, x: int | str) -> int | str: + return x + + def put_all(self, items: list[str]) -> None: + pass + + def put_seq(self, items: Sequence[str]) -> None: + pass + + def names(self) -> list[str | None]: + return [] + + def opts(self, *args: str, **options: str) -> None: + pass + + def deploy( + self, files: str, tenant_id: str | None = None, region: str | None = None + ) -> None: + pass + + def get_thing(self, key: str, *, verbose: bool = False) -> ResultModel: + raise NotImplementedError + + def create_thing(self, data: RequestModel) -> None: + raise NotImplementedError + + def count(self, n: int) -> int: + raise NotImplementedError + + def find(self, key: str) -> ResultModel | None: + raise NotImplementedError + + async def aget(self, key: str) -> ResultModel: + raise NotImplementedError + + def helper(x: str) -> str: + return x + """, +} + +# (id, file, old text, new text, expected substring of one reported break) +BREAKS: list[tuple[str, str, str | None, str | None, str]] = [ + ( + "module-removed", + "models/orphan.py", + None, + None, + "acfix.models.orphan: module removed", + ), + ( + "class-removed", + "models/orphan.py", + "class Orphan:", + "class Orphan2:", + "acfix.models.orphan:Orphan: class removed", + ), + ( + "re-export-removed", + "models/__init__.py", + '"RequestModel", "ResultModel")', + '"RequestModel")', + "acfix.models:ResultModel: class removed", + ), + ( + "function-removed", + "client.py", + "def helper(x: str) -> str:", + "def helper2(x: str) -> str:", + "acfix.client:helper: function removed", + ), + ( + "method-removed", + "client.py", + "def count(self, n: int)", + "def total(self, n: int)", + "acfix.client:Client.count: method removed", + ), + ( + "result-attribute-removed", + "models/result_model.py", + " count: int\n", + "", + "ResultModel.count: attribute removed", + ), + ( + "enum-member-removed", + "models/color.py", + ' BLUE = "blue"\n', + "", + "Color.BLUE: enum member removed", + ), + ( + "enum-value-changed", + "models/color.py", + 'BLUE = "blue"', + 'BLUE = "navy"', + "Color.BLUE: enum value changed", + ), + ( + "new-required-param", + "client.py", + "def get_thing(self, key: str, *,", + "def get_thing(self, key: str, scope: str, *,", + "Client.get_thing: new required parameter 'scope'", + ), + ( + "optional-param-now-required", + "client.py", + "verbose: bool = False", + "verbose: bool", + "Client.get_thing: parameter 'verbose' is now required", + ), + ( + "param-removed", + "client.py", + "def get_thing(self, key: str, *, verbose: bool = False)", + "def get_thing(self, key: str)", + "Client.get_thing: parameter 'verbose' removed", + ), + ( + "param-renamed", + "client.py", + "def count(self, n: int)", + "def count(self, m: int)", + "Client.count: parameter 'n' removed", + ), + ( + "param-narrowed", + "client.py", + "def count(self, n: int)", + "def count(self, n: bool)", + "Client.count: parameter 'n' no longer accepts int", + ), + ( + "return-widened-to-optional", + "client.py", + "def count(self, n: int) -> int:", + "def count(self, n: int) -> int | None:", + "Client.count: return type widened from int to int | None", + ), + ( + "return-type-changed", + "client.py", + "def helper(x: str) -> str:", + "def helper(x: str) -> bytes:", + "acfix.client:helper: return type widened from str to bytes", + ), + ( + "result-field-optional", + "models/result_model.py", + " name: str\n", + " name: str | None\n", + "ResultModel.name: type widened from str to str | None", + ), + ( + "result-field-unset", + "models/result_model.py", + " count: int\n color: Color\n", + " color: Color\n count: int | Unset = UNSET\n", + "ResultModel.count: type widened from int to int | Unset", + ), + ( + "result-nested-field-optional", + "models/result_model.py", + "tags: list[str] | Unset", + "tags: list[str | None] | Unset", + "ResultModel.tags: type widened", + ), + ( + "request-new-required-field", + "models/request_model.py", + " name: str\n", + " name: str\n extra: str\n", + "RequestModel(): new required parameter 'extra'", + ), + ( + "request-field-narrowed", + "models/request_model.py", + "limit: int | None = None", + "limit: int = 0", + "RequestModel(): parameter 'limit' no longer accepts int | None", + ), + ( + "sync-to-async", + "client.py", + " def find(self", + " async def find(self", + "Client.find: changed between sync and async", + ), + ( + "output-defaulted-dataclass-field-widened", + "models/settings.py", + "flag: bool = False", + "flag: bool | None = None", + "Settings.flag: type widened from bool to bool | None", + ), + ( + "classmethod-to-instance-method", + "models/settings.py", + " @classmethod\n def from_dict(cls,", + " def from_dict(self,", + "Settings.from_dict: changed from class method to instance method", + ), + ( + "generated-from-dict-removed", + "models/request_model.py", + " @classmethod\n def from_dict(cls, src_dict: dict[str, object]) -> RequestModel:\n" + " return cls(name=str(src_dict[\"name\"]))\n", + "", + "RequestModel.from_dict: method removed", + ), + ( + "staticmethod-to-instance-method", + "models/settings.py", + " @staticmethod\n def default() -> Settings:", + " def default(self) -> Settings:", + "Settings.default: changed from static method to instance method", + ), + ( + "init-attribute-removed", + "client.py", + " self.content = content\n", + "", + "ApiError.content: attribute removed", + ), + ( + "init-attribute-widened", + "client.py", + "self.status_code = status_code", + "self.status_code: int | None = status_code", + "ApiError.status_code: type widened from int to int | None", + ), + ( + "typevar-return-made-concrete", + "client.py", + "def get(self) -> T:", + "def get(self) -> str:", + "Box.get: return type widened from T to str", + ), + ( + "module-value-widened", + "types.py", + "UNSET: Unset = Unset()", + "UNSET: Unset | None = Unset()", + "acfix.types:UNSET: type widened from Unset to Unset | None", + ), + ( + "class-value-widened", + "client.py", + "MAX = 10", + "MAX = None", + "Limits.MAX: type widened from int to None", + ), + ( + "constructor-overload-removed", + "client.py", + " @overload\n def __init__(self, value: str) -> None: ...\n\n", + "", + "OverloadedCtor(): no longer supports the signature (value: str) -> None", + ), + ( + "inherited-generic-field-specialization-changed", + "client.py", + "class IntBox(GenericBase[int]):", + "class IntBox(GenericBase[str]):", + "IntBox.value: type widened from int to str", + ), + ( + "unannotated-module-value-changed", + "client.py", + "DEFAULT_LIMIT = 10", + "DEFAULT_LIMIT = None", + "acfix.client:DEFAULT_LIMIT: type widened from int to None", + ), + ( + "field-to-wider-property", + "models/page.py", + "class Page:\n total: int\n", + "class Page:\n @property\n def total(self) -> int | None:\n return 0\n", + "Page.total: type widened from int to int | None", + ), + ( + "field-to-method", + "models/page.py", + "class Page:\n total: int\n", + "class Page:\n def total(self) -> int:\n return 0\n", + "Page.total: changed from attribute to method", + ), + ( + "new-keyword-param-captures-kwargs", + "client.py", + "def opts(self, *args: str, **options: str)", + "def opts(self, *args: str, label: int = 0, **options: str)", + "Client.opts: new parameter 'label' no longer accepts str passed through **options", + ), + ( + "new-positional-param-captures-args", + "client.py", + "def opts(self, *args: str, **options: str)", + "def opts(self, first: int = 0, *args: str, **options: str)", + "Client.opts: new parameter 'first' no longer accepts str passed through *args", + ), + ( + "new-parameter-binds-both-variadic-channels", + "client.py", + "def opts(self, *args: str, **options: str)", + 'def opts(self, first: str = "", *args: str, **options: str)', + "Client.opts: new parameter 'first' can bind both positional and keyword arguments", + ), + ( + "typevar-bound-narrowed", + "client.py", + 'B = TypeVar("B", bound=str | bytes)', + 'B = TypeVar("B", bound=str)', + "acfix.client:echo_bound: parameter 'value' no longer accepts B", + ), + ( + "typevar-constraints-narrowed", + "client.py", + 'C = TypeVar("C", str, bytes, int)', + 'C = TypeVar("C", str, bytes)', + "acfix.client:echo_constraints: parameter 'value' no longer accepts C", + ), + ( + "typed-dict-notrequired-becomes-required", + "models/payload.py", + "optional: NotRequired[str]", + "optional: str", + "Payload['optional']: key is now required", + ), + ( + "special-method-removed", + "client.py", + " def __getitem__(self, key: str)", + " def get_item(self, key: str)", + "Client.__getitem__: method removed", + ), + ( + "async-special-method-removed", + "client.py", + " async def __aenter__(self)", + " async def aenter(self)", + "Client.__aenter__: method removed", + ), + ( + "overload-removed", + "client.py", + " @overload\n def pick(self, x: str) -> str: ...\n", + "", + "Client.pick: no longer supports the signature (x: str) -> str", + ), + ( + "overload-return-widened", + "client.py", + "def pick(self, x: int) -> int: ...", + "def pick(self, x: int) -> int | None: ...", + "Client.pick: no longer supports the signature (x: int) -> int", + ), + ( + "invariant-input-arg-widened", + "client.py", + "items: list[str]", + "items: list[str | None]", + "Client.put_all: parameter 'items' no longer accepts list[str]", + ), + ( + "invariant-output-arg-narrowed", + "client.py", + "def names(self) -> list[str | None]:", + "def names(self) -> list[str]:", + "Client.names: return type widened from list[str | None] to list[str]", + ), + ( + "var-positional-narrowed", + "client.py", + "*args: str", + "*args: int", + "Client.opts: parameter '*args' no longer accepts str", + ), + ( + "var-keyword-narrowed", + "client.py", + "**options: str", + "**options: int", + "Client.opts: parameter '**options' no longer accepts str", + ), + ( + "optional-param-keyword-only", + "client.py", + "files: str, tenant_id", + "files: str, *, tenant_id", + "Client.deploy: parameter 'tenant_id' can no longer be passed positionally", + ), + ( + "optional-params-reordered", + "client.py", + "tenant_id: str | None = None, region: str | None = None", + "region: str | None = None, tenant_id: str | None = None", + "Client.deploy: parameter 'tenant_id' moved from position 1 to 2", + ), +] + +COMPATIBLE: list[tuple[str, str, str, str]] = [ + ( + "new-function", + "client.py", + "def helper(x: str) -> str:", + "def other() -> None:\n pass\n\ndef helper(x: str) -> str:", + ), + ( + "new-optional-param", + "client.py", + "verbose: bool = False)", + "verbose: bool = False, page: int = 1)", + ), + ( + "param-widened", + "client.py", + "def count(self, n: int)", + "def count(self, n: int | str)", + ), + ( + "return-narrowed", + "client.py", + "-> ResultModel | None:", + "-> ResultModel:", + ), + ( + "request-new-optional-field", + "models/request_model.py", + " color: Color | Unset = UNSET\n", + " color: Color | Unset = UNSET\n offset: int | Unset = UNSET\n", + ), + ( + "request-field-becomes-optional", + "models/request_model.py", + " name: str\n", + " name: str | None = None\n", + ), + ( + "request-field-widened", + "models/request_model.py", + "limit: int | None = None", + "limit: int | str | None = None", + ), + ( + "result-new-required-field", + "models/result_model.py", + " color: Color\n", + " color: Color\n extra: str\n", + ), + ( + "result-field-narrowed", + "models/result_model.py", + "tags: list[str] | Unset = UNSET", + "tags: list[str] = attrs.field(factory=list)", + ), + ( + "new-enum-member", + "models/color.py", + ' BLUE = "blue"\n', + ' BLUE = "blue"\n GREEN = "green"\n', + ), + ( + # A model nothing accepts or returns only has to keep existing. + "orphan-field-changed", + "models/orphan.py", + "value: str", + "value: str | None = None", + ), + ( + "covariant-input-arg-widened", + "client.py", + "items: Sequence[str]", + "items: Sequence[str | None]", + ), + ( + "new-overload", + "client.py", + " def pick(self, x: int | str) -> int | str:", + " @overload\n def pick(self, x: bytes) -> bytes: ...\n\n" + " def pick(self, x: int | str | bytes) -> int | str | bytes:", + ), + ( + "new-keyword-param-matching-kwargs", + "client.py", + "def opts(self, *args: str, **options: str)", + 'def opts(self, *args: str, label: str = "", **options: str)', + ), + ( + "init-attribute-added", + "client.py", + " self.content = content\n", + " self.content = content\n self.retryable = False\n", + ), + ( + "field-to-property-same-type", + "models/page.py", + "class Page:\n total: int\n", + "class Page:\n @property\n def total(self) -> int:\n return 0\n", + ), + ( + "staticmethod-to-classmethod", + "models/settings.py", + " @staticmethod\n def default() -> Settings:\n return Settings(name=\"\")", + " @classmethod\n def default(cls) -> Settings:\n return cls(name=\"\")", + ), + ( + "output-dataclass-field-gains-default", + "models/settings.py", + " name: str\n", + " name: str = \"\"\n", + ), + ( + "new-special-method", + "client.py", + " def __getitem__(self, key: str)", + " def __len__(self) -> int:\n return 0\n\n def __getitem__(self, key: str)", + ), +] + + +def _write(root: Path, files: dict[str, str]) -> Path: + for rel, body in files.items(): + path = root / PKG / rel + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(textwrap.dedent(body).lstrip(), encoding="utf-8") + return root + + +def _mutate(file: str, old: str | None, new: str | None) -> dict[str, str]: + files = {k: textwrap.dedent(v).lstrip() for k, v in BASELINE.items()} + if old is None: + del files[file] + return files + assert files[file].count(old) == 1, f"mutation anchor {old!r} not unique in {file}" + files[file] = files[file].replace(old, new or "") + return files + + +def _describe(root: Path) -> Any: + return api_compat.describe_in_subprocess(root, PKG) + + +@pytest.fixture(scope="module") +def baseline(tmp_path_factory: pytest.TempPathFactory) -> Any: + return _describe(_write(tmp_path_factory.mktemp("baseline"), BASELINE)) + + +def test_baseline_is_compatible_with_itself(baseline: Any, tmp_path: Path) -> None: + assert api_compat.find_breaks(baseline, _describe(_write(tmp_path, BASELINE))) == [] + + +def test_baseline_classifies_model_directions(baseline: Any) -> None: + checker = api_compat.Checker(baseline, baseline) + checker.run() + assert checker.model_directions(f"{PKG}.models.result_model:ResultModel") == { + api_compat.OUTPUT + } + assert checker.model_directions(f"{PKG}.models.request_model:RequestModel") == { + api_compat.INPUT + } + assert checker.model_directions(f"{PKG}.models.orphan:Orphan") == set() + + +@pytest.mark.parametrize( + ("file", "old", "new", "expected"), + [case[1:] for case in BREAKS], + ids=[case[0] for case in BREAKS], +) +def test_reports_break( + baseline: Any, + tmp_path: Path, + file: str, + old: str | None, + new: str | None, + expected: str, +) -> None: + current = _describe(_write(tmp_path, _mutate(file, old, new))) + breaks = api_compat.find_breaks(baseline, current) + assert any(expected in b for b in breaks), breaks + + +@pytest.mark.parametrize( + ("file", "old", "new"), + [case[1:] for case in COMPATIBLE], + ids=[case[0] for case in COMPATIBLE], +) +def test_accepts_compatible_change( + baseline: Any, tmp_path: Path, file: str, old: str, new: str +) -> None: + current = _describe(_write(tmp_path, _mutate(file, old, new))) + assert api_compat.find_breaks(baseline, current) == [] + + +# ---- CLI exit codes ------------------------------------------------------------------ + + +def test_cli_exit_codes(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: + base = _write(tmp_path / "base", BASELINE) + same = _write(tmp_path / "same", BASELINE) + broken = _write(tmp_path / "broken", _mutate("client.py", "n: int) -> int:", "n: int) -> str:")) + args = ["--package", PKG, "--baseline-dir", str(base), "--current"] + + assert api_compat.main([*args, str(same)]) == 0 + assert api_compat.main([*args, str(broken)]) == 1 + assert "Client.count: return type widened from int to str" in capsys.readouterr().out + assert api_compat.main([*args, str(tmp_path / "missing")]) == 2 + + +def test_cli_passes_with_notice_when_no_release_of_the_major( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr( + api_compat, "fetch_pypi_metadata", lambda: _metadata("11.0.0rc1") + ) + assert api_compat.main(["--baseline-major", "11"]) == 0 + assert "::notice::" in capsys.readouterr().out + assert api_compat.main(["--print-baseline-major", "11"]) == 0 + assert capsys.readouterr().out == "\n" + + +# ---- baseline resolution ------------------------------------------------------------- + + +def _metadata(*versions: str, yanked: tuple[str, ...] = ()) -> Any: + return { + "releases": { + v: [{"filename": f"x-{v}.whl", "yanked": v in yanked}] for v in versions + } + } + + +def test_latest_release_compares_numerically_and_skips_prereleases() -> None: + meta = _metadata( + "10.1.9", "10.1.10", "10.2.0.dev3", "10.2.0rc1", "11.0.0", "9.9.9", "10.0.0" + ) + assert api_compat.latest_release(meta, 10) == "10.1.10" + assert api_compat.latest_release(meta, 9) == "9.9.9" + assert api_compat.latest_release(meta, 12) is None + + +def test_latest_release_skips_yanked_and_empty_releases() -> None: + meta = _metadata("10.1.4", "10.1.5", yanked=("10.1.5",)) + meta["releases"]["10.1.6"] = [] + assert api_compat.latest_release(meta, 10) == "10.1.4" + + +def test_print_baseline_major( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + monkeypatch.setattr( + api_compat, "fetch_pypi_metadata", lambda: _metadata("10.1.9", "10.1.10") + ) + assert api_compat.main(["--print-baseline-major", "10"]) == 0 + assert capsys.readouterr().out.strip() == "10.1.10" + + +def test_describe_output_is_json_serialisable(baseline: Any) -> None: + assert json.loads(json.dumps(baseline)) == baseline + + +# ---- release gate scripts (uv, git, gh and sleep stubbed on PATH) -------------------- + +_SCRIPTS = _SCRIPT.parent + +_STUBS = { + "uv": """ + case "$*" in + *--print-baseline-major*) echo 10.1.5 ;; + *--baseline-version*) exit "${FAKE_COMPAT_RC:-1}" ;; + *"semantic-release version --print"*) echo 10.2.0 ;; + *"semantic-release version"*) + n=$(( $(cat "$FAKE_STATE/releases" 2>/dev/null || echo 0) + 1 )) + echo "$n" > "$FAKE_STATE/releases" + if [ "$n" -eq 1 ]; then echo "Upstream branch has changed"; exit 1; fi ;; + esac + """, + "git": """ + case "$1 $2" in + "rev-parse --show-toplevel") echo "$FAKE_STATE" ;; + "rev-parse HEAD"|"rev-parse --short") echo abc123 ;; + "log --format=%H") [ -z "${FAKE_GIT_LOG_FAIL:-}" ] || exit 128; echo abc123 ;; + "log -1") echo "fix: something" ;; + "merge-base "*) exit 1 ;; + esac + """, + "gh": 'printf "%s\\n" "${FAKE_APPROVED_PRS:-}"', + "sleep": "exit 0", +} + + +def _run_script(tmp_path: Path, script: str, **env: str) -> tuple[int, str]: + bin_dir = tmp_path / "bin" + bin_dir.mkdir(exist_ok=True) + for name, body in _STUBS.items(): + stub = bin_dir / name + stub.write_text("#!/usr/bin/env bash\n" + textwrap.dedent(body), encoding="utf-8") + stub.chmod(0o755) + full_env = { + **os.environ, + "PATH": f"{bin_dir}{os.pathsep}{os.environ['PATH']}", + "FAKE_STATE": str(tmp_path), + "RUNNER_TEMP": str(tmp_path), + "GITHUB_REF_NAME": "stable/10", + "GITHUB_REPOSITORY": "camunda/example", + **env, + } + proc = subprocess.run( + ["bash", str(_SCRIPTS / script), "stable/10"], + cwd=tmp_path, + env=full_env, + capture_output=True, + text=True, + check=False, + ) + return proc.returncode, proc.stdout + proc.stderr + + +def _releases(tmp_path: Path) -> int: + return int((tmp_path / "releases").read_text()) + + +@pytest.mark.parametrize(("compat_rc", "expected_rc", "releases"), [(1, 1, 1), (0, 0, 2)]) +def test_release_retry_regates_the_new_branch_tip( + tmp_path: Path, compat_rc: int, expected_rc: int, releases: int +) -> None: + # The first attempt loses a race; the retry must not release unchecked code. + rc, out = _run_script( + tmp_path, "semantic-release-with-retry.sh", FAKE_COMPAT_RC=str(compat_rc) + ) + assert (rc, _releases(tmp_path)) == (expected_rc, releases), out + + +@pytest.mark.parametrize(("git_log_fail", "expected_rc"), [("", 1), ("1", 2)]) +def test_gate_is_a_setup_error_when_commits_cannot_be_listed( + tmp_path: Path, git_log_fail: str, expected_rc: int +) -> None: + rc, out = _run_script(tmp_path, "api-compat-gate.sh", FAKE_GIT_LOG_FAIL=git_log_fail) + assert rc == expected_rc, out + + +@pytest.mark.parametrize("compat_rc", [0, 1, 2]) +@pytest.mark.parametrize("approval", ["none", "dispatch", "label"]) +def test_gate_approval_only_waives_breaks( + tmp_path: Path, compat_rc: int, approval: str +) -> None: + rc, out = _run_script( + tmp_path, + "api-compat-gate.sh", + FAKE_COMPAT_RC=str(compat_rc), + DISPATCH_APPROVED="true" if approval == "dispatch" else "false", + FAKE_APPROVED_PRS="#123" if approval == "label" else "", + ) + expected_rc = 0 if compat_rc == 1 and approval != "none" else compat_rc + assert rc == expected_rc, out From 47322ed71bb801a0e801bfcd7442d1a35433de0b Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Tue, 17 Nov 2026 15:00:43 +1300 Subject: [PATCH 2/8] chore: retain only stable/9 contributor instructions The cherry-pick carried the main-only AGENTS.md despite the target having no such file. Remove it from the port; the source guard guidance is already in the existing Copilot instructions. Relates to #465; backports #466. --- AGENTS.md | 399 ------------------------------------------------------ 1 file changed, 399 deletions(-) delete mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 5a88fa8ed..000000000 --- a/AGENTS.md +++ /dev/null @@ -1,399 +0,0 @@ -# AGENTS.md - -> **Note:** This file delegates to a central AGENTS.md. Read and apply it before proceeding. - -**URL:** -https://raw.githubusercontent.com/camunda/.github/refs/heads/main/AGENTS.md - -Treat the central file's contents as if they were written directly in this file. -Instructions below extend those guidelines and take precedence if there is any conflict. - - -> **Note:** This file also delegates to the shared SDK AGENTS.md. Read and apply it too. - -**URL:** -https://raw.githubusercontent.com/camunda/sdk-infra/refs/heads/main/policies/AGENTS.md - -It holds the conventions shared by all Camunda SDK repos (commits, bug fixes, tests, opening issues). Precedence on conflict: this file, then the shared SDK file, then the central Camunda file. - - -## Repo-specific instructions - -### Role & boundary - -This repo is the Python SDK Generator for the Camunda 8 Orchestration Cluster API. It produces the `camunda_orchestration_sdk` package in `generated/` from an OpenAPI spec, layering custom runtime logic and post-processing hooks on top of `openapi-python-client`. - -- **Project type**: Python SDK generator + client library -- **Source language**: Python 3.10+ for the published SDK; Python 3.11+ to run the generator (see `hooks/post_gen/0030_py310_compat.py`) -- **Build/dependency**: `uv` (primary), `make` (orchestration) -- **Generation**: `openapi-python-client` with custom Python hooks -- **Runtime**: `httpx`, `pydantic`, `asyncio` -- **Testing**: `pytest`, `pytest-asyncio` - -Upstream dependencies — when they misbehave, fix them at the source rather than working around them here: - -- [`camunda-schema-bundler`](https://github.com/camunda/camunda-schema-bundler) — fetches and bundles the upstream OpenAPI spec. -- [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) — generates `generated/camunda_orchestration_sdk/`. -- [`camunda/camunda`](https://github.com/camunda/camunda) — source of the OpenAPI spec. - -**Path map:** - -| Path | Ownership and intent | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `generate.py` | Main entry point for generation. | -| `runtime/` | Hand-written runtime logic (e.g. `JobWorker`) **injected** into the generated SDK. Primary edit surface for runtime behavior. | -| `hooks/pre_gen/` | Hooks that modify the raw OpenAPI spec before generation. | -| `hooks/post_gen/` | Hooks that modify the generated Python files (flatten client, patch imports, etc.). Primary edit surface for fixing generator output. | -| `generated/` | **Generated.** Produced by `make generate`. Never hand-edit. The published `camunda_orchestration_sdk` package lives under `generated/`. | -| `stubs/` | Generated `.pyi` stub files mirroring the `generated/` package, used by downstream tooling (e.g. API changelog generation). Type-checked by ty. | -| `tests/acceptance/` | Fast unit tests that validate the generated code's structure and logic. No live Camunda required. | -| `tests/integration/` | Integration tests against a real Camunda instance. | -| `examples/readme.py` | Source of truth for `README.md` code examples — type-checked by ty. | -| `docker/` | Local Camunda compose stack for integration tests. | -| `scripts/` | Build, bundle, and sync helpers. | - -## Working on an issue - -Every change must be traceable to a tracked, claimed, in-progress work item **before implementation starts**. This keeps work legible so reviewers and other agents can direct effort and detect drift. - -- **Start from a tracked issue or PR.** Do not begin implementation without a GitHub issue (or an already-open PR) describing the work. If none exists, create one first. -- **Claim it.** Assign the issue to yourself (or the human you are working for) and move it into an in-progress state so it is visibly owned. -- **Reference it.** The branch, commits, and PR must reference the issue (e.g. `Closes #123`), so the trail from motivation to change is explicit. -- **One concern per issue/PR.** If work uncovers an unrelated problem, file a separate issue rather than expanding the current one. - -The only exceptions are trivial, self-evident fixes (typos, broken links, formatting) where the change *is* its own justification. When in doubt, open an issue. - -## Documentation (Audiences) - -This repo serves two audiences. When updating documentation, choose the correct file: - -- **End users of the published SDK**: document in `README.md` (installation, configuration, and how to use `CamundaClient` / `CamundaAsyncClient`). Keep generator internals out of the README. -- **Contributors / SDK generator maintainers**: document in `CONTRIBUTING.md` (generation workflow, hooks, runtime injection, testing, release/build details). -- **Deep technical reference**: use `docs/*.md` for focused design notes and longer-form explanations. - -If the user request is ambiguous (e.g. "update the docs"), clarify which audience they mean before editing. - -## Build instructions - -Always use `uv` for package management and running scripts. The `Makefile` provides convenient shortcuts, but understanding the underlying `uv` commands is helpful depending on the task. - -> Contributor workflows (generation, hooks, testing) are documented in `CONTRIBUTING.md`. Prefer keeping this file focused on execution conventions for the coding agent. - -### 1. Bootstrap & install - -Ensure `uv` is installed. Then install dependencies: - -```bash -uv sync -``` - -### 2. Generate SDK (critical step) - -Before running tests, type checks, or using the SDK, you **must** generate it. This script fetches the OpenAPI spec, runs the generator, and executes post-processing hooks (including copying runtime code). - -```bash -make generate -# OR manually: -# uv run generate.py --generator openapi-python-client --config generator-config-python-client.yaml --skip-tests -``` - -**Validation**: Check that `generated/camunda_orchestration_sdk` exists and contains `client.py` and `models/`. - -### 3. Run tests - -The repository has two types of tests: - -- **Acceptance tests**: fast, no live Camunda required. Run after every generation. - - ```bash - make test - # OR: uv run pytest -q tests/acceptance - ``` - -- **Integration tests**: require a local Camunda server. - - 1. Start server: `cd docker && docker compose up -d` - 2. Run tests: - - ```bash - make itest - # OR: CAMUNDA_INTEGRATION=1 uv run pytest -q tests/integration - ``` - -### 4. Linting & formatting - -```bash -make lint -# OR: uv run ruff check . -``` - -To fix auto-fixable issues: - -```bash -uv run ruff check . --fix -``` - -### 5. Type checking - -Type checking runs `ty` on the generated code and test files. - -```bash -make typecheck -# OR: uv run ty check -``` - -*Precondition*: The SDK must be generated first (`make generate`). - -**Always green**: The `main` branch must have **0 errors** from `uv run ty check`. Any change that introduces ty errors must be fixed before merging. Do not dismiss new errors as "pre-existing" without verifying by checking the baseline. If a change produces errors, fix them — do not leave regressions. - -**After pipeline changes**: When modifying hooks, runtime code, or any part of the generation pipeline, always run `make lint` and `make typecheck` and fix any errors before considering the change complete. - -### 6. Clean - -To remove generated artifacts: - -```bash -make clean -``` - -## Project layout - -### Architecture & generation flow - -1. **Spec retrieval**: `generate.py` fetches the OpenAPI spec. -2. **Pre-gen hooks**: scripts in `hooks/pre_gen/` modify the raw OpenAPI spec (e.g. renaming fields). -3. **Core generation**: `openapi-python-client` runs using `generator-config-python-client.yaml`. -4. **Post-gen hooks**: scripts in `hooks/post_gen/` modify the generated Python files (e.g. flattening client structure, patching imports). -5. **Runtime injection**: the content of `runtime/` is copied into `generated/camunda_orchestration_sdk/runtime/`. - -### Important files - -- `pyproject.toml`: project dependencies and build settings. Use `uv` to manage this. -- `Makefile`: standard workflows. -- `generator-config-python-client.yaml`: configuration for the `openapi-python-client` generator. -- `docker/docker-compose.yaml`: local development server. - -### Dependencies - -- **Runtime**: `httpx`, `attrs`, `pydantic`, `python-dateutil`, `loguru`, `python-dotenv`, `typing-extensions`. -- **Development**: `pytest`, `pytest-asyncio`, `pyyaml`, `openapi-python-client`, `jsonref`, `ruff`, `ty`, `python-semantic-release`, `sphinx`, `sphinx-markdown-builder`, `sphinx-book-theme`, `psutil`, `pydantic-settings`, `fastapi`, `uvicorn`. - -## Commit message guidelines - -We use Conventional Commits (enforced by `python-semantic-release`). - -Format: - -``` -(optional scope): - - - -BREAKING CHANGE: -``` - -Allowed type values (common set): - -``` -feat -fix -chore -docs -style -refactor -test -ci -build -perf -``` - -Rules: - -- Subject length: 5–100 characters. -- Use imperative mood ("add support", not "added support"). -- Lowercase subject (except proper nouns). No PascalCase subjects. -- Keep subject concise; body can include details, rationale, links. -- Prefix breaking changes with `BREAKING CHANGE:` either in body or footer. - -### Review-comment fix-ups - -Commits that address PR review comments must use the `chore` type (e.g. `chore:` or `chore():`), **not** the `fix` type. -`fix` commits trigger a patch release and a CHANGELOG entry — review iterations are not user-facing bug fixes. - -``` -# Correct -chore: address review comments — clarify dry-run output - -# Wrong — will pollute the CHANGELOG -fix: address review comments — clarify dry-run output -``` - -### Breaking change commits - -Breaking change markers (`BREAKING CHANGE:` in the body/footer) trigger a major version bump and a CHANGELOG entry. **Never** use these markers for intra-branch corrections on a feature branch — they pollute the release history and cause unnecessary major version increments. - -PR CI includes a breaking change guard that fails when it detects these markers. If the breaking change is intentional, add the `breaking-change-approved` label to the PR. Otherwise, rewrite the commit history to remove the markers before merging. - -### Separate generator changes from regenerated output - -When a change modifies the generator (hooks under `hooks/`, `generate.py`, generator config, `runtime/` files that get copied verbatim, build scripts) **and** that change causes `generated/*` (and/or `stubs/*`) to differ, **split the work into two commits**: - -1. **First commit** — generator change only: hook / `runtime/` / config / script / test edits. No `generated/*` or `stubs/*` changes. -2. **Second commit** — regenerated output: `generated/*` and `stubs/*` produced by running the pipeline against the first commit. - -Why: - -- **Cherry-picks stay clean.** Backports to `stable/*` only need the generator commit; the target branch's release CI regenerates `generated/*` itself. Mixing the two means the cherry-pick drags generated diff through, which conflicts with whatever generated state the target branch has. -- **Reviewers can read the change.** Generator commits are small and meaningful; regenerated commits are large and mechanical. Mixing them makes the review effectively unreadable. -- **`git blame` stays useful** for both surfaces. - -Naming convention for the second commit (mirrors the existing release-pipeline convention `chore(generation): update generated SDK [skip ci]`): - -``` -chore(generation): regenerate SDK for -``` - -If `make generate` modifies `generated/*` or `stubs/*` after the generator commit, `git add` those directories and commit them separately — do **not** amend them back into the generator commit. - -The pre-push checklist below still applies: always run `make generate && make lint && make typecheck && make test` before pushing, and commit any regenerated drift before the push. - -## Pre-push checklist - -Before pushing any commits, **always** run: - -1. `make generate` — regenerates `generated/` from the bundled spec. -2. `make lint` — ruff lint. -3. `make typecheck` — `ty` on generated + tests + stubs. -4. `make test` — acceptance tests. - -If any step modifies tracked files (e.g. `generated/*` drift, README snippet drift, stub drift), commit those changes before pushing — and respect the **separate-commits rule** above when the modified files are under `generated/` or `stubs/`. - -## Bug fix process (red/green refactor) - -Every bug fix **must** follow the red/green refactor discipline: - -1. **Red** — Write a failing test **first**, before changing any production code. The test must fail for the reason you expect (the bug). Commit this separately or demonstrate the failure clearly in the PR. -2. **Green** — Apply the minimal production fix that makes the test pass. -3. **Refactor** (optional) — Clean up while keeping all tests green. - -### Test scope: target the defect class, not just the instance - -The regression test must be broad enough to detect the **class of defect**, not only the specific instance you are fixing. For example, if the bug is "generated model X has a wrong field type", the test should verify that **all** generated models have correct field types — not just model X. - -A test that only covers the exact instance provides weaker protection: the same category of bug can recur in a different model without being caught. - -### Why - -- The failing test **proves** the test can detect this category of defect. -- The green step **proves** the fix resolves it. -- A class-scoped test acts as a durable regression guard against future reintroduction of the same pattern. - -### There are no flaky tests - -We do not acknowledge the existence of "flaky tests". A test that passes sometimes and fails other times is reporting one of two things: - -1. **A test defect** — the test contains a race, an unbounded timeout, an order-of-operation assumption, an unsynchronised readiness signal, or a dependency on wall-clock timing. Fix the test so its outcome is deterministic for the behaviour it claims to assert. -2. **A product defect** — the production code has a race, a missed signal, an unhandled error path, or a resource it leaks under load. Fix the product. - -Either way, an intermittent failure is a real defect that must be diagnosed and fixed before the change merges. Do not retry the CI job, mark the test `@pytest.mark.skip`, or describe the failure as "flaky" or "unrelated" in the PR description. "Re-run and hope" is a coping strategy, not engineering. - -When triaging an intermittent CI failure: - -- Reproduce locally if possible (loops, resource pressure, timeout reduction). If you cannot reproduce, reason from first principles about what *could* differ between local and CI (load, filesystem semantics, signal delivery latency, parallel test interaction). -- Identify the specific race or assumption. Common shapes: polling for an output line that is printed *before* the relevant handler is registered; timeouts that double as correctness assertions; tests that share a temp directory across runs; tests that depend on event ordering across two processes. -- Pick category 1 vs category 2 explicitly in the fix commit message, and explain which signal the test was previously relying on and which deterministic signal it now relies on. -- If timeouts must be generous to absorb runner load, the timeout is a safety net — not a correctness signal. State this in a comment so future maintainers don't tighten it back into a race. - -## Backporting generator fixes to `stable/*` branches - -Generator fixes are **safe and expected to backport** to maintained `stable/N` branches (currently `stable/9` and `stable/10`) by cherry-pick. The typical trigger is a Renovate bump of a generator dependency (e.g. `openapi-python-client`) that breaks generation on `stable/N`: land a generator-only fix on `main`, then cherry-pick it to `stable/N` so the bump can succeed. - -**Generator code** is everything that produces `generated/camunda_orchestration_sdk/` and `stubs/` from the bundled spec: - -- `hooks/pre_gen/` and `hooks/post_gen/` -- `runtime/` — hook `0300_copy_runtime.py` copies it into the generated package on every regen, so a `runtime/` fix propagates through the next generation -- `generate.py`, `bundle.py`, `generator-config-python-client.yaml` -- Spec bundling via `camunda-schema-bundler` (`scripts/bundle-spec.sh`) - -**Not generator fixes** (do not backport without discussion): - -- Direct edits to `generated/` or `stubs/` (regenerated; `stubs/` by hook `1400_generate_stubs.py`). -- Changes that alter the public API surface, the runtime behavior of generated clients, or published SDK semantics. - -### Why it is safe - -`.github/workflows/publish.yml` runs on every push to `stable/**`: it bundles the spec and runs `make generate-local`, regenerating `generated/` and `stubs/` before any release. A generator-only cherry-pick therefore: - -1. Does not change generated output under the branch's currently pinned generator version (verify locally — see below). -2. Lets the next Renovate bump of the generator dependency regenerate successfully. -3. Introduces no behavioral change in whatever N.x patch is published next. - -Regeneration is not publication. The workflow publishes only when semantic-release finds a release-eligible commit since the last tag (e.g. `fix:`); `chore:` commits — including routine Renovate updates and regenerated-output commits — complete without a release. Renovate vulnerability fixes are committed as `fix(deps)` and do cut a patch. If a backport needs to ship on its own, its commit type must be release-eligible. - -This relies on generator changes and regenerated output living in separate commits — see [Separate generator changes from regenerated output](#separate-generator-changes-from-regenerated-output). Cherry-pick only the generator commit. - -### Workflow - -1. Land the fix on `main` via a normal PR first. -2. For each `stable/N` that needs it: - ```bash - git fetch origin stable/N - git checkout -b backport/stable-N/ origin/stable/N - git cherry-pick - ``` -3. If the cherry-pick conflicts, resolve conservatively. If a conflict suggests the fix does not fit that branch's generator pipeline, ask before forcing it. -4. Open a PR against `stable/N` titled ` (backport # to stable/N)`, linking the original PR and stating the verification below. - -### Verification before opening the backport PR - -- The cherry-pick applied cleanly, or conflict resolution is documented. -- The change is generator-class only (no `generated/`, `stubs/`, or behavioral changes). -- Where feasible, run `make generate` on the branch with its pinned generator version and confirm `git diff --stat generated/ stubs/` is empty. - Stable branches track a moving upstream spec branch (e.g. `stable/10` builds from camunda `stable/8.10`), so a diff can come from upstream spec drift. Regenerate once without the cherry-pick to separate that from the backport's effect. -- `make lint` and `make typecheck` pass. -- For PRs to `stable/N`, `make api-compat MAJOR=N` is green (see below). - -### API compatibility guard - -PRs to `stable/**` must pass the `API compatibility` check (`scripts/api_compat.py`, tests in `tests/acceptance/test_api_compat.py`), and the Publish workflow repeats it before releasing from a stable branch. It compares `generated/` with the newest published `N.x.y` on PyPI. Only an intended break may be approved, with the `api-break-approved` label on the PR (or the `api_break_approved` input of a manual Publish run for upstream drift). Never apply the label to make a check pass; make the change backward compatible instead. See CONTRIBUTING.md for what counts as breaking. - -### Anti-patterns - -- **Don't** cherry-pick commits that touch `generated/` or `stubs/` — the target branch regenerates them. -- **Don't** bundle a generator fix with unrelated behavioral changes in one commit. Split them on `main` first so the backport is surgical. -- **Don't** backport without landing on `main` first, unless `main` cannot reproduce the issue (rare; flag it explicitly in the PR). - -## README Code Examples - -### API spec examples: prefer ergonomic helpers - -The `examples/operation-map.json` file maps OpenAPI `operationId`s to example regions that are displayed in the Camunda docs API reference (via `docusaurus-plugin-openapi-docs`). - -When an ergonomic helper method exists for a generated operation, the operation-map entry **must** point to the helper — not to the raw generated method. Users should see the best developer experience by default. - -Example: `create_deployment` maps to `DeployResources` (`deploy_resources_from_files` helper) instead of the raw `create_deployment` (requires manual multipart form construction). This preference is consistent across all three SDK repos (C#, TypeScript, Python). - -Code blocks in `README.md` are **injected from compilable example files** — do not edit them inline. - -- **Source of truth**: `examples/readme.py` (type-checked by ty during build) -- **Sync script**: `scripts/sync-readme-snippets.py` -- **CI gate**: `python3 scripts/sync-readme-snippets.py --check` (fails if README is out of sync) - -### How it works - -1. Wrap code in `examples/readme.py` with `# region RegionName` / `# endregion RegionName` tags. -2. In `README.md`, place `` immediately before the fenced code block. -3. Run `python3 scripts/sync-readme-snippets.py` to update README (or the build does it automatically). -4. Composite regions: `` concatenates regions A and B separated by a blank line. -5. Exempt blocks: use `` above a code block to exclude it from injection enforcement (e.g. pseudo-code). - -The script auto-upgrades legacy `` markers to the new descriptive format. - -### Adding or updating a README example - -1. Add/edit the region-tagged code in `examples/readme.py`. -2. Add/verify the `` marker in `README.md`. -3. Run `python3 scripts/sync-readme-snippets.py` to sync. -4. Run `uv run ty check` to confirm the example type-checks. - -**Never edit a snippet-marked code block directly in README.md** — it will be overwritten on the next sync. From 84edc2db03f18e61861b80a11ac8a12d25581d37 Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Tue, 17 Nov 2026 15:05:14 +1300 Subject: [PATCH 3/8] chore: pin API guard jobs to supported Python 3.12 The unconstrained workflow can select Python 3.15, but stable branch pydantic-core supports only through 3.14. Use the already-tested 3.12 interpreter for API and release jobs without changing the SDK runtime floor or its version matrix. A regression test for both jobs failed before the fix and now passes. Relates to #465. --- .github/workflows/api-compat.yml | 4 ++-- .github/workflows/publish.yml | 4 ++-- tests/acceptance/test_api_compat.py | 13 +++++++++++++ 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/.github/workflows/api-compat.yml b/.github/workflows/api-compat.yml index e94d69496..eb2d1b62c 100644 --- a/.github/workflows/api-compat.yml +++ b/.github/workflows/api-compat.yml @@ -27,7 +27,7 @@ jobs: api-compat: name: API compatibility env: - UV_PYTHON: ">=3.11" + UV_PYTHON: "3.12" runs-on: ubuntu-latest timeout-minutes: 15 steps: @@ -39,7 +39,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version-file: "pyproject.toml" + python-version: "3.12" # Both the baseline wheel and generated/ are imported to read their API, so the # SDK's runtime dependencies must be installed. diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 3aee85d5e..fe2858b7c 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -220,7 +220,7 @@ jobs: release: env: - UV_PYTHON: ">=3.11" + UV_PYTHON: "3.12" needs: generate runs-on: ubuntu-latest permissions: @@ -265,7 +265,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version-file: "pyproject.toml" + python-version: "3.12" - name: Install dependencies run: uv sync --all-extras --dev --group ci diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py index a9cf40726..87eb2744f 100644 --- a/tests/acceptance/test_api_compat.py +++ b/tests/acceptance/test_api_compat.py @@ -984,3 +984,16 @@ def test_gate_approval_only_waives_breaks( ) expected_rc = 0 if compat_rc == 1 and approval != "none" else compat_rc assert rc == expected_rc, out + + +@pytest.mark.parametrize( + ("workflow", "job_name"), [("api-compat.yml", "api-compat"), ("publish.yml", "release")] +) +def test_guard_jobs_use_supported_tool_python(workflow: str, job_name: str) -> None: + import yaml + + path = _SCRIPTS.parent / ".github" / "workflows" / workflow + job = yaml.safe_load(path.read_text())["jobs"][job_name] + assert job["env"]["UV_PYTHON"] == "3.12" + setup = next(step for step in job["steps"] if "setup-python@" in step.get("uses", "")) + assert setup["with"]["python-version"] == "3.12" From 5730a1fc8d3740e879d09ad1cd09d6ba5ae12da9 Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Wed, 18 Nov 2026 13:05:27 +1300 Subject: [PATCH 4/8] chore: catch five more API breaks the compatibility checker missed Review of the stable/10 and stable/9 backports (#467, #468) found breaks the checker reported as compatible. Each now has a regression that fails on the previous commit: - A package without __all__ re-exports what it imports from the SDK; removing `from .client import Client` broke `from pkg import Client` unnoticed. Packages now record their SDK imports; a plain module's imports stay incidental. - A subclass reassigning an inherited attribute in __init__ kept the base class's inferred type, so `int` -> `int | None` went unseen. The subclass's inference now replaces an inherited one, but never a declared annotation. - `f(*args, label="")` -> `f(label="", *args)` makes `f("x", label="y")` bind label twice. - An annotated attribute becoming a plain class value, and the reverse, skipped the type comparison. stable/10's generated SDK is still compatible with 10.1.5 under the new checks, as it was before. --- scripts/api_compat.py | 31 +++++++++++++++++--- tests/acceptance/test_api_compat.py | 45 +++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 4 deletions(-) diff --git a/scripts/api_compat.py b/scripts/api_compat.py index 3482547c6..6df799756 100644 --- a/scripts/api_compat.py +++ b/scripts/api_compat.py @@ -208,7 +208,8 @@ def _is_private_module(name: str) -> bool: def _defined_names(module: types.ModuleType) -> list[str]: - """Names bound at module level by the module's own code (not imports).""" + """Names bound at module level by the module's own code, plus, for a package, the SDK + names it imports (its re-exports). A plain module's imports are incidental.""" explicit = getattr(module, "__all__", None) if explicit is not None: return [str(n) for n in explicit] @@ -216,6 +217,8 @@ def _defined_names(module: types.ModuleType) -> list[str]: if not path or not path.endswith(".py"): return [] tree = ast.parse(Path(path).read_text(encoding="utf-8")) + is_package = hasattr(module, "__path__") + root_package = module.__name__.split(".")[0] names: list[str] = [] def visit(body: list[ast.stmt]) -> None: @@ -224,6 +227,10 @@ def visit(body: list[ast.stmt]) -> None: node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef) ): names.append(node.name) + elif isinstance(node, ast.ImportFrom) and is_package and ( + node.level > 0 or (node.module or "").split(".")[0] == root_package + ): + names.extend(a.asname or a.name for a in node.names if a.name != "*") elif isinstance(node, ast.Assign): for target in node.targets: if isinstance(target, ast.Name): @@ -508,6 +515,7 @@ def _add_class(self, cls: type) -> None: ) attributes: dict[str, Json] = {} + annotated: set[str] = set() members: dict[str, Json] = {} for klass in reversed(cls.__mro__): if not self._is_ours(klass): @@ -517,6 +525,7 @@ def _add_class(self, cls: type) -> None: for name, ann in inspect.get_annotations(klass).items(): if name.startswith("_"): continue + annotated.add(name) attributes[name] = self._substitute_typevars( self._type(ann, klass_ns), substitutions ) @@ -529,8 +538,11 @@ def _add_class(self, cls: type) -> None: if member is not None: members[name] = self._substitute_typevars(member, substitutions) if info["kind"] == "class": + # A subclass's own `self.x = ...` replaces an inherited inference, but never + # a declared annotation. for name, t in self._init_attributes(klass, klass_ns).items(): - attributes.setdefault(name, self._substitute_typevars(t, substitutions)) + if name not in annotated: + attributes[name] = self._substitute_typevars(t, substitutions) for name, member in list(members.items()): # A defaulted field's class-level value is the default, not the member's type. if member["kind"] == "value" and name in attributes: @@ -1095,6 +1107,17 @@ def _check_form(self, where: str, old: Json, new: Json, implemented: bool) -> No continue if kind != "POSITIONAL_ONLY" and q["kind"] == "POSITIONAL_ONLY": self._break(where, f"parameter '{name}' can no longer be passed by keyword") + # f("x", label="y") passed "x" through *args; now it binds label as well. + if ( + kind == "KEYWORD_ONLY" + and q["kind"] == "POSITIONAL_OR_KEYWORD" + and "VAR_POSITIONAL" in old_var + ): + self._break( + where, + f"parameter '{name}' now takes positional arguments previously " + f"passed through *{old_var['VAR_POSITIONAL']['name']}", + ) # Optional parameters can be passed positionally too. if kind in ("POSITIONAL_ONLY", "POSITIONAL_OR_KEYWORD"): if q["kind"] == "KEYWORD_ONLY": @@ -1195,7 +1218,7 @@ def _check_class(self, key: str) -> None: self._break(f"{where}.{name}", "attribute removed") elif replacement["kind"] == "method": self._break(f"{where}.{name}", "changed from attribute to method") - elif replacement["kind"] == "property": + elif replacement["kind"] in ("property", "value"): new_t = replacement["type"] if new_t is None: continue @@ -1222,7 +1245,7 @@ def _check_class(self, key: str) -> None: self._break(member, f"{old_m['kind']} removed") elif old_m["kind"] == "method": self._break(member, "changed from method to attribute") - elif old_m["kind"] == "property" and self.widened_output( + elif old_m["kind"] in ("property", "value") and self.widened_output( old_m["type"], new_t ): self._break( diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py index 87eb2744f..c6739644c 100644 --- a/tests/acceptance/test_api_compat.py +++ b/tests/acceptance/test_api_compat.py @@ -165,6 +165,14 @@ def __init__(self, status_code: int, content: bytes) -> None: self.status_code = status_code self.content = content + class NotFoundError(ApiError): + def __init__(self, status_code: int, content: bytes, retry: bool = False) -> None: + super().__init__(status_code, content) + self.status_code: int = status_code + + def tag(*labels: str, label: str = "") -> None: + pass + class Box(Generic[T]): def get(self) -> T: raise NotImplementedError @@ -291,6 +299,43 @@ def helper(x: str) -> str: '"RequestModel")', "acfix.models:ResultModel: class removed", ), + ( + # A package without __all__ still re-exports what it imports from the SDK. + "re-export-removed-without-all", + "__init__.py", + "from .client import Client\n", + "", + "acfix:Client: class removed", + ), + ( + "subclass-reassigned-attribute-widened", + "client.py", + "self.status_code: int = status_code", + "self.status_code: int | None = status_code", + "acfix.client:NotFoundError.status_code: type widened", + ), + ( + # f("x", label="y") now binds label twice. + "keyword-only-takes-args-position", + "client.py", + 'def tag(*labels: str, label: str = "")', + 'def tag(label: str = "", *labels: str)', + "acfix.client:tag: parameter 'label' now takes positional arguments", + ), + ( + "annotated-attribute-to-class-value", + "models/page.py", + " total: int\n", + " total = None\n", + "acfix.models.page:Page.total: type widened", + ), + ( + "class-value-to-annotated-attribute", + "client.py", + " MAX = 10\n", + " MAX: int | None = None\n", + "acfix.client:Limits.MAX: type widened", + ), ( "function-removed", "client.py", From 54e2155bf2ae81fcfcc0f0a362652e717a229560 Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Wed, 18 Nov 2026 13:10:51 +1300 Subject: [PATCH 5/8] ci: scope api-compat approvals to the changes they cover Ports the policy fixed in the Rust SDK (camunda/orchestration-cluster- api-rust#170). PR check: every PR to stable/N was compared with the last published N.x release. Once an approved breaking PR merged, its breaks stayed in that comparison and failed every later PR until the next release. A PR is now compared with its base commit, both sides regenerated from their own checked-in bundled spec, so it answers only for its own changes. It still passes when the major has no release yet. Release gate: a labelled PR merged anywhere, `main` included, approved every break in the release, including any pushed after it. The search (scripts/api-break-approvals.sh, shared with the Rust SDK) now counts only PRs merged into the release branch since the baseline. An approval covers the API as of that PR's merge: when the newest approved merge is not HEAD, the gate regenerates that commit and blocks any break added since. Tests run the gate against a real git repo with the checker, generator and approval search stubbed; disabling the post-approval comparison fails four of them. --- .github/workflows/api-compat.yml | 45 +++++-- CONTRIBUTING.md | 6 +- scripts/api-break-approvals.sh | 30 +++++ scripts/api-compat-gate.sh | 51 +++++--- tests/acceptance/test_api_compat.py | 192 +++++++++++++++++++++++++++- 5 files changed, 291 insertions(+), 33 deletions(-) create mode 100755 scripts/api-break-approvals.sh diff --git a/.github/workflows/api-compat.yml b/.github/workflows/api-compat.yml index eb2d1b62c..c300b93cb 100644 --- a/.github/workflows/api-compat.yml +++ b/.github/workflows/api-compat.yml @@ -1,10 +1,11 @@ name: API compatibility -# Blocks PRs to stable branches whose public Python API would break customer code written -# against the last release published from that branch (see scripts/api_compat.py). When a -# break is intended (e.g. a bug fix that must change the API), apply the +# Blocks PRs to stable branches that change the public Python API in a way that breaks +# customer code (see scripts/api_compat.py). A PR is compared with its base branch, so it +# answers only for its own changes: an approved break already merged does not fail every +# later PR. When a break is intended (e.g. a bug fix that must change the API), apply the # `api-break-approved` label: the check still runs and lists the breaks, but passes. The -# Publish workflow repeats the check on the code it is about to release. +# Publish workflow compares the code it is about to release with the last release. on: pull_request: @@ -33,6 +34,13 @@ jobs: steps: - uses: actions/checkout@v6 + - name: Check out the base branch + uses: actions/checkout@v6 + with: + ref: ${{ github.event.pull_request.base.sha }} + path: .api-compat-base + persist-credentials: false + - name: Install uv uses: astral-sh/setup-uv@v7 @@ -46,25 +54,36 @@ jobs: - name: Install dependencies run: uv sync --all-extras --dev - # Regenerate from the checked-in bundled spec, so a generator change is checked even - # when its regenerated output was not committed. Upstream spec drift is left to the - # release gate, which checks what Publish actually generates. + # Regenerate both sides from their checked-in bundled specs, so a generator change is + # checked even when its regenerated output was not committed. Upstream spec drift is + # left to the release gate, which checks what Publish actually generates. - name: Generate SDK run: | - uv run generate.py --generator openapi-python-client --config generator-config-python-client.yaml --skip-tests --bundled-spec external-spec/bundled/rest-api.bundle.json - uv run ruff format generated/ - uv run ruff check generated/ --fix + # stable/9 has no `make generate-only`; generate inside each checkout. + for root in . .api-compat-base; do + ( + cd "$root" + uv run generate.py --generator openapi-python-client --config generator-config-python-client.yaml --skip-tests --bundled-spec external-spec/bundled/rest-api.bundle.json + uv run ruff format generated/ + uv run ruff check generated/ --fix + ) + done - name: Check API compatibility env: - # stable/: compared with the newest published N.x.y. A branch with no N.x - # release yet (just cut from main) has nothing to compare with and passes. + # stable/ with no N.x release yet (just cut from main) has no published API + # to protect and passes. MAJOR: ${{ github.base_ref }} APPROVED: ${{ contains(github.event.pull_request.labels.*.name, 'api-break-approved') }} run: | set -uo pipefail + released=$(uv run python scripts/api_compat.py --print-baseline-major "${MAJOR#stable/}") || exit 2 + if [ -z "$released" ]; then + echo "::notice::No ${MAJOR#stable/}.x release published yet; nothing to protect." + exit 0 + fi rc=0 - uv run python scripts/api_compat.py --baseline-major "${MAJOR#stable/}" || rc=$? + uv run python scripts/api_compat.py --baseline-dir .api-compat-base/generated || rc=$? if [ "$rc" -eq 1 ] && [ "$APPROVED" = "true" ]; then echo "::warning::Breaking API changes approved with the api-break-approved label." echo "Approved with the \`api-break-approved\` label." >> "$GITHUB_STEP_SUMMARY" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcb52f5f3..d2b062cfc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,9 +126,9 @@ make itest `stable/N` regenerates from a moving upstream spec, so a release can change the public API without anyone reviewing it. `scripts/api_compat.py` compares the API of `generated/` with the newest non-prerelease `N.x.y` on PyPI and lists every change that would break code written against it: removed modules, classes, functions, attributes or enum members; new required parameters; narrowed parameter types; and result values that became wider (for example a response field turning `str | None` or `str | Unset`). Request models may widen; response models may narrow. Exit codes: `0` compatible, `1` breaking, `2` setup error. -- The `API compatibility` check runs on every PR to `stable/**`. It regenerates from the checked-in bundled spec first. -- The Publish workflow repeats the check before releasing from `stable/**`. -- If a break is intended (e.g. a bug fix that must change the API), apply the `api-break-approved` label to the PR. The check still lists the breaks but passes, and the release gate accepts any break approved this way on a PR merged since the baseline release. For a break with no PR to label (upstream spec drift), re-run Publish manually with `api_break_approved`. +- The `API compatibility` check runs on every PR to `stable/**` and compares it with its base branch, both regenerated from their checked-in bundled specs, so a PR answers only for its own changes. +- The Publish workflow compares what it is about to release with the newest `N.x.y` on PyPI before releasing from `stable/**`. +- If a break is intended (e.g. a bug fix that must change the API), apply the `api-break-approved` label to the PR. The check still lists the breaks but passes. The release gate accepts the label only on a PR merged into the release branch since the baseline release, and only for the API as of that PR's merge: a break added afterwards needs its own approval. For a break with no PR to label (upstream spec drift), re-run Publish manually with `api_break_approved`. Run it locally with `make api-compat MAJOR=10`. diff --git a/scripts/api-break-approvals.sh b/scripts/api-break-approvals.sh new file mode 100755 index 000000000..31633936d --- /dev/null +++ b/scripts/api-break-approvals.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# Usage: api-break-approvals.sh +# +# Prints `#N ` for each PR labelled api-break-approved that was merged into +# after , newest merge first. A label on a PR merged elsewhere +# (say `main`, whose commits a backport shares) or before the baseline approves nothing here. +# Exits non-zero if a lookup fails, so the caller can tell "none" from "unknown". +set -euo pipefail + +tag="$1" +branch="$2" +shas=$(git log --format=%H "${tag}..HEAD") + +# A file, not `$(...)`: command substitution does not inherit `set -e`, so a failed lookup +# on any but the last commit would be swallowed. +approved=$(mktemp) +trap 'rm -f "$approved"' EXIT +for sha in $shas; do + gh api "repos/${GITHUB_REPOSITORY}/commits/${sha}/pulls" \ + --jq '.[] | select(.merged_at != null) | select(any(.labels[]; .name == "api-break-approved")) | "\(.number) \(.base.ref) \(.merge_commit_sha)"' \ + | while read -r number base merge_sha; do + if [ "$base" = "$branch" ] && grep -qx "$merge_sha" <<<"$shas"; then + echo "#${number} ${merge_sha}" + fi + done +done > "$approved" + +for sha in $shas; do + grep " ${sha}$" "$approved" || true +done | awk '!seen[$0]++' diff --git a/scripts/api-compat-gate.sh b/scripts/api-compat-gate.sh index 9b0c8506d..d4d6f0326 100644 --- a/scripts/api-compat-gate.sh +++ b/scripts/api-compat-gate.sh @@ -6,11 +6,14 @@ # by scripts/semantic-release-with-retry.sh after it resets to a newer branch tip, so the # commit that gets released is always the commit that was checked. # -# Approval: the api-break-approved label on any PR merged since that release, or -# DISPATCH_APPROVED=true (the api_break_approved input of a manual run). +# Approval: the api-break-approved label on a PR merged into since that release +# (scripts/api-break-approvals.sh), or DISPATCH_APPROVED=true (the api_break_approved +# input of a manual run). A label approves the API as of that PR's merge: breaks added +# after the newest approved merge need their own approval. # Needs GH_TOKEN and GITHUB_REPOSITORY. Exit codes: 0 pass, 1 blocked, 2 setup error. set -uo pipefail +here=$(dirname "$0") BRANCH="${1:?usage: api-compat-gate.sh }" major="${BRANCH#stable/}" # The newest published release of this stable major, not the nearest tag: a stable @@ -33,20 +36,36 @@ if [ "${DISPATCH_APPROVED:-false}" = "true" ]; then echo "::warning::Breaking API changes approved by the api_break_approved input of this run." exit 0 fi -shas=$(git log --format=%H "${tag}..HEAD") || { - echo "::error::cannot list the commits since ${tag}." +approved=$("$here/api-break-approvals.sh" "$tag" "$BRANCH") || { + echo "::error::cannot list the approved PRs merged since ${tag}." exit 2 } -approved="" -for sha in $shas; do - prs=$(gh api "repos/${GITHUB_REPOSITORY}/commits/${sha}/pulls" \ - --jq '.[] | select(.merged_at != null) | select(any(.labels[]; .name == "api-break-approved")) | "#\(.number)"') || exit 2 - approved="${approved} ${prs}" -done -approved=$(echo "$approved" | xargs -n1 2>/dev/null | sort -u | xargs) -if [ -n "$approved" ]; then - echo "::warning::Breaking API changes approved with the api-break-approved label on: ${approved}" - exit 0 +if [ -z "$approved" ]; then + echo "::error::Release blocked: the public API breaks compatibility with ${tag}. If intended, label the PR that made the change api-break-approved (or re-run this workflow manually with api_break_approved), then re-run." + exit 1 +fi +prs=$(cut -d' ' -f1 <<<"$approved" | xargs) +read -r latest_pr latest <<<"$approved" +if [ "$latest" != "$(git rev-parse HEAD)" ]; then + dir=$(mktemp -d) + trap 'git worktree remove --force "$dir" >/dev/null 2>&1; rm -rf "$dir"' EXIT + git worktree add -q --detach "$dir" "$latest" || exit 2 + # From that commit's own spec and generator, so only later changes show up. + ( + cd "$dir" && + uv run generate.py --generator openapi-python-client --config generator-config-python-client.yaml --skip-tests --bundled-spec external-spec/bundled/rest-api.bundle.json && + uv run ruff format generated/ && + uv run ruff check generated/ --fix + ) >/dev/null || { + echo "::error::cannot generate the SDK at ${latest}." + exit 2 + } + rc=0 + uv run python scripts/api_compat.py --baseline-dir "$dir/generated" || rc=$? + if [ "$rc" -eq 1 ]; then + echo "::error::Release blocked: breaking API changes were added after ${latest_pr} (${latest}), the newest approved PR. Label the PR that made them api-break-approved (or re-run this workflow manually with api_break_approved), then re-run." + exit 1 + fi + [ "$rc" -eq 0 ] || exit "$rc" fi -echo "::error::Release blocked: the public API breaks compatibility with ${tag}. If intended, label the PR that made the change api-break-approved (or re-run this workflow manually with api_break_approved), then re-run." -exit 1 +echo "::warning::Breaking API changes approved with the api-break-approved label on: ${prs}" diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py index c6739644c..42b44a0ae 100644 --- a/tests/acceptance/test_api_compat.py +++ b/tests/acceptance/test_api_compat.py @@ -10,6 +10,7 @@ import importlib.util import json import os +import shutil import subprocess import sys import textwrap @@ -1025,7 +1026,9 @@ def test_gate_approval_only_waives_breaks( "api-compat-gate.sh", FAKE_COMPAT_RC=str(compat_rc), DISPATCH_APPROVED="true" if approval == "dispatch" else "false", - FAKE_APPROVED_PRS="#123" if approval == "label" else "", + # What `gh api .../commits//pulls --jq ...` prints for a PR merged into the + # release branch at HEAD. + FAKE_APPROVED_PRS="123 stable/10 abc123" if approval == "label" else "", ) expected_rc = 0 if compat_rc == 1 and approval != "none" else compat_rc assert rc == expected_rc, out @@ -1042,3 +1045,190 @@ def test_guard_jobs_use_supported_tool_python(workflow: str, job_name: str) -> N assert job["env"]["UV_PYTHON"] == "3.12" setup = next(step for step in job["steps"] if "setup-python@" in step.get("uses", "")) assert setup["with"]["python-version"] == "3.12" + + +# ---- approval scope (real git; checker, generator and approval search stubbed) -------- + + +def _git(repo: Path, *args: str) -> str: + return subprocess.run( + ["git", *args], cwd=repo, check=True, capture_output=True, text=True + ).stdout.strip() + + +@pytest.fixture +def gate_repo(tmp_path: Path) -> dict[str, Any]: + """`before` tagged v10.1.5, then `first` and `second` (HEAD), with the gate beside a + fake approval search; uv answers per mode and records each --baseline-dir commit.""" + repo = tmp_path / "repo" + repo.mkdir() + _git(repo, "init", "-q") + shas = [] + for message in ("before", "first", "second"): + _git(repo, "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", message) + shas.append(_git(repo, "rev-parse", "HEAD")) + if message == "before": + _git(repo, "tag", "v10.1.5") + scripts = repo / "scripts" + scripts.mkdir() + (scripts / "api-compat-gate.sh").write_text((_SCRIPTS / "api-compat-gate.sh").read_text()) + stubs = { + scripts / "api-break-approvals.sh": 'echo "approvals $2" >> "$CALLS"\n[ -z "${APPROVALS:-}" ] || printf "%s\\n" "$APPROVALS"', + tmp_path / "bin" / "uv": """ + case "$*" in + *--print-baseline-major*) echo 10.1.5 ;; + *--baseline-version*) echo release >> "$CALLS"; exit "$RC_RELEASE" ;; + *--baseline-dir*) + while [ "$1" != --baseline-dir ]; do shift; done + echo "since $(git -C "${2%/generated}" rev-parse HEAD)" >> "$CALLS" + exit "$RC_SINCE" ;; + *generate.py*) echo "generate $PWD" >> "$CALLS" ;; + esac + """, + tmp_path / "bin" / "make": 'echo "generate $2" >> "$CALLS"', + tmp_path / "bin" / "gh": "exit 0", + } + for path, body in stubs.items(): + path.parent.mkdir(exist_ok=True) + path.write_text("#!/usr/bin/env bash\n" + textwrap.dedent(body), encoding="utf-8") + path.chmod(0o755) + return {"repo": repo, "tmp": tmp_path, "first": shas[1], "second": shas[2]} + + +def _gate(ctx: dict[str, Any], **env: str) -> tuple[int, str, list[str]]: + calls = ctx["tmp"] / "calls" + calls.write_text("") + proc = subprocess.run( + ["bash", str(ctx["repo"] / "scripts" / "api-compat-gate.sh"), "stable/10"], + cwd=ctx["repo"], + env={ + **os.environ, + "PATH": f"{ctx['tmp'] / 'bin'}{os.pathsep}{os.environ['PATH']}", + "CALLS": str(calls), + "GITHUB_REPOSITORY": "camunda/example", + "RC_RELEASE": "1", + "RC_SINCE": "0", + **env, + }, + capture_output=True, + text=True, + check=False, + ) + lines = [line for line in calls.read_text().splitlines() if not line.startswith("generate")] + return proc.returncode, proc.stdout + proc.stderr, lines + + +def test_gate_searches_approvals_on_the_release_branch(gate_repo: dict[str, Any]) -> None: + rc, out, calls = _gate(gate_repo) + assert (rc, calls) == (1, ["release", "approvals stable/10"]), out + + +def test_gate_approval_at_head_passes(gate_repo: dict[str, Any]) -> None: + rc, out, calls = _gate(gate_repo, APPROVALS=f"#7 {gate_repo['second']}") + assert (rc, calls) == (0, ["release", "approvals stable/10"]), out + + +def test_gate_approval_covers_the_api_up_to_its_merge(gate_repo: dict[str, Any]) -> None: + rc, out, calls = _gate(gate_repo, APPROVALS=f"#6 {gate_repo['first']}") + assert (rc, calls) == (0, ["release", "approvals stable/10", f"since {gate_repo['first']}"]), out + + +def test_gate_blocks_a_break_added_after_the_newest_approval(gate_repo: dict[str, Any]) -> None: + rc, out, calls = _gate(gate_repo, APPROVALS=f"#6 {gate_repo['first']}", RC_SINCE="1") + assert (rc, calls) == (1, ["release", "approvals stable/10", f"since {gate_repo['first']}"]), out + assert "added after #6" in out + + +def test_gate_comparison_error_after_approval_is_a_setup_error(gate_repo: dict[str, Any]) -> None: + assert _gate(gate_repo, APPROVALS=f"#6 {gate_repo['first']}", RC_SINCE="2")[0] == 2 + + +def test_gate_regenerates_the_approved_commit_and_removes_it(gate_repo: dict[str, Any]) -> None: + _gate(gate_repo, APPROVALS=f"#6 {gate_repo['first']}") + assert any( + line.startswith("generate ") for line in (gate_repo["tmp"] / "calls").read_text().splitlines() + ) + assert len(_git(gate_repo["repo"], "worktree", "list").splitlines()) == 1 + + +# ---- approval search (real git; gh answered from fixtures) ---------------------------- + + +@pytest.fixture +def search_repo(gate_repo: dict[str, Any]) -> dict[str, Any]: + fixtures = gate_repo["tmp"] / "pulls" + fixtures.mkdir() + (fixtures / "none.json").write_text("[]") + gh = gate_repo["tmp"] / "bin" / "gh" + gh.write_text( + '#!/usr/bin/env bash\nset -euo pipefail\nsha="${2##*/commits/}"; sha="${sha%/pulls}"\n' + 'f="$FIXTURES/$sha.json"; [ -f "$f" ] || f="$FIXTURES/none.json"\njq -r "$4" "$f"\n' + ) + return {**gate_repo, "fixtures": fixtures} + + +def _pr(number: int, base: str, merge_sha: str | None, labelled: bool = True) -> dict[str, Any]: + return { + "number": number, + "merged_at": "2026-01-01T00:00:00Z" if merge_sha else None, + "merge_commit_sha": merge_sha, + "base": {"ref": base}, + "labels": [{"name": "api-break-approved"}] if labelled else [], + } + + +def _search(ctx: dict[str, Any], **by_commit: str) -> subprocess.CompletedProcess[str]: + for sha, body in by_commit.items(): + (ctx["fixtures"] / f"{sha}.json").write_text(body) + return subprocess.run( + ["bash", str(_SCRIPTS / "api-break-approvals.sh"), "v10.1.5", "stable/10"], + cwd=ctx["repo"], + env={ + **os.environ, + "PATH": f"{ctx['tmp'] / 'bin'}{os.pathsep}{os.environ['PATH']}", + "FIXTURES": str(ctx["fixtures"]), + "GITHUB_REPOSITORY": "camunda/example", + }, + capture_output=True, + text=True, + check=False, + ) + + +@pytest.mark.skipif(not shutil.which("jq"), reason="the gh stub applies --jq with jq") +@pytest.mark.parametrize( + ("pr", "approves"), + [ + (lambda s: _pr(1, "stable/10", s["second"]), True), + (lambda s: _pr(2, "main", s["second"]), False), + (lambda s: _pr(3, "stable/10", None), False), + (lambda s: _pr(4, "stable/10", s["second"], labelled=False), False), + ], + ids=["release-line", "other-branch", "unmerged", "unlabelled"], +) +def test_approval_search_scope(search_repo: dict[str, Any], pr: Any, approves: bool) -> None: + proc = _search(search_repo, **{search_repo["second"]: json.dumps([pr(search_repo)])}) + assert proc.returncode == 0, proc.stderr + assert bool(proc.stdout.strip()) == approves, proc.stdout + + +@pytest.mark.skipif(not shutil.which("jq"), reason="the gh stub applies --jq with jq") +def test_approval_search_lists_newest_merge_first(search_repo: dict[str, Any]) -> None: + first, second = search_repo["first"], search_repo["second"] + proc = _search( + search_repo, + **{ + first: json.dumps([_pr(6, "stable/10", first)]), + second: json.dumps([_pr(7, "stable/10", second)]), + }, + ) + assert proc.stdout.splitlines() == [f"#7 {second}", f"#6 {first}"], proc.stderr + + +@pytest.mark.skipif(not shutil.which("jq"), reason="the gh stub applies --jq with jq") +@pytest.mark.parametrize("broken", ["second", "first"]) +def test_approval_search_lookup_failure_on_any_commit_is_an_error( + search_repo: dict[str, Any], broken: str +) -> None: + # The newest commit is looked up first; its failure must not be masked by later ones. + assert _search(search_repo, **{search_repo[broken]: "not json"}).returncode != 0 From 2302a15518e6ea6be254442609dc46c2cca01872 Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Wed, 18 Nov 2026 13:19:15 +1300 Subject: [PATCH 6/8] chore: type the approval-search test parameters Strict pyright on stable/9 (its pre-push hook) rejects untyped lambdas in the parametrized approval-search test and an unannotated list. Plain typed parameters keep the test identical across branches. --- tests/acceptance/test_api_compat.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py index 42b44a0ae..db4680119 100644 --- a/tests/acceptance/test_api_compat.py +++ b/tests/acceptance/test_api_compat.py @@ -1063,7 +1063,7 @@ def gate_repo(tmp_path: Path) -> dict[str, Any]: repo = tmp_path / "repo" repo.mkdir() _git(repo, "init", "-q") - shas = [] + shas: list[str] = [] for message in ("before", "first", "second"): _git(repo, "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "--allow-empty", "-m", message) shas.append(_git(repo, "rev-parse", "HEAD")) @@ -1197,17 +1197,21 @@ def _search(ctx: dict[str, Any], **by_commit: str) -> subprocess.CompletedProces @pytest.mark.skipif(not shutil.which("jq"), reason="the gh stub applies --jq with jq") @pytest.mark.parametrize( - ("pr", "approves"), + ("base", "merged", "labelled", "approves"), [ - (lambda s: _pr(1, "stable/10", s["second"]), True), - (lambda s: _pr(2, "main", s["second"]), False), - (lambda s: _pr(3, "stable/10", None), False), - (lambda s: _pr(4, "stable/10", s["second"], labelled=False), False), + ("stable/10", True, True, True), + ("main", True, True, False), + ("stable/10", False, True, False), + ("stable/10", True, False, False), ], ids=["release-line", "other-branch", "unmerged", "unlabelled"], ) -def test_approval_search_scope(search_repo: dict[str, Any], pr: Any, approves: bool) -> None: - proc = _search(search_repo, **{search_repo["second"]: json.dumps([pr(search_repo)])}) +def test_approval_search_scope( + search_repo: dict[str, Any], base: str, merged: bool, labelled: bool, approves: bool +) -> None: + head = search_repo["second"] + pr = _pr(1, base, head if merged else None, labelled=labelled) + proc = _search(search_repo, **{head: json.dumps([pr])}) assert proc.returncode == 0, proc.stderr assert bool(proc.stdout.strip()) == approves, proc.stdout From edccb17933365cb01565daeef45aa362f5733a0b Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Wed, 18 Nov 2026 14:15:30 +1300 Subject: [PATCH 7/8] chore: preserve Python export and call semantics in API checks --- scripts/api_compat.py | 33 +++++++++++++++++-------- tests/acceptance/test_api_compat.py | 38 ++++++++++++++++++++++++++++- 2 files changed, 60 insertions(+), 11 deletions(-) diff --git a/scripts/api_compat.py b/scripts/api_compat.py index 6df799756..27a6ad5fb 100644 --- a/scripts/api_compat.py +++ b/scripts/api_compat.py @@ -30,6 +30,7 @@ import enum import hashlib import importlib +import importlib.util import inspect import json import os @@ -230,7 +231,17 @@ def visit(body: list[ast.stmt]) -> None: elif isinstance(node, ast.ImportFrom) and is_package and ( node.level > 0 or (node.module or "").split(".")[0] == root_package ): - names.extend(a.asname or a.name for a in node.names if a.name != "*") + for alias in node.names: + if alias.name != "*": + names.append(alias.asname or alias.name) + continue + target = importlib.util.resolve_name( + "." * node.level + (node.module or ""), module.__name__ + ) + source = sys.modules.get(target) + if source is not None: + exported = getattr(source, "__all__", vars(source)) + names.extend(name for name in exported if name in vars(module)) elif isinstance(node, ast.Assign): for target in node.targets: if isinstance(target, ast.Name): @@ -522,7 +533,8 @@ def _add_class(self, cls: type) -> None: continue klass_ns = self._ns(vars(sys.modules[klass.__module__])) substitutions = specializations.get(klass, {}) - for name, ann in inspect.get_annotations(klass).items(): + declarations = inspect.get_annotations(klass) + for name, ann in declarations.items(): if name.startswith("_"): continue annotated.add(name) @@ -538,11 +550,11 @@ def _add_class(self, cls: type) -> None: if member is not None: members[name] = self._substitute_typevars(member, substitutions) if info["kind"] == "class": - # A subclass's own `self.x = ...` replaces an inherited inference, but never - # a declared annotation. - for name, t in self._init_attributes(klass, klass_ns).items(): - if name not in annotated: + for name, (t, explicit) in self._init_attributes(klass, klass_ns).items(): + if name not in declarations and (explicit or name not in annotated): attributes[name] = self._substitute_typevars(t, substitutions) + if explicit: + annotated.add(name) for name, member in list(members.items()): # A defaulted field's class-level value is the default, not the member's type. if member["kind"] == "value" and name in attributes: @@ -552,7 +564,7 @@ def _add_class(self, cls: type) -> None: info["attributes"] = attributes info["methods"] = members - def _init_attributes(self, klass: type, ns: dict[str, Any]) -> dict[str, Json]: + def _init_attributes(self, klass: type, ns: dict[str, Any]) -> dict[str, tuple[Json, bool]]: """Public ``self.x = ...`` assignments in ``__init__``, read from its source.""" init = vars(klass).get("__init__") if not inspect.isfunction(init): @@ -566,7 +578,7 @@ def _init_attributes(self, klass: type, ns: dict[str, Any]) -> dict[str, Json]: if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)) or not fn.args.args: return {} self_name = fn.args.args[0].arg - found: dict[str, Json] = {} + found: dict[str, tuple[Json, bool]] = {} for node in ast.walk(fn): if isinstance(node, ast.AnnAssign): targets, ann, value = [node.target], node.annotation, node.value @@ -588,7 +600,8 @@ def _init_attributes(self, klass: type, ns: dict[str, Any]) -> dict[str, Json]: t = self._type(params[value.id].annotation, {**ns, **init.__globals__}) else: t = {"k": "any"} - found.setdefault(target.attr, t) + if ann is not None or target.attr not in found: + found[target.attr] = (t, ann is not None) return found def _describe_member(self, raw: Any, ns: dict[str, Any]) -> Json | None: @@ -639,7 +652,7 @@ def _signature( if skip_first: params = list(sig.parameters.values())[1:] sig = sig.replace(parameters=params) - is_async = inspect.iscoroutinefunction(func) or inspect.isasyncgenfunction(func) + is_async = inspect.iscoroutinefunction(func) described = self._signature_from(sig, ns, is_async=is_async) if not with_overloads: return described diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py index db4680119..171d19f4c 100644 --- a/tests/acceptance/test_api_compat.py +++ b/tests/acceptance/test_api_compat.py @@ -37,6 +37,7 @@ "__init__.py": """ from .client import Client from .models import Color, RequestModel, ResultModel + from .models.page import * """, "types.py": """ class Unset: @@ -146,7 +147,7 @@ class ResultModel: "client.py": """ from __future__ import annotations - from collections.abc import Sequence + from collections.abc import AsyncIterator, Sequence from typing import Generic, TypeVar, overload from .models.request_model import RequestModel @@ -184,6 +185,13 @@ class GenericBase(Generic[T]): class IntBox(GenericBase[int]): pass + class NamedBox(IntBox): + def __init__(self) -> None: + self.value: int = 0 + + async def stream() -> AsyncIterator[int]: + yield 1 + class Limits: MAX = 10 @@ -279,6 +287,27 @@ def helper(x: str) -> str: # (id, file, old text, new text, expected substring of one reported break) BREAKS: list[tuple[str, str, str | None, str | None, str]] = [ + ( + "wildcard-reexport-removed", + "__init__.py", + "from .models.page import *", + "if False:\n from .models.page import *", + "acfix:Page: class removed", + ), + ( + "inherited-declaration-overridden", + "client.py", + "self.value: int = 0", + "self.value: int | None = None", + "NamedBox.value: type widened", + ), + ( + "async-generator-becomes-coroutine", + "client.py", + "yield 1", + "raise NotImplementedError", + "stream: changed between sync and async", + ), ( "module-removed", "models/orphan.py", @@ -827,6 +856,13 @@ def test_baseline_is_compatible_with_itself(baseline: Any, tmp_path: Path) -> No assert api_compat.find_breaks(baseline, _describe(_write(tmp_path, BASELINE))) == [] +def test_equivalent_wildcard_reexport(baseline: Any, tmp_path: Path) -> None: + files = _mutate( + "__init__.py", "from .models import Color, RequestModel, ResultModel", "from .models import *" + ) + assert api_compat.find_breaks(baseline, _describe(_write(tmp_path, files))) == [] + + def test_baseline_classifies_model_directions(baseline: Any) -> None: checker = api_compat.Checker(baseline, baseline) checker.run() From 214484a08e26af259b683df1ac97e9ed18c38670 Mon Sep 17 00:00:00 2001 From: Emily Oram Date: Wed, 18 Nov 2026 14:45:45 +1300 Subject: [PATCH 8/8] chore: check protocol variadics and exempt unused model fields --- scripts/api_compat.py | 12 ++++++++--- tests/acceptance/test_api_compat.py | 32 ++++++++++++++++++++++++++++- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/scripts/api_compat.py b/scripts/api_compat.py index 27a6ad5fb..fde3fff2e 100644 --- a/scripts/api_compat.py +++ b/scripts/api_compat.py @@ -1143,7 +1143,12 @@ def _check_form(self, where: str, old: Json, new: Json, implemented: bool) -> No self._break(where, f"parameter '{name}' is now required") self._check_param_type(where, name, p, q, implemented) for q in new["params"]: - if q["name"] in old_names or q["kind"] in ("VAR_POSITIONAL", "VAR_KEYWORD"): + if q["kind"] in ("VAR_POSITIONAL", "VAR_KEYWORD"): + if implemented and q["kind"] not in old_var: + star = "*" if q["kind"] == "VAR_POSITIONAL" else "**" + self._break(where, f"implementations must accept new parameter '{star}{q['name']}'") + continue + if q["name"] in old_names: continue if not q["has_default"]: self._break(where, f"new required parameter '{q['name']}'") @@ -1191,6 +1196,9 @@ def _check_form(self, where: str, old: Json, new: Json, implemented: bool) -> No def _check_class(self, key: str) -> None: old = self.old["classes"][key] new = self.new["classes"][key] + dirs = self.model_directions(key) if self._data_class(key) else {INPUT, OUTPUT} + if not dirs: + return where = key if old["kind"] != new["kind"] and "protocol" in (old["kind"], new["kind"]): self._break(where, f"changed from {old['kind']} to {new['kind']}") @@ -1215,8 +1223,6 @@ def _check_class(self, key: str) -> None: self._check_typeddict(where, old, new) return - data = old["kind"] in ("attrs", "dataclass", "pydantic") - dirs = self.model_directions(key) if data else {INPUT, OUTPUT} protocol = old["kind"] == "protocol" if "init" in old and "init" in new and INPUT in dirs and not protocol: diff --git a/tests/acceptance/test_api_compat.py b/tests/acceptance/test_api_compat.py index 171d19f4c..b38a61f1c 100644 --- a/tests/acceptance/test_api_compat.py +++ b/tests/acceptance/test_api_compat.py @@ -100,11 +100,16 @@ def default() -> Settings: "models/orphan.py": """ from __future__ import annotations + from typing import TypedDict + import attrs @attrs.define class Orphan: value: str + + class OrphanDict(TypedDict): + key: int """, "models/request_model.py": """ from __future__ import annotations @@ -148,7 +153,7 @@ class ResultModel: from __future__ import annotations from collections.abc import AsyncIterator, Sequence - from typing import Generic, TypeVar, overload + from typing import Generic, Protocol, TypeVar, overload from .models.request_model import RequestModel from .models.result_model import ResultModel @@ -162,6 +167,9 @@ class ResultModel: DEFAULT_LIMIT = 10 + class AuthProvider(Protocol): + def headers(self) -> dict[str, str]: ... + class ApiError(Exception): def __init__(self, status_code: int, content: bytes) -> None: self.status_code = status_code @@ -287,6 +295,20 @@ def helper(x: str) -> str: # (id, file, old text, new text, expected substring of one reported break) BREAKS: list[tuple[str, str, str | None, str | None, str]] = [ + ( + "protocol-adds-varargs", + "client.py", + "def headers(self)", + "def headers(self, *args: str)", + "AuthProvider.headers: implementations must accept new parameter '*args'", + ), + ( + "protocol-adds-varkwargs", + "client.py", + "def headers(self)", + "def headers(self, **kwargs: str)", + "AuthProvider.headers: implementations must accept new parameter '**kwargs'", + ), ( "wildcard-reexport-removed", "__init__.py", @@ -706,6 +728,14 @@ def helper(x: str) -> str: ] COMPATIBLE: list[tuple[str, str, str, str]] = [ + ("orphan-field-removed", "models/orphan.py", "value: str", "pass"), + ("orphan-key-removed", "models/orphan.py", "key: int", "pass"), + ( + "ordinary-function-adds-variadics", + "client.py", + "def helper(x: str)", + "def helper(x: str, *args: str, **kwargs: str)", + ), ( "new-function", "client.py",