github-apiroute 0.1.0__tar.gz

github_apiroute-0.1.0/.agent/skills/apiroute-client.md

@@ -0,0 +1,194 @@
+---
+name: apiroute-client
+description: Create, set up and maintain a GitHub repository that publishes apiroute-generated Python clients for an API described by OpenAPI/Swagger specs, WSDLs or a GraphQL schema (with hand-written operations). Covers gathering the specs and documentation links, the repository layout, the apis.yaml generation config, hand-written auth base classes, the README, CI/Build/Release workflows (the Build workflow regenerates and commits changes), PyPI publishing (only if the user wants it), and ongoing maintenance.
+---
+
+# apiroute client repositories
+
+Use this skill when asked to create a client repository for an API ("make a <api>-apiroute repo", e.g. `stripe-apiroute`), or to maintain one: adding or removing an API, a spec change that broke generation, upgrading apiroute, or setting up releases.
+
+A client repository holds generated code that is never edited by hand. It is the output of [apiroute](https://github.com/dougyouch/apiroute)'s generator (`apiroute generate openapi|wsdl|graphql`), applied to specs listed in one config file, and refreshed by a scheduled workflow. The one exception is GraphQL: its `.graphql` operation files are hand-written inputs, kept in `operations/` (see below). A worked example is **[ebay-apiroute](https://github.com/dougyouch/ebay-apiroute)**; the examples below use it, but nothing here is specific to eBay. Copy its files and adapt them rather than writing new ones; the sections below say what to change.
+
+## 1. Gather before creating anything
+
+Ask the user (an AskUserQuestion-style prompt with choices works well), and confirm what you find:
+
+1. **Names:**
+   - the repository (`<api>-apiroute`)
+   - the PyPI name (the same)
+   - the Python package (`<api>_apiroute`)
+   - the GitHub owner
+2. **Which APIs to cover.** Offer "everything with a published spec" as the default; lazy loading makes unused APIs free.
+3. **Will it be released to PyPI?** Always ask; never assume. If yes, the repo gets `release.yml` and the user must create a PyPI pending publisher (step 6). If no, skip `release.yml`, and the README says to install from GitHub (`pip install git+https://github.com/<owner>/<repo>`).
+4. **Public or private.** Releasing to PyPI implies public.
+5. **Auth model:** OAuth bearer tokens, API keys, Basic auth, request signing, SOAP header credentials, or extra per-call parameters. This decides the auth base class (step 4).
+6. **For a GraphQL API, which operations.** A GraphQL schema doesn't say what to fetch, so the repository holds the queries and mutations to generate. Ask what the user needs (or start from the API's documented examples), and write them as `.graphql` files. Also ask whether introspecting the schema needs a token, and the name of the environment variable that holds it.
+
+Then find each API's machine-readable description and its documentation page:
+
+- **Download every spec and check its content, not the HTTP status.** Some sites (eBay's, for example) answer unknown URLs with a normal 200 page. A spec must parse as JSON/YAML with an `openapi` or `swagger` key, or as XML with `definitions` (WSDL).
+- **For GraphQL, introspect the endpoint** with `apiroute fetch-schema <endpoint> -o /tmp/x.graphql -H "Authorization: Bearer $TOKEN"`. Some APIs also publish the schema as a file (GitHub's `schema.docs.graphql`), which works without a token.
+- **Treat documentation links the same way.** Some sites serve an error page to `curl` but the real page to browsers. A page's `<title>` that says "Error" or "Not Found" means "try another URL or a web search", not "it doesn't exist". Every API in the README table needs a working documentation link.
+- **Probe URL patterns** when a site publishes many specs (eBay, as an example: `/api-docs/master/<group>/<api>/openapi/3/<group>_<api>_<version>_oas3.json`), but keep only the ones whose content validates.
+- **Generate each spec into a scratch directory** before committing to it: `apiroute generate openapi <url> -o /tmp/x --models`, or for GraphQL `apiroute generate graphql /tmp/x.graphql --operations <dir> -o /tmp/x --models`, which reports every operation that doesn't match the schema as `file:line:column`. Note any spec the generator can't handle, and either fix apiroute or leave that API out, telling the user which.
+
+## 2. Repository layout
+
+```text
+<repo>/
+  apis.yaml                     the source of truth: one entry per API (hand-written)
+  specs/                        committed copies of the specs (written by --fetch; SDL for GraphQL)
+  operations/<api>/             GraphQL operations, one folder per API (hand-written)
+  scripts/generate.py           fetch specs, run apiroute generate, write the README table
+  src/<package>/
+    __init__.py                 package docstring (hand-written)
+    auth.py                     auth base classes the generated clients extend (hand-written)
+    <group>/__init__.py         written by scripts/generate.py
+    <group>/<api>/              generated by apiroute (never edited)
+  tests/                        config checks, auth behaviour, one call per protocol
+  .github/workflows/            ci.yml, build.yml, release.yml (if releasing)
+  release-please-config.json    .release-please-manifest.json   (if releasing)
+  AGENT.md  CLAUDE.md           agent guidance; CLAUDE.md imports AGENT.md with "@AGENT.md"
+  .agent/skills/apiroute-client.md   this skill (copy it into the new repository)
+  README.md  CHANGELOG.md  LICENSE  pyproject.toml  uv.lock
+```
+
+`apis.yaml`, one entry per API (shown with ebay-apiroute's values as an example):
+
+```yaml
+package: ebay_apiroute
+apis:
+  - name: sell_inventory            # unique; also the spec file name in specs/
+    title: Inventory API            # shown in the README table
+    format: openapi                 # openapi (covers Swagger 2.0) or wsdl
+    spec: https://.../sell_inventory_v1_oas3.json
+    docs: https://developer.ebay.com/api-docs/sell/static/api-inventory.html
+    module: sell.inventory          # -> src/ebay_apiroute/sell/inventory/
+    client: SellInventoryApi
+    base_class: ebay_apiroute.auth:EbayAuth   # optional; owns auth
+    models: true                    # optional, default true: the typed .models layer
+  - name: github                    # a GraphQL API
+    title: GitHub GraphQL API
+    format: graphql
+    spec: https://api.github.com/graphql      # introspected by --fetch into specs/github.graphql
+    spec_headers:                   # optional, for introspection; values name environment variables
+      Authorization: "Bearer ${GITHUB_TOKEN}"
+    operations: operations/github   # hand-written .graphql files; subfolders become sections
+    endpoint: https://api.github.com/graphql  # --endpoint: base_url and path
+    scalars:                        # optional --scalar mappings
+      DateTime: datetime:datetime
+    persisted_queries: false        # optional: --persisted-queries, for servers with APQ
+    docs: https://docs.github.com/en/graphql
+    module: github
+    client: GitHubApi
+    base_class: github_apiroute.auth:GitHubAuth
+```
+
+`scripts/generate.py`: copy an existing one, such as [ebay-apiroute's](https://github.com/dougyouch/ebay-apiroute/blob/main/scripts/generate.py). It does the following:
+
+- `--fetch` downloads each spec, validates it, and re-indents JSON (keeping key order) so diffs stay readable. For `format: graphql` it runs `apiroute fetch-schema <spec> -o specs/<name>.graphql`, expanding `${VAR}` in `spec_headers` from the environment and passing each as `-H`. Never write a token to a file.
+- It runs `apiroute generate <format> specs/<name> -o src/<package>/<module> --client-name ... --models --base-class ...` for each API, adding `--operations`, `--endpoint`, `--scalar` and `--persisted-queries` for GraphQL.
+- It writes the group packages' `__init__.py`, marked "Generated by scripts/generate.py".
+- It rewrites the README table between `<!-- apis:start -->` and `<!-- apis:end -->`.
+- `--only NAME` limits the run to the named APIs.
+
+ebay-apiroute's script also has an eBay-specific `_write_trading_version`. Drop it, or adapt it if your auth class must read a value from a spec.
+
+`pyproject.toml`:
+- Depend on `apiroute>=<current>` (add `apiroute[soap]` when any API is a WSDL; GraphQL clients need nothing extra at run time) and `pydantic>=2.6` (generated models fail on pydantic 2.1–2.5). Put `apiroute[codegen]`, `pytest` and `ruff` in the `dev` dependency group.
+- Set ruff's `line-length = 100` and `extend-exclude = ["specs"]`.
+- Keep `specs/` out of the sdist.
+
+## 3. Generate, lint, import
+
+```bash
+uv sync
+uv run python scripts/generate.py --fetch
+uv run ruff check . && uv run ruff format --check .   # generated code passes both
+```
+
+Then import every module and build every model, on the lowest and highest supported Python versions. A Python 3.10 import catches annotation problems that 3.14's deferred annotations hide. The checks live in `tests/test_apis_config.py`:
+
+- every `apis.yaml` entry has a spec file, a documentation link, an importable client and the configured base class
+- every route compiles
+
+## 4. Auth base class (hand-written, in `auth.py`)
+
+Every generated root client extends the `base_class` from `apis.yaml`, and apiroute then generates no auth of its own. Write the class once, by subclassing `apiroute.Client`. Sections inherit its `headers` and `query_params`, and they use its hooks.
+
+| Need | How |
+| --- | --- |
+| Bearer token | `headers = {"Authorization": lambda self: f"Bearer {self.current_token()}" if self._token else None}`; accept a string or a function returning one (for refreshing OAuth helpers) |
+| API key in a header or query | an entry in `headers` or `query_params` reading an attribute |
+| Request signing | `on_request(self, request)` returning `dataclasses.replace(request, headers=...)` |
+| Per-call parameters | `on_request`, with `request.operation` (the spec's operationId or WSDL operation name) |
+| Retrying safe operations | apiroute 2 only retries `GET`, `HEAD` and `OPTIONS` after a read timeout. Override `idempotent(self, request)` to return `True` for operations that are safe to repeat, by `request.operation` (a SOAP API's `Get*` calls) or `request.method`, and `None` for the rest. Set `idempotency_key = "Idempotency-Key"` instead for APIs that honor that header |
+| SOAP header credentials | `soap_header(self, operation) -> dict`, in the same xmltodict shape as bodies |
+| Sandbox or region hosts | an `__init__` flag that sets `kwargs["base_url"]` from `type(self)._config.base_url` |
+
+Test each behaviour in `tests/` with `apiroute.testing`: inside `with mock_transport() as mock:`, call the client and assert on `mock.last`, which records the operation, the header or parameter on the wire, the sandbox host, and a SOAP header if any. Match responses by operation with `mock.on(operation=...)`.
+
+## 5. README (generate it as part of setup)
+
+It must have:
+- a one-paragraph description with CI and Build badges
+- installation instructions (PyPI, or from GitHub when not releasing)
+- usage per protocol: dict and typed calls, `.aio`, auth arguments and sandbox
+- **links to the API's documentation and its auth or token guide**
+- the generated API table, with a docs link per API
+- **how the repository stays up to date:**
+  - the Build schedule
+  - the `specs/` snapshot and `git log -p specs/`
+  - apiroute as the generator
+  - the commit types and the releases they produce
+  - what CI checks
+- development commands, and how to add an API
+
+Use an existing client repository's README (ebay-apiroute's, for example) as the template.
+
+## 6. Workflows
+
+Copy them from an existing client repository (ebay-apiroute, for example) and change the names, the PyPI project and the schedule.
+
+- **`ci.yml`** runs on pushes to main, pull requests and `workflow_call`:
+  - Lint: `ruff check` and `ruff format --check`.
+  - `generated-is-current`: runs `scripts/generate.py` without `--fetch` and fails on any `git status` difference. This catches hand edits, and specs out of step with the code.
+  - Tests on every supported Python version.
+- **`build.yml`** runs on a schedule and `workflow_dispatch`:
+  1. `uv lock --upgrade-package apiroute`, then `uv sync`.
+  2. `scripts/generate.py --fetch`.
+  3. Lint and test.
+  4. If `git status` shows changes, commit and push to main:
+     - `feat(specs): update clients from <API>'s latest specs` when `specs/` changed (a minor release)
+     - otherwise `fix(codegen): regenerate clients with apiroute <version>` (a patch)
+
+  It needs `permissions: contents: write`. If `main` is protected, give the workflow a bypass or have it open a PR instead. A GraphQL API whose introspection needs a token gets it from a repository secret, exposed to the fetch step as the environment variable `spec_headers` names.
+- **`release.yml`**, only if the user said yes to PyPI, releases hands-off, which is the default for client repositories. It runs release-please, then tests the release PR's branch (CI through `workflow_call` with a `ref` input), cancels CI runs still waiting on the release PR (GitHub holds the bot's PR runs for approval, and once the merge deletes the branch they'd fail with "a workflow file issue"), merges it with `gh pr merge --rebase`, and runs release-please again in the same job to tag it and create the GitHub release. Then it publishes with `uv publish --trusted-publishing always` in the `pypi` environment. All of this happens in one run, because a merge made with `GITHUB_TOKEN` doesn't trigger the push event that would otherwise release it. A release PR merged by hand still releases through `push`. Publishing skips a version that's already on PyPI, and attaches the distributions to the GitHub release. Besides `push` and `workflow_dispatch`, trigger it on `workflow_run` of Build: commits pushed with `GITHUB_TOKEN` don't trigger other workflows. Copy ebay-apiroute's `release.yml` and `ci.yml`.
+
+Each repository needs these GitHub and PyPI settings:
+
+- Delete branches on merge: `gh repo edit --delete-branch-on-merge`.
+- Let Actions open pull requests, for release-please: `gh api -X PUT repos/<owner>/<repo>/actions/permissions/workflow -f default_workflow_permissions=read -F can_approve_pull_request_reviews=true`.
+- If releasing:
+  - The user creates a PyPI **pending publisher**: the project name, the repository owner and name, workflow `release.yml`, environment `pypi`.
+  - Before the first release, set the version (e.g. `0.1.0`) in `pyproject.toml` and `.release-please-manifest.json`.
+  - Tag `v<version>`, create its GitHub release, and run Release manually to publish. After that, releases are automatic: release-please's PRs are tested, merged and published by `release.yml`.
+
+## 7. Maintenance
+
+- **Routine:** none. Build commits changes, and release-please's PR is tested, merged and published on its own. The tests are the gate, so keep them meaningful: config checks, auth behaviour, and one call per protocol.
+- **A spec change breaks generation:** Build fails before committing, and the last good code stays on main. Reproduce with `scripts/generate.py --fetch --only <name>`, then fix apiroute (preferred) or the auth class. Never patch `specs/` or generated files by hand.
+- **A GraphQL schema change breaks an operation:** Build fails listing each broken operation as `file:line:column`. The operations are yours: update them in `operations/<api>/` (a renamed or removed field), regenerate and commit (`feat!:` if a released method's result changed shape). Deprecation warnings in the Build log say what to move off before the API removes it.
+- **Add a GraphQL operation:** add a `.graphql` file (or a query to one), `generate.py --only <name>`, test and commit (`feat:`).
+- **Lists:** for a Relay connection the user wants in full, put `@paginate` on the connection field and give the operation a `$after: String` variable. The generated method then iterates every item across pages. Leave it off where one page (with `totalCount`) is what's wanted, because adding it later changes the method's return type.
+- **Add an API:** add an `apis.yaml` entry, verifying its spec and docs as in step 1, then `generate.py --fetch --only <name>`, then test and commit (`feat:`).
+- **Remove an API:** delete its entry, its spec and its folder, then regenerate and commit (`feat!:` if it was released).
+- **apiroute adds a feature you need:** release apiroute, raise the minimum in `pyproject.toml`, `uv lock`, regenerate, commit.
+
+## 8. Before handing over
+
+- [ ] Every API has a working spec and a working docs link (checked by content, not by status).
+- [ ] `ruff check`, `ruff format --check`, the tests, and a Python 3.10 import of every module all pass.
+- [ ] CI, Build (run it once by hand) and, if releasing, Release are green.
+- [ ] Branch auto-delete is on and Actions can open PRs. If releasing, the pending publisher exists, or the user knows to create it.
+- [ ] README, AGENT.md, CLAUDE.md (importing AGENT.md) and this skill are in the repository.

github_apiroute-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,57 @@
+name: Build
+
+# Keeps the clients current: fetches GitHub's latest REST description and GraphQL schema, upgrades apiroute, regenerates,
+# checks, and commits any difference to main. A changed spec is committed as feat(specs)
+# (a minor release); output that changed only because apiroute did, as fix(codegen) (a patch).
+on:
+  schedule:
+    - cron: "41 7 * * 1" # Mondays 07:41 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write # commit regenerated clients
+
+concurrency:
+  group: build
+  cancel-in-progress: false
+
+jobs:
+  regenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - name: Use the newest apiroute
+        run: uv lock --upgrade-package apiroute
+      - run: uv sync
+      - name: Fetch the latest specs and regenerate
+        env:
+          GITHUB_TOKEN: ${{ github.token }} # introspecting the GraphQL schema needs a token
+        run: uv run python scripts/generate.py --fetch
+      - name: Check
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pytest
+      - name: Commit changes
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "Specs and generated clients are unchanged."
+            exit 0
+          fi
+          specs=$(git status --porcelain -- specs | awk '{print $2}' | xargs -r -n1 basename | sed 's/\..*$//' | sort -u | paste -sd ' ' -)
+          if [ -n "$specs" ]; then
+            subject="feat(specs): update clients from GitHub's latest API specs"
+            body="Changed specs: $specs"
+          else
+            version=$(uv run python -c "import importlib.metadata as m; print(m.version('apiroute'))")
+            subject="fix(codegen): regenerate clients with apiroute $version"
+            body="No spec changed; the generated code did, with the newer apiroute."
+          fi
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git add -A
+          git commit -m "$subject" -m "$body"
+          git push

github_apiroute-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # run by release.yml before publishing, and on the release PR before merging it
+    inputs:
+      ref:
+        description: "The branch, tag or commit to test (default: the triggering commit)"
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  # The committed code must be exactly what the committed specs generate: nothing in src/
+  # is edited by hand, and specs/ and src/ never drift apart.
+  generated-is-current:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+      - run: uv sync
+      - run: uv run python scripts/generate.py
+      - name: Check for differences
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git status --short
+            echo "::error::Generated code differs from the committed specs. Run 'uv run python scripts/generate.py' and commit the result."
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest

github_apiroute-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,166 @@
+name: Release
+
+# Releases are hands-off. release-please keeps a release PR open that bumps the version in
+# pyproject.toml and CHANGELOG.md from conventional commits; this workflow tests that PR,
+# merges it, has release-please tag it and create the GitHub release, and publishes to PyPI
+# (trusted publishing, environment "pypi"). All in one run: a merge made with GITHUB_TOKEN
+# doesn't trigger the push event that would otherwise release it.
+# It also runs after Build, whose commits (pushed by a workflow) don't trigger push events.
+# A release PR merged by hand still releases through the push event.
+# Run it manually (workflow_dispatch) to retry publishing the current version.
+on:
+  push:
+    branches: [main]
+  workflow_run:
+    workflows: [Build]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # release commits, tags and GitHub releases
+      issues: write # release labels
+      pull-requests: write # the release PR
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      pr_branch: ${{ steps.release.outputs.pr && fromJSON(steps.release.outputs.pr).headBranchName || '' }}
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # uv.lock records this package's own version, which release-please doesn't update,
+  # so regenerate the lockfile on the release PR branch.
+  sync-lockfile:
+    needs: release-please
+    if: needs.release-please.outputs.pr_branch != ''
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # push to the release PR branch
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release-please.outputs.pr_branch }}
+      - uses: astral-sh/setup-uv@v6
+      - run: uv lock
+      - name: Push updated uv.lock
+        run: |
+          git diff --quiet uv.lock && exit 0
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git commit -m 'build(deps): sync uv.lock version' uv.lock
+          git push
+
+  # The release PR is opened with GITHUB_TOKEN, which doesn't trigger CI on it, so test its
+  # branch here (after the lockfile sync), then merge it.
+  release-pr-ci:
+    needs: [release-please, sync-lockfile]
+    if: needs.release-please.outputs.pr_branch != ''
+    uses: ./.github/workflows/ci.yml
+    with:
+      ref: ${{ needs.release-please.outputs.pr_branch }}
+
+  merge-release-pr:
+    needs: [release-please, release-pr-ci]
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # cancel the release PR's waiting CI runs
+      contents: write # merge, tags and the GitHub release
+      issues: write # release labels
+      pull-requests: write # merge the release PR
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      # GitHub holds CI on the bot's release PR for approval. Those runs never start, and once
+      # the merge deletes the branch they fail with "a workflow file issue". release-pr-ci has
+      # tested the branch, so cancel them rather than leave red runs behind.
+      - name: Cancel CI runs waiting on the release PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ needs.release-please.outputs.pr_branch }}
+        run: |
+          waiting=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow ci.yml --branch "$BRANCH" \
+            --event pull_request --limit 20 --json databaseId,status \
+            --jq '.[] | select(.status != "completed") | .databaseId')
+          for run in $waiting; do
+            gh run cancel "$run" --repo "$GITHUB_REPOSITORY" || echo "run $run already finished"
+          done
+      - name: Merge the release PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh pr merge "${{ needs.release-please.outputs.pr_branch }}" --rebase --repo "$GITHUB_REPOSITORY"
+      # The merge doesn't trigger a push event, so tag and create the release now
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # A release PR merged by hand: run the suite before anything is published.
+  ci:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true' || github.event_name == 'workflow_dispatch'
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: [release-please, ci, merge-release-pr]
+    # after a hand merge (ci), an automatic one (merge-release-pr), or a manual retry; never
+    # when something it needs failed
+    if: >-
+      always() && !failure() && !cancelled() &&
+      (needs.release-please.outputs.release_created == 'true' ||
+       needs.merge-release-pr.outputs.release_created == 'true' ||
+       github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/github-apiroute/
+    permissions:
+      contents: write # attach the distributions to the GitHub release
+      id-token: write # PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # the new tag on release; the dispatched commit on a manual retry
+          ref: ${{ needs.merge-release-pr.outputs.tag_name || needs.release-please.outputs.tag_name || github.sha }}
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Read version
+        run: |
+          version=$(uv version --short)
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+          echo "TAG=v$version" >> "$GITHUB_ENV"
+
+      - name: Build
+        run: uv build
+
+      # A version that's already on PyPI is skipped, so a manual retry can finish a
+      # partially published release.
+      - name: Publish to PyPI
+        run: |
+          if curl -sf "https://pypi.org/pypi/github-apiroute/$VERSION/json" > /dev/null; then
+            echo "github-apiroute $VERSION is already published"
+          else
+            uv publish --trusted-publishing always
+          fi
+
+      - name: Attach distributions to GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release upload "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --clobber

github_apiroute-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.mypy_cache/

github_apiroute-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

github_apiroute-0.1.0/AGENT.md

@@ -0,0 +1,54 @@
+# AGENT.md
+
+Guidance for AI coding agents (and people) working in this repository.
+
+## What this repository is
+
+`github-apiroute` publishes Python clients for GitHub's REST and GraphQL APIs. The clients are **generated** by [apiroute](https://github.com/dougyouch/apiroute):
+- the REST client from GitHub's published OpenAPI description;
+- the GraphQL client from GitHub's introspected schema plus the operations in `operations/graphql/`.
+
+They're kept current by the weekly Build workflow, and released to PyPI as `github-apiroute`.
+
+## Layout
+
+| Path | What it is | Edit by hand? |
+| --- | --- | --- |
+| `apis.yaml` | Both APIs: spec URL, docs URL, module, client class, auth base class, and for GraphQL the endpoint, operations folder and scalar mappings | **yes**: this is the source of truth |
+| `operations/graphql/` | The GraphQL operations (queries, mutations, shared fragments), one method each | **yes** |
+| `specs/` | Committed copies of the REST description and GraphQL schema, written by `scripts/generate.py --fetch` | no (fetch them) |
+| `scripts/generate.py` | Fetches specs (introspecting the GraphQL schema with `GITHUB_TOKEN`), runs `apiroute generate` per API, writes the README table | yes |
+| `src/github_apiroute/auth.py` | `GitHubAuth` (token, API version header, retry safety), which both generated clients extend | **yes** |
+| `src/github_apiroute/__init__.py` | Package docstring | yes |
+| `src/github_apiroute/rest/`, `graphql/` | Generated clients (every file starts with `# Generated by apiroute`) | **never** |
+| `tests/` | Config checks, auth, GraphQL operations | yes |
+| `.github/workflows/` | `ci.yml`, `build.yml` (regenerate and commit), `release.yml` (release-please, auto-merge and PyPI) | yes |
+| `.agent/skills/apiroute-client.md` | Skill for creating and maintaining repos like this one | yes |
+
+## Rules
+
+- **Never edit generated code.** CI regenerates from `specs/` and fails on any difference. To change generated output:
+  - Edit `apis.yaml`, `operations/graphql/` or `auth.py` and regenerate.
+  - If the generator itself is wrong, fix apiroute; the Build workflow picks up its next release.
+- **Regenerate after any change** to `apis.yaml`, the operations or the generate script: `uv run python scripts/generate.py`. Add `--fetch` to download the latest specs first (it needs `GITHUB_TOKEN`, e.g. `GITHUB_TOKEN="$(gh auth token)"`). Commit the specs, operations and generated code together.
+- **Never write a token to a file or print it.** Pass it through the environment only.
+- **Credentials belong in `auth.py`.** Every generated root client extends `GitHubAuth`; spec-declared security schemes aren't generated.
+- **Use conventional commits.** release-please derives versions from them:
+  - `feat:` is a minor release
+  - `fix:` is a patch
+  - `chore:`, `docs:`, `test:` and `ci:` produce no release
+- **Before committing:** `uv run ruff check .`, `uv run ruff format --check .` and `uv run pytest`.
+
+## Common tasks
+
+- **Add a GraphQL operation:**
+  1. Write it in a `.graphql` file under `operations/graphql/`. The folder is the section (`repos/` → `gh.repos`); top-level files go on the root client. Reuse the fragments in `fragments.graphql`.
+  2. For a connection, select `pageInfo { hasNextPage endCursor }`, take an `$after: String` variable, and mark the field `@paginate`.
+  3. Run `scripts/generate.py --only graphql`. The generator validates the operation against `specs/graphql.graphql`.
+  4. Add a test in `tests/test_graphql.py` using `MockTransport`. Don't run mutations against the real API.
+- **A spec change broke generation:** the Build workflow fails before committing anything. Reproduce with `GITHUB_TOKEN="$(gh auth token)" scripts/generate.py --fetch`, then fix the operation (a field GitHub removed or renamed), apiroute or `auth.py`. Patching `specs/` by hand would be overwritten by the next fetch.
+- **Release:** nothing to do. `release.yml` tests the release PR that release-please keeps open, merges it, tags it and publishes to PyPI (trusted publishing, the `pypi` environment), whenever releasable commits land, including Build's. Merging the release PR by hand still works. Running Release manually retries publishing the current version.
+
+## Skill
+
+`.agent/skills/apiroute-client.md` describes how to create, set up and maintain a client repository like this one for any API with OpenAPI/Swagger specs, WSDLs or GraphQL schemas. Read it before restructuring this repo or creating a sibling.

github_apiroute-0.1.0/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+This repository's guidance for coding agents lives in AGENT.md, imported here:
+
+@AGENT.md
+
+Skills for this repository are in `.agent/skills/`. Read `.agent/skills/apiroute-client.md` before creating or restructuring an apiroute client repository.

github_apiroute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dougyouch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.