scalar-sdk 0.3.2__tar.gz

scalar_sdk-0.3.2/.claude/skills/scalar-api-python-sdk/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: scalar-api-python-sdk
+description: "Python SDK for Scalar API. Use when writing Python code that calls Scalar API with the scalar-sdk package: installing it, constructing and authenticating the client, and calling API operations."
+---
+
+# Scalar API Python SDK
+
+Generated Python client for Scalar API, published as `scalar-sdk`. Use the generated client instead of hand-writing HTTP requests.
+
+## Install
+
+```sh
+pip install scalar-sdk
+```
+
+## Client setup and authentication
+
+```python
+import os
+
+from scalar_sdk import Scalar
+
+client = Scalar(
+    bearer_auth=os.environ.get("BEARER_AUTH"),
+)
+```
+
+Provide credentials using the options below. Environment variables are read automatically when the target runtime supports them:
+
+- `bearer_auth` (env: `BEARER_AUTH`) — Credential for the BearerAuth scheme.
+
+## Calling operations
+
+```python
+import os
+
+from scalar_sdk import Scalar
+
+client = Scalar(
+    bearer_auth=os.environ.get("BEARER_AUTH"),
+)
+
+registry = client.registry.list_all_api_documents()
+print(registry)
+```
+
+Method names, parameter shapes, and response types are generated from the API description — do not guess them. Look up the exact call signature in [api.md](../../../api.md) before writing a call.
+
+## Error handling
+
+Non-success responses throw generated API errors. Error objects expose status, headers, response body, and request metadata where the target runtime supports it.
+
+```python
+from scalar_sdk import APIStatusError
+
+try:
+    registry = client.registry.list_all_api_documents()
+except APIStatusError as err:
+    print(err.status_code, err.message)
+    raise
+```
+
+## Requirements
+
+- Python 3.8 or newer
+
+## Reference files
+
+- [README.md](../../../README.md) — full feature tour: client options, request options, retries and timeouts, logging.
+- [api.md](../../../api.md) — complete catalogue of every operation with request and response types.

scalar_sdk-0.3.2/.github/workflows/release-please.yml

@@ -0,0 +1,93 @@
+name: Release Please
+
+on:
+  # Fires when a human merges the platform-managed release PR into main
+  # (the PR's base, so its diff shows the full pending release). Regenerations and
+  # custom-code pushes only touch scalar-next and never run this workflow.
+  push:
+    branches:
+      - main
+  # Manual fallback only; nothing in the automated chain depends on dispatch.
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  # Required to update the merged release PR's autorelease labels after tagging.
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      # Consumed by the publish job's checkout: without this mapping the checkout ref would be
+      # empty and the publish would build the triggering branch head instead of the released
+      # tag's exact commit.
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          target-branch: main
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+          # Release PRs are opened and updated by the Scalar platform with its own
+          # credential (so their CI runs without manual approval); this workflow only
+          # cuts the tag + GitHub Release once a release PR is merged.
+          skip-github-pull-request: true
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        with:
+          fetch-depth: 0
+      # Merging the release PR into main is itself the promotion, but the
+      # version bump and changelog must also land back on scalar-next, or the next
+      # release PR would propose this release again. A real merge (never a plain
+      # commit push) so a squash- or rebase-merged release PR syncs just as well; the
+      # non-conventional message keeps the sync commit out of future changelogs. Plain
+      # (non-force) push on purpose: losing a race against a concurrent regeneration
+      # push fails loudly here, and the platform's next sync re-converges.
+      - name: Sync release back to scalar-next
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin scalar-next
+          git checkout -B scalar-next origin/scalar-next
+          git merge --no-edit -m "Sync release ${{ steps.release.outputs.tag_name }} back to scalar-next" "${{ steps.release.outputs.sha }}"
+          git push origin scalar-next
+  publish:
+    needs: release-please
+    # `!cancelled()` keeps publishing even when the back-sync to the integration branch
+    # failed: a raced integration branch must not block the release from reaching its
+    # registry.
+    if: ${{ !cancelled() && needs.release-please.outputs.release_created == 'true' }}
+    runs-on: ubuntu-latest
+    # Job-level permissions replace the workflow's release-cutting grants with the publish
+    # floor. OIDC trusted publishing verifies this run's claims, which name this workflow
+    # file — register release-please.yml as the trusted publisher on the registry.
+    permissions:
+      contents: read
+      id-token: write
+      packages: write
+    env:
+      VERSIONING_POLICY: manual
+    steps:
+      # Publishing runs inline — a top-level job of this same run — rather than dispatching
+      # sdk-release.yml: workflow_dispatch resolves the target workflow on the repository's
+      # default branch only, so a dispatch would 404 whenever the release line is any other
+      # branch, while OIDC trusted publishing accepts this job because it stays top-level
+      # (never a reusable-workflow call). The release-please job cut the tag earlier in this
+      # run; checking it out publishes exactly the released commit, not the branch head that
+      # triggered the workflow.
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name }}
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          skip-existing: true

scalar_sdk-0.3.2/.github/workflows/release-title-edit.yml

@@ -0,0 +1,117 @@
+name: Release PR Version
+
+on:
+  # `edited` is not one of the default pull_request types, but it is the point of this
+  # workflow: retitling the release PR is how a maintainer picks an exact version. The
+  # other types keep the consistency check attached to the PR as it evolves.
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
+
+# Read-only by default; only the job that pushes the Release-As commit widens this.
+permissions:
+  contents: read
+
+jobs:
+  version-consistency:
+    # Also the check name the release PR's footer tells maintainers to wait for.
+    name: Release PR version
+    # Only the platform's release PR carries a version in its title; every other pull request
+    # skips this job, which GitHub reports as neutral. The release may be presented from
+    # scalar-next itself or from the release-please branch rendered off it, so both heads
+    # count as the release PR.
+    if: >-
+      ${{ github.event.pull_request.base.ref == 'main'
+      && (github.event.pull_request.head.ref == 'scalar-next'
+      || startsWith(github.event.pull_request.head.ref, 'release-please--branches--scalar-next--')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          # The version committed on the PR head is what merging would actually release.
+          ref: ${{ github.event.pull_request.head.sha }}
+      # Fails while the title version and the committed version disagree — the window between
+      # a maintainer's retitle and the platform re-rendering the PR from it. Without this a
+      # merge in that window would tag a release whose own files self-report the old version,
+      # and a title release-please cannot parse would silently cut no release at all.
+      - name: Compare the title version with the committed version
+        env:
+          # The title is human input, so it is bound through the environment (never
+          # interpolated into the script) and matched against a strict semver pattern
+          # before it is read.
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          pattern='^release: ((0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?)$'
+          if [[ ! "$PR_TITLE" =~ $pattern ]]; then
+            echo "::error::Release PR title must be \"release: X.Y.Z\" with a full semver version, got: $PR_TITLE"
+            exit 1
+          fi
+          title_version="${BASH_REMATCH[1]}"
+          manifest_version="$(jq -r '.["."]' .release-please-manifest.json)"
+          if [[ "$title_version" != "$manifest_version" ]]; then
+            echo "::error::Release PR title says $title_version but the pull request is versioned $manifest_version. Wait for the release PR to be re-rendered at $title_version before merging."
+            exit 1
+          fi
+          echo "Release PR title and committed version agree on $title_version."
+
+  apply-title-version:
+    name: Apply edited release version
+    # A human retitle of the open release PR is bridged into the canonical explicit-version
+    # mechanism (a Release-As commit on scalar-next, which the platform re-renders the
+    # release PR from). `changes.title` is only set when the title itself changed, and bot
+    # senders are ignored so the platform's own retitles cannot bounce back into another
+    # commit.
+    if: >-
+      ${{ github.event.action == 'edited'
+      && github.event.changes.title != null
+      && github.event.sender.type != 'Bot'
+      && github.event.pull_request.state == 'open'
+      && github.event.pull_request.base.ref == 'main'
+      && (github.event.pull_request.head.ref == 'scalar-next'
+      || startsWith(github.event.pull_request.head.ref, 'release-please--branches--scalar-next--')) }}
+    # One bridge run at a time per pull request, newest retitle wins. Two retitles in quick
+    # succession (a version typo corrected seconds later) would otherwise start two runs that
+    # both read the version committed on the PR head, both get past the no-op guard, and both
+    # push — and since each fetches scalar-next immediately before committing, the second
+    # push fast-forwards instead of failing. release-please honours the newest Release-As
+    # footer, so the release would land on whichever run happened to push last, not on the
+    # title the maintainer actually left behind.
+    concurrency:
+      group: release-title-edit-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          # The PR head, so the version the pull request currently carries can be read before
+          # deciding whether anything needs to change.
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Push a Release-As commit for the edited version
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -euo pipefail
+          pattern='^release: ((0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?)$'
+          if [[ ! "$PR_TITLE" =~ $pattern ]]; then
+            echo "::error::Release PR title must be \"release: X.Y.Z\" with a full semver version, got: $PR_TITLE"
+            exit 1
+          fi
+          # Only ever a validated semver from here on, so it is safe in a commit message.
+          version="${BASH_REMATCH[1]}"
+          manifest_version="$(jq -r '.["."]' .release-please-manifest.json)"
+          # The re-rendered PR is retitled to the version it now carries; stopping here keeps
+          # that from producing an endless chain of Release-As commits.
+          if [[ "$version" == "$manifest_version" ]]; then
+            echo "This release PR already carries $version; nothing to do."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin scalar-next
+          git checkout -B scalar-next origin/scalar-next
+          git commit --allow-empty -m "chore: release $version" -m "Release-As: $version"
+          # Plain (non-force) push: losing a race against a regeneration push fails loudly
+          # rather than discarding it, and the retitle can simply be repeated.
+          git push origin scalar-next
+          echo "Pushed Release-As: $version to scalar-next. The release PR will be re-rendered at that version."

scalar_sdk-0.3.2/.github/workflows/sdk-ci.yml

@@ -0,0 +1,16 @@
+name: Python SDK CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build

scalar_sdk-0.3.2/.github/workflows/sdk-release.yml

@@ -0,0 +1,34 @@
+name: Python SDK Release
+
+on:
+  # Manual re-publish only: the automated publish for each release runs as the `publish` job
+  # inside release-please.yml, in the same run that cuts the tag (dispatching a workflow here
+  # instead would resolve it on the repository's default branch only, which breaks releasing
+  # from any other release line). Dispatch this workflow at an existing release tag to re-run
+  # a failed or skipped publish. A dispatched run is top-level, so OIDC trusted-publisher
+  # claims name this file; register it as an additional trusted publisher only when manual
+  # re-publishes are used. Never add a workflow_call trigger here — registries reject
+  # publishes from called (reusable) workflows.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+  packages: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      VERSIONING_POLICY: manual
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          skip-existing: true

scalar_sdk-0.3.2/.gitignore

@@ -0,0 +1,10 @@
+# Generated by Scalar SDK Generator.
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

scalar_sdk-0.3.2/.release-please-manifest.json

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