From c61c5359535089027389e9dd7956f86a6a39e66c Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Wed, 11 Nov 2026 18:49:42 -0800 Subject: [PATCH 1/9] Publish versioned guides with optional repository tools Keep release documentation tied to its source and locked dependencies. Retain validated snapshots and route readers through a shared catalog. Provide an explicitly installed developer CLI and main-owned publisher with isolated rendering, release forwarding, and dependency-aware CI. Signed-off-by: Trent Nelson --- .gitattributes | 1 + .github/workflows/ci.yml | 65 +- .github/workflows/docs.yml | 108 +++- .github/workflows/release-docs.yml | 38 ++ CONTRIBUTING.md | 15 +- MANIFEST.in | 1 + dev/.gitignore | 3 + dev/AGENTS.md | 31 + dev/README.md | 181 ++++++ dev/pyproject.toml | 64 ++ dev/src/cuphoton_dev/__init__.py | 5 + dev/src/cuphoton_dev/__main__.py | 7 + dev/src/cuphoton_dev/archive.py | 274 +++++++++ dev/src/cuphoton_dev/assets/selector.css | 24 + dev/src/cuphoton_dev/assets/selector.js | 48 ++ dev/src/cuphoton_dev/build.py | 225 +++++++ dev/src/cuphoton_dev/cli.py | 165 +++++ dev/src/cuphoton_dev/github.py | 215 +++++++ dev/src/cuphoton_dev/publisher.py | 245 ++++++++ dev/src/cuphoton_dev/renderers.py | 91 +++ dev/src/cuphoton_dev/transforms.py | 439 ++++++++++++++ dev/tests/test_archive.py | 128 ++++ dev/tests/test_ci_changes.py | 123 ++++ dev/tests/test_cli.py | 208 +++++++ dev/tests/test_packaging.py | 230 +++++++ dev/tests/test_prepare.py | 190 ++++++ dev/tests/test_publisher.py | 213 +++++++ dev/tests/test_release_hook.py | 68 +++ dev/tests/test_renderers.py | 85 +++ dev/tests/test_transforms.py | 258 ++++++++ dev/uv.lock | 741 +++++++++++++++++++++++ scripts/ci/dev_changes.py | 175 ++++++ src/cuphoton/core/cli/app.py | 37 +- src/cuphoton/core/cli/component.py | 8 +- 34 files changed, 4678 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/release-docs.yml create mode 100644 dev/.gitignore create mode 100644 dev/AGENTS.md create mode 100644 dev/README.md create mode 100644 dev/pyproject.toml create mode 100644 dev/src/cuphoton_dev/__init__.py create mode 100644 dev/src/cuphoton_dev/__main__.py create mode 100644 dev/src/cuphoton_dev/archive.py create mode 100644 dev/src/cuphoton_dev/assets/selector.css create mode 100644 dev/src/cuphoton_dev/assets/selector.js create mode 100644 dev/src/cuphoton_dev/build.py create mode 100644 dev/src/cuphoton_dev/cli.py create mode 100644 dev/src/cuphoton_dev/github.py create mode 100644 dev/src/cuphoton_dev/publisher.py create mode 100644 dev/src/cuphoton_dev/renderers.py create mode 100644 dev/src/cuphoton_dev/transforms.py create mode 100644 dev/tests/test_archive.py create mode 100644 dev/tests/test_ci_changes.py create mode 100644 dev/tests/test_cli.py create mode 100644 dev/tests/test_packaging.py create mode 100644 dev/tests/test_prepare.py create mode 100644 dev/tests/test_publisher.py create mode 100644 dev/tests/test_release_hook.py create mode 100644 dev/tests/test_renderers.py create mode 100644 dev/tests/test_transforms.py create mode 100644 dev/uv.lock create mode 100644 scripts/ci/dev_changes.py diff --git a/.gitattributes b/.gitattributes index f770236a..9b4730c3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -20,6 +20,7 @@ # Publish the user guide separately from release source archives. /docs/guide export-ignore +/dev export-ignore # Large or review-heavy artifacts should not enter the clean repo accidentally. *.fits filter=lfs diff=lfs merge=lfs -text diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8a26226f..6eaf0a32 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,6 +23,61 @@ env: UV_HTTP_TIMEOUT: "300" jobs: + changes: + name: classify developer dependencies + permissions: + contents: read + pull-requests: read + runs-on: ubuntu-24.04 + timeout-minutes: 5 + outputs: + dev: ${{ steps.classify.outputs.dev }} + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + persist-credentials: false + fetch-depth: 0 + - name: Compare the actual source range + id: classify + env: + GH_TOKEN: ${{ github.token }} + run: python scripts/ci/dev_changes.py + + developer-tools: + name: developer tools / CPU + needs: changes + if: needs.changes.outputs.dev == 'true' + runs-on: ubuntu-24.04 + timeout-minutes: 15 + env: + CUDA_VISIBLE_DEVICES: "" + CUPHOTON_XREP_TORCH_DEVICE: cpu + COVERAGE_FILE: ${{ github.workspace }}/dev/.coverage + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6 + with: + version: "0.12.1" + enable-cache: true + - run: uv sync --project dev --locked --python 3.12 + - run: uv run --project dev --locked ruff check dev scripts/ci + - run: uv run --project dev --locked ruff format --check dev scripts/ci + - run: uv run --project dev --locked mypy --config-file dev/pyproject.toml dev/src/cuphoton_dev + - name: Test developer tools with separate coverage + run: | + uv run --project dev --locked coverage run --rcfile=dev/pyproject.toml \ + -m pytest -c dev/pyproject.toml dev/tests + uv run --project dev --locked coverage xml --rcfile=dev/pyproject.toml \ + -o dev/coverage.xml + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: developer-coverage-${{ github.sha }} + path: dev/coverage.xml + if-no-files-found: error + retention-days: 14 + lint: timeout-minutes: 15 name: lint @@ -546,13 +601,16 @@ jobs: ci-required: # PR checks do not satisfy the merge gate before package and GPU qualification. name: ${{ github.event_name == 'pull_request' && 'ci-pr-checks' || 'ci-required' }} - needs: [lint, test-cpu, test-nooa, test-gpu, coverage, package, conda] + needs: [changes, developer-tools, lint, test-cpu, test-nooa, test-gpu, coverage, package, conda] if: ${{ always() }} runs-on: ubuntu-24.04 timeout-minutes: 5 steps: - name: Require every CI job to succeed env: + CHANGES_RESULT: ${{ needs.changes.result }} + DEV_REQUIRED: ${{ needs.changes.outputs.dev }} + DEV_RESULT: ${{ needs.developer-tools.result }} LINT_RESULT: ${{ needs.lint.result }} CPU_RESULT: ${{ needs.test-cpu.result }} NOOA_RESULT: ${{ needs.test-nooa.result }} @@ -562,6 +620,11 @@ jobs: PACKAGE_RESULT: ${{ needs.package.result }} CONDA_RESULT: ${{ needs.conda.result }} run: | + test "${CHANGES_RESULT}" = success || exit 1 + case "${DEV_REQUIRED}:${DEV_RESULT}" in + true:success|false:skipped) ;; + *) exit 1 ;; + esac for result in "${LINT_RESULT}" "${CPU_RESULT}" "${NOOA_RESULT}" "${COVERAGE_RESULT}" "${CONDA_RESULT}"; do test "${result}" = success || exit 1 done diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index f3a6fbdb..bba32885 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,12 +3,15 @@ # SPDX-License-Identifier: Apache-2.0 name: user guide +run-name: docs ${{ inputs.tag || 'main' }} / ${{ inputs.request_id || github.sha }} on: push: branches: [main] paths: - .github/workflows/docs.yml + - .github/workflows/release-docs.yml + - dev/** - docs/** - src/** - examples/** @@ -19,6 +22,8 @@ on: branches: [main] paths: - .github/workflows/docs.yml + - .github/workflows/release-docs.yml + - dev/** - docs/** - src/** - examples/** @@ -26,25 +31,40 @@ on: - uv.lock - setup.py workflow_dispatch: + inputs: + # Existing release tags retain their hook. Preserve this name and type. + tag: + description: "Release tag, main, or missing for eligible backfills" + type: string + default: main + request_id: + description: "Optional client request identifier for run tracking" + type: string + default: "" permissions: contents: read +# Keep the lock from archive read through deployment. Queue every publication; +# a newer main run must not cancel a pending release or an active deployment. concurrency: - group: pages-${{ github.ref }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + group: ${{ github.event_name == 'pull_request' && format('docs-preview-{0}', github.event.number) || 'cuphoton-docs-publication' }} + queue: max + cancel-in-progress: false + +env: + CUPHOTON_XDR_BUILD_EXT: "0" + CUPHOTON_XREP_TORCH_DEVICE: cpu + CUDA_VISIBLE_DEVICES: "" + MPLBACKEND: Agg + UV_HTTP_TIMEOUT: "300" jobs: - build: - name: render user guide + preview: + name: preview user guide + if: github.event_name == 'pull_request' runs-on: ubuntu-24.04 - timeout-minutes: 20 - env: - CUPHOTON_XDR_BUILD_EXT: "0" - CUPHOTON_XREP_TORCH_DEVICE: cpu - CUDA_VISIBLE_DEVICES: "" - MPLBACKEND: Agg - UV_HTTP_TIMEOUT: "300" + timeout-minutes: 30 steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 with: @@ -54,6 +74,8 @@ jobs: with: version: "0.12.1" enable-cache: true + - name: Install developer tools + run: uv sync --project dev --locked --python 3.12 - name: Install Quarto run: | curl --fail --location --retry 3 --output "$RUNNER_TEMP/quarto.deb" \ @@ -62,35 +84,71 @@ jobs: 8c47762e78fe58642246a94d18f67eb332c1778b711e5bef991ef3c15490d83a \ "$RUNNER_TEMP/quarto.deb" | sha256sum --check sudo dpkg --install "$RUNNER_TEMP/quarto.deb" - - name: Install documentation dependencies - run: uv sync --locked --python 3.12 --group docs --extra ximage --extra catalog - - name: Render the guide and execute its CPU examples - env: - CUPHOTON_REPO: ${{ github.workspace }} - QUARTO_PYTHON: ${{ github.workspace }}/.venv/bin/python - run: quarto render docs/guide - - name: Upload the rendered site - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + - name: Render exact PR source in isolation + run: >- + uv run --project dev --locked cuphoton dev docs-build + --ref "$GITHUB_SHA" --repo . --output "$RUNNER_TEMP/preview" + - name: Check the rendered preview + run: uv run --project dev --locked cuphoton dev docs-check "$RUNNER_TEMP/preview" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 with: - path: docs/guide/_book + name: docs-preview-${{ github.sha }} + path: ${{ runner.temp }}/preview + if-no-files-found: error + retention-days: 14 - deploy: - name: deploy user guide - needs: build + publish: + name: publish user guide if: >- github.repository == 'NVIDIA/cuPhoton' && github.ref == 'refs/heads/main' && github.event_name != 'pull_request' runs-on: ubuntu-24.04 - timeout-minutes: 10 + timeout-minutes: 90 permissions: + contents: write pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + # Controller code is always the main SHA that started this workflow. + ref: ${{ github.sha }} + persist-credentials: false + fetch-depth: 0 + - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6 + with: + version: "0.12.1" + enable-cache: true + - name: Install developer tools + run: uv sync --project dev --locked --python 3.12 + - name: Install Quarto + run: | + curl --fail --location --retry 3 --output "$RUNNER_TEMP/quarto.deb" \ + https://github.com/quarto-dev/quarto-cli/releases/download/v1.9.36/quarto-1.9.36-linux-amd64.deb + printf '%s %s\n' \ + 8c47762e78fe58642246a94d18f67eb332c1778b711e5bef991ef3c15490d83a \ + "$RUNNER_TEMP/quarto.deb" | sha256sum --check + sudo dpkg --install "$RUNNER_TEMP/quarto.deb" + - name: Retain snapshots and assemble the complete site + env: + GH_TOKEN: ${{ github.token }} + DOCS_TAG: ${{ inputs.tag }} + DOCS_REQUEST_ID: ${{ inputs.request_id }} + run: >- + uv run --project dev --locked python -m cuphoton_dev.publisher prepare + --tag "$DOCS_TAG" --request-id "$DOCS_REQUEST_ID" + --output "$RUNNER_TEMP/site" + - name: Check the complete publication + run: uv run --project dev --locked cuphoton dev docs-check "$RUNNER_TEMP/site" - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 + - name: Upload the complete retained site + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: ${{ runner.temp }}/site - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml new file mode 100644 index 00000000..eadbb812 --- /dev/null +++ b/.github/workflows/release-docs.yml @@ -0,0 +1,38 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +# Keep this hook on release branches before tagging. All publisher code lives +# on main; existing tags keep dispatching the compatible docs.yml tag input. +name: release documentation + +on: + release: + types: [published, released] + +permissions: + actions: write + +jobs: + forward: + if: >- + github.repository == 'NVIDIA/cuPhoton' && + !github.event.release.draft && + !github.event.release.prerelease && + github.event.release.published_at != null + runs-on: ubuntu-24.04 + timeout-minutes: 5 + steps: + - name: Dispatch the main publisher for a final release + env: + GH_TOKEN: ${{ github.token }} + RELEASE_TAG: ${{ github.event.release.tag_name }} + shell: bash + run: | + # Both initial final publication and prerelease promotion reach here. + # Ignore non-semantic and prerelease tags even if marked final. + if [[ ! "$RELEASE_TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then + exit 0 + fi + gh workflow run docs.yml --repo "$GITHUB_REPOSITORY" --ref main \ + --field "tag=$RELEASE_TAG" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 354a2fb7..0cc2372d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,10 +23,13 @@ Do not report security vulnerabilities through GitHub. Follow `SECURITY.md`. ## Coding Guidelines -All Python code ships in one distribution and must live under `cuphoton.*`. +Product Python code ships in one distribution and lives under `cuphoton.*`. Shared CLI, application-context, logging, and invariant framework code belongs in `cuphoton.core`. Workflow-specific configuration remains in the component -that owns the workflow. Do not add top-level Python packages. +that owns the workflow. The explicit repository-only exception is the +independently installed `dev/` project (`cuphoton-dev`, module `cuphoton_dev`). +It is excluded from product wheels, sdists, Conda payloads and Git source +archives. Do not add other top-level Python packages. Keep pull requests concise: @@ -71,6 +74,14 @@ Use the smallest profile that exercises the change. The experimental `cutile` extra supports Python 3.12–3.14; use a CUDA 13.2 or newer TileIR compiler for the supported setup. The `dragon` extra currently supports Python 3.12 and 3.13. +### Documentation developer tools + +Versioned documentation uses the independent, explicitly installed `dev/` +project. See its [installation and publication runbook](dev/README.md) and +[agent instructions](dev/AGENTS.md). Product installs and the existing `dev` +extra do not include these tools. Keep both dependency locks synchronized when +root dependencies change, and verify release-hook inheritance before tagging. + ## Checks Run focused tests for the code you changed, then run the repository checks diff --git a/MANIFEST.in b/MANIFEST.in index 1409f5fe..4f96d850 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -29,6 +29,7 @@ include requirements-dragon.txt include .pre-commit-config.yaml recursive-include docs *.md prune docs/guide +prune dev recursive-include examples *.py *.yaml recursive-include examples/distributed-pipeline *.json *.txt *.license recursive-include tests *.py diff --git a/dev/.gitignore b/dev/.gitignore new file mode 100644 index 00000000..22d65b82 --- /dev/null +++ b/dev/.gitignore @@ -0,0 +1,3 @@ +.venv +.coverage* +coverage*.xml diff --git a/dev/AGENTS.md b/dev/AGENTS.md new file mode 100644 index 00000000..f6829531 --- /dev/null +++ b/dev/AGENTS.md @@ -0,0 +1,31 @@ +# Developer-tool instructions + +Scope: the independent `dev/` project and its documentation publishing workflows. + +- Read [the runbook](README.md) before changing publication behavior. Install + this project explicitly with `uv sync --project dev --locked`; root installs + and the product's existing `dev` extra must remain independent. +- Reuse `cuphoton.core` command, invariant and context machinery. Keep the + product component registry fixed and the optional route lazy. Product wheels, + sdists, Conda packages and Git source archives must exclude this project. +- Keep orchestration and postprocessing on main. Render exact target source + with its lockfile in a separate environment; never replace historical + chapters or edit an existing tag. Authored guide URLs continue to name main. +- Preserve the `docs.yml` workflow name and string `tag` dispatch input. Release + branches inherit only the forwarding hook; verify it is present before each + future release cut. Publishing packages is not the GitHub Release signal. +- Every publication must validate formal-release eligibility, retained hashes, + tag identity and the complete catalog. Hold the shared publication lock from + reading the archive through native Pages deployment. Keep PR jobs read-only. +- Keep transformation fixtures synchronized with guide markup, install examples, + link structure and search output. Unexpected version-sensitive markup should + fail validation rather than silently publish stale main instructions. +- Update `scripts/ci/dev_changes.py` when adding a dependency or transformation + input. Update and check `dev/uv.lock` after changing root dependency metadata; + do not add this project to the root lock, groups, extras or workspace. +- Run developer tests and type checks separately from product tests and coverage. + Exercise real main and release renders, navigation, search, themes and bookmark + redirects when changing transformations or publication behavior. Inspect + deployed URLs and hashes before reporting a rollout complete. +- Follow the repository's Apache-2.0 SPDX/copyright, signed-commit and DCO rules. + Keep local environments, output trees, review notes and credentials untracked. diff --git a/dev/README.md b/dev/README.md new file mode 100644 index 00000000..cb6fde34 --- /dev/null +++ b/dev/README.md @@ -0,0 +1,181 @@ +# Documentation developer tools + +This repository-only project builds and publishes cuPhoton's versioned user +guide. It is installed explicitly and reuses the product CLI framework. +It does not publish software releases or upload packages. + +## Install and check + +From a complete cuPhoton checkout: + +```sh +uv sync --project dev --locked +uv run --project dev --locked cuphoton dev --help +``` + +For a pip environment, install both editable projects explicitly: + +```sh +python -m pip install -e . -e dev +``` + +The separate `dev/.venv` keeps root `uv sync` independent. Normal product +installs, root editable installs, root sync and the existing product `dev` +extra do not install `cuphoton-dev` or advertise `cuphoton dev`. Uninstalling +`cuphoton-dev` removes that route from help. `python -m cuphoton_dev` provides +the same commands in an explicitly installed environment. + +Run the developer checks separately: + +```sh +uv lock --project dev --check +uv run --project dev --locked ruff check dev scripts/ci +uv run --project dev --locked ruff format --check dev scripts/ci +uv run --project dev --locked mypy --config-file dev/pyproject.toml dev/src/cuphoton_dev +uv run --project dev --locked pytest -c dev/pyproject.toml dev/tests +``` + +CI writes developer coverage separately from product coverage. The changes +classifier includes core CLI code, package entrypoints, dependency locks, +packaging exclusions, shared configuration, workflows and guide inputs. It +compares PRs to their actual target merge base, vetted PR copies to that PR's +target, and ordinary pushes to their before/after commits. Uncertain ranges +run the developer tests. Existing product CI requirements remain in force. + +When root dependencies change, update both locks and check both projects: + +```sh +uv lock +uv lock --project dev +uv lock --check +uv lock --project dev --check +``` + +Beautiful Soup and Soup Sieve are MIT-licensed developer-only dependencies. +Keep dependency/license review and `dev/uv.lock` synchronized when updating +them; they are not product dependencies or product payloads. + +Keep new dependency paths in `scripts/ci/dev_changes.py`. Changes to guide +markup, install wording, source URLs or search output also require review of +transformation fixtures and real rendered output. See [AGENTS.md](AGENTS.md) +for instructions for agents working in this project. + +## Build and inspect + +Make `uv` and `git` available on `PATH`. The command reuses an installed Quarto +matching the target's renderer pin. Otherwise, on Linux amd64 and arm64 it +downloads the target renderer from the official release, verifies its digest +against the main controller's trusted table and extracts it into the temporary +render workspace. It does not replace the host's Quarto installation. Unknown +renderer versions fail with instructions to update the table. + +When upgrading Quarto, add its official release digests to +`dev/src/cuphoton_dev/renderers.py` and retain all historical entries so missed +release publications can still be backfilled. The command creates a complete +isolated source checkout and uses the target's locked Python dependencies. +CPU examples execute from that checkout. The output includes build provenance +and hashes; authored source remains unchanged. + +```sh +uv run --project dev --locked cuphoton dev docs-build --ref main --output /tmp/cuphoton-main +uv run --project dev --locked cuphoton dev docs-build --ref v0.2.0 --output /tmp/cuphoton-v0.2.0 +uv run --project dev --locked cuphoton dev docs-check /tmp/cuphoton-v0.2.0 --json +uv run --project dev --locked cuphoton dev docs-status --json +``` + +A draft release can be built and checked locally. Publication additionally +requires a published, non-prerelease GitHub Release whose tag is a full final +version such as `v0.2.0`. Older tags without the guide are reported as +unavailable; they are not populated from newer content. + +## Site layout and ownership + +The site at contains: + +| Path | Meaning | +| --- | --- | +| `main/` | Moving development guide | +| `v0.2.0/`, later full versions | Retained release snapshots | +| `stable/` | Highest documented, published final release | +| Root and existing chapter paths | Redirects to stable, or main before the first eligible snapshot | +| `versions.json` | Generated shared catalog | + +Every snapshot reads the shared catalog. Version selection preserves the +chapter and a valid anchor where available, falling back to the target home +page. Root and stable redirects preserve query strings and fragments. Search, +assets and canonical URLs remain within the selected version. + +Main owns rendering orchestration, conversion and publication. Release tags +own the source code, guide and dependency lock used to render their snapshot. +Authored documentation continues to use main URLs; HTML postprocessing converts +release links, install examples, labels, search data and canonical URLs. +The `gh-pages` branch retains complete validated output. Main publications +replace only `main/`; release publications retain existing release bytes. +Catalogs and redirects are generated, not hand-maintained. + +## Publish, bootstrap and recover + +Authenticate `gh` with access to dispatch repository Actions. For a normal +publication, the CLI dispatches `docs.yml` explicitly on main and reports the +exact run URL. It waits for completion and returns a failing exit status when +the workflow fails. Use `--json` for machine-readable results or `--no-wait` +to return after dispatch. + +```sh +uv run --project dev --locked cuphoton dev docs-publish --ref main --json +uv run --project dev --locked cuphoton dev docs-publish --ref v0.2.0 --json +uv run --project dev --locked cuphoton dev docs-publish --missing --json +``` + +The existing `v0.2.0` tag predates the release hook. Its once-off bootstrap is +the `--ref v0.2.0` command above, after the GitHub Release becomes eligible. +Keep its tag unchanged. Before eligibility, finish the local render and check +and leave this command ready; documentation rollout does not authorize release +publication. + +The workflow serializes archive updates through Pages deployment. It re-reads +retained state under the lock, rejects a moved tag or stale main rollback, +validates the complete site and publishes through native Pages actions. A +failed render leaves the live site and catalog intact. If deployment fails +after retaining the assembled site, retry the workflow or repeat the same CLI +command. Matching release snapshots are reused, so duplicate requests are safe. +Use `--missing` for deliberate reconciliation of eligible missing releases. + +If validation rejects a retained snapshot or tag identity, inspect the failing +run and provenance before retrying. Do not repair this by moving a release tag, +copying current-main chapters, or editing generated catalog entries. A change +to an immutable snapshot requires a separate reviewed correction procedure. + +After successful deployment, verify the live root, `main/`, `stable/`, release +paths and existing chapter bookmarks. Check the shared catalog, search, +light/dark themes, desktop/mobile navigation and keyboard version selection. +Compare served files to retained hashes and confirm older release hashes +survive the next publication. A successful build alone is not deployment +verification. + +## Future release hooks + +Before cutting a release, verify that its branch contains +`.github/workflows/release-docs.yml`. New release branches inherit it from main. +For the existing `0.2.x` branch, add only this hook before its next tag; no +developer package or documentation-content backport is needed. + +The hook responds to `published` and `released`, including promotion of a +prerelease to a final Release. It accepts only the canonical repository and a +published final semantic-version tag, then dispatches `docs.yml` with +`ref: main` and the string `tag` input. The receiving publisher independently +checks eligibility and the exact tag. Keep that workflow filename and input +compatible with hooks already stored in historical tags. + +Publishing a GitHub Release with `GITHUB_TOKEN` does not trigger the ordinary +downstream release workflow. A programmatic release publisher must explicitly +dispatch documentation after it publishes the final Release: + +```sh +gh workflow run docs.yml --repo NVIDIA/cuPhoton --ref main --field tag=v0.2.1 +``` + +Give that integration `actions: write` and check the resulting documentation +run. The existing package-upload workflow uploads packages and does not +publish a GitHub Release, so it is not the documentation trigger. Prereleases, +draft releases and package uploads alone must not promote stable docs. diff --git a/dev/pyproject.toml b/dev/pyproject.toml new file mode 100644 index 00000000..c56d6278 --- /dev/null +++ b/dev/pyproject.toml @@ -0,0 +1,64 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +[build-system] +requires = ["setuptools>=84.2.1"] +build-backend = "setuptools.build_meta" + +[project] +name = "cuphoton-dev" +version = "0.1.0" +description = "Repository development tools for cuPhoton contributors." +requires-python = ">=3.12,<3.15" +license = "Apache-2.0" +dependencies = ["cuphoton", "beautifulsoup4>=4.14,<5"] + +[dependency-groups] +dev = [ + "coverage>=7.10.6,<8", + "mypy==1.19.1", + "pytest>=8.3", + "ruff>=0.15.12", + "types-beautifulsoup4>=4.12", +] + +[tool.uv.sources] +cuphoton = { path = "..", editable = true } + +[tool.setuptools.packages.find] +where = ["src"] +include = ["cuphoton_dev*"] + +[tool.setuptools.package-data] +cuphoton_dev = ["assets/*.js", "assets/*.css"] + +[tool.ruff] +extend = "../pyproject.toml" + +[tool.pytest.ini_options] +minversion = "8.0" +addopts = ["--import-mode=importlib"] +testpaths = ["tests"] + +[tool.mypy] +strict = true +python_version = "3.12" +files = ["src/cuphoton_dev"] +mypy_path = "$MYPY_CONFIG_FILE_DIR/../src" +check_untyped_defs = true +warn_unused_ignores = true +warn_redundant_casts = true +show_error_codes = true + +[[tool.mypy.overrides]] +module = ["cuphoton.*"] +follow_imports = "silent" + +[tool.coverage.run] +branch = true +source = ["cuphoton_dev"] +data_file = ".coverage-dev" + +[tool.coverage.xml] +output = "coverage-dev.xml" diff --git a/dev/src/cuphoton_dev/__init__.py b/dev/src/cuphoton_dev/__init__.py new file mode 100644 index 00000000..92d4ef50 --- /dev/null +++ b/dev/src/cuphoton_dev/__init__.py @@ -0,0 +1,5 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Repository tools installed from the independent dev project.""" diff --git a/dev/src/cuphoton_dev/__main__.py b/dev/src/cuphoton_dev/__main__.py new file mode 100644 index 00000000..5b9d0903 --- /dev/null +++ b/dev/src/cuphoton_dev/__main__.py @@ -0,0 +1,7 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from .cli import main + +raise SystemExit(main()) diff --git a/dev/src/cuphoton_dev/archive.py b/dev/src/cuphoton_dev/archive.py new file mode 100644 index 00000000..1651decb --- /dev/null +++ b/dev/src/cuphoton_dev/archive.py @@ -0,0 +1,274 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Retain historical snapshots when assembling a Pages archive.""" + +from __future__ import annotations + +import html +import json +import posixpath +import shutil +import tempfile +from collections.abc import Callable +from pathlib import Path, PurePosixPath +from typing import Any + +from cuphoton_dev.transforms import RELEASE, check_snapshot + + +def _json(path: Path, value: Any) -> None: + path.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n") + + +def _release_key(version: str) -> tuple[int, ...]: + match = RELEASE.fullmatch(version) + if not match: + raise ValueError(f"Not a formal version: {version}") + return tuple(int(n) for n in match.groups()) + + +def _snapshots(archive: Path) -> dict[str, dict[str, Any]]: + result = {} + for path in sorted(archive.iterdir()): + if path.name == "main" or RELEASE.fullmatch(path.name): + if path.is_symlink() or not path.is_dir(): + raise ValueError(f"Invalid snapshot directory: {path}") + receipt = check_snapshot(path) + if receipt["version"] != path.name: + raise ValueError( + f"Snapshot directory and receipt disagree: {path}" + ) + result[path.name] = receipt + return result + + +def redirect_html(target: str) -> str: + """Redirect with a no-JS fallback and query/fragment preservation.""" + escaped = html.escape(target, quote=True) + # The target is a generated relative path. + script_target = json.dumps(target).replace("<", "\\u003c") + return ( + '\n' + '' + "cuPhoton documentation" + f'

Continue to cuPhoton documentation.

' + "" + f'" + "\n" + ) + + +def _catalog( + receipts: dict[str, dict[str, Any]], + eligible_releases: set[str], + legacy_pages: set[str] | None = None, +) -> dict[str, Any]: + releases = sorted( + (v for v in receipts if v != "main"), key=_release_key, reverse=True + ) + stable = next((v for v in releases if v in eligible_releases), None) + preferred = stable or ("main" if "main" in receipts else None) + if preferred is None: + raise ValueError("Archive has no main or eligible release snapshot") + versions = (["main"] if "main" in receipts else []) + releases + entries = [ + { + "version": version, + "path": version + "/", + "source_sha": receipts[version]["source_sha"], + "released": version in eligible_releases, + "pages": receipts[version]["pages"], + } + for version in versions + ] + pages = sorted( + {p for receipt in receipts.values() for p in receipt["pages"]} + | (legacy_pages or set()) + ) + aliases: dict[str, str] = {} + for page in pages: + page_path = PurePosixPath(page) + if ( + page_path.is_absolute() + or ".." in page_path.parts + or page_path.as_posix() != page + or page_path.suffix != ".html" + ): + raise ValueError(f"Invalid legacy chapter path: {page}") + # Never replace a snapshot/catalog directory with a legacy alias. + first = page.split("/", 1)[0] + if first in { + "main", + "stable", + "versions.html", + "versions.json", + } or RELEASE.fullmatch(first): + raise ValueError( + f"Chapter path collides with archive layout: {page}" + ) + target_page = ( + page if page in receipts[preferred]["pages"] else "index.html" + ) + target = preferred + "/" + target_page + for alias in (page, "stable/" + page): + aliases[alias] = posixpath.relpath( + target, posixpath.dirname(alias) or "." + ) + return { + "schema": 1, + "stable": stable, + "preferred": preferred, + "versions": entries, + "legacy_pages": pages, + "aliases": aliases, + } + + +def _generate(archive: Path, catalog: dict[str, Any]) -> None: + _json(archive / "versions.json", catalog) + for alias, target in catalog["aliases"].items(): + file = archive / alias + file.parent.mkdir(parents=True, exist_ok=True) + file.write_text(redirect_html(target)) + items = "".join( + f'
  • ' + f"{html.escape(entry['version'])}" + f"{' (stable)' if entry['version'] == catalog['stable'] else ''}" + "
  • " + for entry in catalog["versions"] + ) + (archive / "versions.html").write_text( + '' + '' + "cuPhoton documentation versions" + "

    cuPhoton documentation versions

      " + + items + + "
    \n" + ) + (archive / ".nojekyll").touch() + + +def assemble( + archive: Path, + snapshot: Path, + *, + eligible_releases: set[str], + is_ancestor: Callable[[str, str], bool] | None = None, +) -> dict[str, Any]: + """Validate and stage a complete update, preserving immutable releases. + + The caller holds the workflow concurrency lock from reading the archive + through deployment, and commits this generated tree only after success. + An ancestry callback is mandatory when main changes to another source SHA. + """ + archive, snapshot = Path(archive), Path(snapshot) + incoming = check_snapshot(snapshot) + version = incoming["version"] + for release in eligible_releases: + _release_key(release) + if version != "main" and version not in eligible_releases: + raise ValueError( + f"Release is not eligible for publication: {version}" + ) + archive.mkdir(parents=True, exist_ok=True) + receipts = _snapshots(archive) + legacy_pages: set[str] = set() + if (archive / "versions.json").is_file(): + previous_catalog = json.loads((archive / "versions.json").read_text()) + legacy_pages.update(previous_catalog["legacy_pages"]) + previous = receipts.get(version) + reuse = False + if previous: + if incoming["site_url"] != previous["site_url"]: + raise ValueError("Snapshot site URL changed") + if version != "main": + if incoming["source_sha"] != previous["source_sha"]: + raise ValueError( + f"Tag moved since its retained snapshot: {version}" + ) + reuse = True + elif incoming["source_sha"] != previous["source_sha"]: + if is_ancestor is None or not is_ancestor( + previous["source_sha"], incoming["source_sha"] + ): + raise ValueError( + "Stale or unrelated main snapshot would replace " + "published main" + ) + if receipts and incoming["site_url"] not in { + r["site_url"] for r in receipts.values() + }: + raise ValueError("Snapshots disagree about the site URL") + with tempfile.TemporaryDirectory( + prefix="cuphoton-archive-", dir=archive.parent + ) as scratch: + staged = Path(scratch) / "site" + shutil.copytree( + archive, staged, ignore=shutil.ignore_patterns(".git") + ) + if not reuse: + destination = staged / version + if destination.exists(): + shutil.rmtree(destination) + shutil.copytree(snapshot, destination) + retained = _snapshots(staged) + catalog = _catalog(retained, eligible_releases, legacy_pages) + _generate(staged, catalog) + check_archive(staged) + # All validation has completed before the first mutation. Preserve Git + # metadata and copy ordinary files, which native Pages accepts. + if not reuse: + destination = archive / version + if destination.exists(): + shutil.rmtree(destination) + shutil.copytree(staged / version, destination) + _generate(archive, catalog) + return catalog + + +def check_archive(path: Path) -> dict[str, Any]: + """Validate snapshots, catalog, stable choice and legacy aliases.""" + path = Path(path) + for entry in path.rglob("*"): + if ".git" in entry.relative_to(path).parts: + continue + if entry.is_symlink() or ( + entry.is_file() and entry.stat().st_nlink != 1 + ): + raise ValueError(f"Archive contains a link: {entry}") + catalog: dict[str, Any] = json.loads((path / "versions.json").read_text()) + if catalog.get("schema") != 1: + raise ValueError("Unsupported documentation catalog schema") + receipts = _snapshots(path) + eligible = { + entry["version"] for entry in catalog["versions"] if entry["released"] + } + expected = _catalog(receipts, eligible, set(catalog["legacy_pages"])) + if catalog != expected: + raise ValueError("Catalog does not match retained snapshots") + for alias, target in catalog["aliases"].items(): + redirect = path / alias + if not redirect.is_file() or redirect.read_text() != redirect_html( + target + ): + raise ValueError(f"Invalid legacy redirect: {alias}") + resolved = (redirect.parent / target).resolve() + if ( + not resolved.is_relative_to(path.resolve()) + or not resolved.is_file() + ): + raise ValueError(f"Legacy redirect has no target: {alias}") + if ( + not (path / "versions.html").is_file() + or not (path / ".nojekyll").is_file() + ): + raise ValueError( + "Archive is missing its fallback catalog or Pages marker" + ) + return catalog diff --git a/dev/src/cuphoton_dev/assets/selector.css b/dev/src/cuphoton_dev/assets/selector.css new file mode 100644 index 00000000..c3668fe0 --- /dev/null +++ b/dev/src/cuphoton_dev/assets/selector.css @@ -0,0 +1,24 @@ +/* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 */ +.cuphoton-version { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: .5rem .8rem; + border: 1px solid currentColor; + border-radius: .3rem; + margin: 0 0 1.5rem; + padding: .65rem .85rem; + font-size: .9rem; +} +.cuphoton-version label { margin: 0; } +.cuphoton-version select { + color: inherit; + background: var(--bs-body-bg, Canvas); + border: 1px solid currentColor; + border-radius: .2rem; + padding: .2rem .4rem; + max-width: 100%; +} +.cuphoton-version select:focus-visible { outline: 3px solid #76b900; } +#cuphoton-version-notice { flex-basis: 100%; } diff --git a/dev/src/cuphoton_dev/assets/selector.js b/dev/src/cuphoton_dev/assets/selector.js new file mode 100644 index 00000000..ecfc7d1e --- /dev/null +++ b/dev/src/cuphoton_dev/assets/selector.js @@ -0,0 +1,48 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 +(() => { + "use strict"; + const script = document.currentScript; + const select = document.getElementById("cuphoton-version-select"); + const notice = document.getElementById("cuphoton-version-notice"); + const catalogURL = new URL(script.dataset.catalog, document.baseURI); + const root = new URL("./", catalogURL); + const current = script.dataset.version; + const page = script.dataset.page; + fetch(catalogURL, {cache: "no-cache"}) + .then(response => { + if (!response.ok) throw new Error("Catalog unavailable"); + return response.json(); + }) + .then(catalog => { + if (catalog.schema !== 1 || !Array.isArray(catalog.versions)) return; + const entries = catalog.versions; + if (!entries.some(entry => entry.version === current)) return; + select.replaceChildren(); + for (const entry of entries) { + const label = entry.version === "main" ? "main (development)" : entry.version; + const option = new Option(label + (entry.version === catalog.stable ? " (stable)" : ""), entry.version); + option.selected = entry.version === current; + select.add(option); + } + select.disabled = false; + select.addEventListener("change", () => { + const entry = entries.find(item => item.version === select.value); + const samePage = Object.hasOwn(entry.pages, page); + const targetPage = samePage ? page : "index.html"; + const target = new URL(entry.path + targetPage, root); + target.search = location.search; + let anchor; + try { anchor = decodeURIComponent(location.hash.slice(1)); } catch { anchor = ""; } + if (samePage && entry.pages[page].includes(anchor)) target.hash = location.hash; + location.assign(target); + }); + if (catalog.stable && current !== catalog.stable) { + const link = document.createElement("a"); + link.href = new URL(catalog.stable + "/index.html", root); + link.textContent = "Read stable " + catalog.stable + "."; + notice.replaceChildren(document.createTextNode(current === "main" ? "Development documentation. " : "An earlier release. "), link); + } + }) + .catch(() => { /* The server-rendered version and Versions link remain. */ }); +})(); diff --git a/dev/src/cuphoton_dev/build.py b/dev/src/cuphoton_dev/build.py new file mode 100644 index 00000000..4ffe4945 --- /dev/null +++ b/dev/src/cuphoton_dev/build.py @@ -0,0 +1,225 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 +"""Render a complete, immutable source checkout in its own environment.""" + +from __future__ import annotations + +import hashlib +import os +import re +import shutil +import subprocess +import sys +import tempfile +from pathlib import Path +from typing import Any + +from cuphoton_dev.renderers import renderer_for + +FINAL_TAG = re.compile(r"v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\Z") + + +def run( + args: list[str], + *, + cwd: Path | None = None, + env: dict[str, str] | None = None, + capture: bool = True, +) -> str: + """Keep progress on stderr so command stdout can be machine-readable.""" + if not capture: + with subprocess.Popen( + args, + cwd=cwd, + env=env, + text=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + ) as process: + assert process.stdout is not None + for line in process.stdout: + sys.stderr.write(line) + code = process.wait() + if code: + raise RuntimeError(f"{args[0]} failed ({code}); see build output") + return "" + result = subprocess.run( + args, + cwd=cwd, + env=env, + text=True, + capture_output=True, + ) + if result.returncode: + raise RuntimeError( + f"{args[0]} failed ({result.returncode}): " + f"{result.stderr or 'see build output'}" + ) + return (result.stdout or "").strip() + + +def git(repo: Path, *args: str) -> str: + return run(["git", "-C", str(repo), *args]) + + +def resolve(repo: Path, ref: str) -> str: + return git( + repo, "rev-parse", "--verify", "--end-of-options", f"{ref}^{{commit}}" + ) + + +def render_environment(checkout: Path) -> dict[str, str]: + """Do not inherit the controller's Python or uv project selection.""" + env = dict(os.environ) + for key in ( + "PYTHONPATH", + "PYTHONHOME", + "VIRTUAL_ENV", + "CONDA_PREFIX", + "UV_PROJECT_ENVIRONMENT", + "UV_PROJECT", + "UV_WORKING_DIR", + "QUARTO_PROFILE", + "JUPYTER_PATH", + "JUPYTER_CONFIG_DIR", + "JUPYTER_DATA_DIR", + "GH_TOKEN", + "GITHUB_TOKEN", + "ACTIONS_ID_TOKEN_REQUEST_TOKEN", + "ACTIONS_ID_TOKEN_REQUEST_URL", + ): + env.pop(key, None) + for key in tuple(env): + if key.startswith("SETUPTOOLS_SCM_"): + env.pop(key) + env.update( + UV_PROJECT_ENVIRONMENT=str(checkout / ".venv"), + CUPHOTON_XDR_BUILD_EXT="0", + CUPHOTON_IMAGING_BUILD_EXT="0", + CUPHOTON_XFIT_BUILD_EXT="0", + CUPHOTON_XREP_TORCH_DEVICE="cpu", + CUDA_VISIBLE_DEVICES="", + MPLBACKEND="Agg", + CUPHOTON_REPO=str(checkout), + QUARTO_PYTHON=str(checkout / ".venv/bin/python"), + JUPYTER_CONFIG_DIR=str(checkout / ".jupyter"), + IPYTHONDIR=str(checkout / ".ipython"), + JUPYTER_DATA_DIR=str(checkout / ".jupyter/data"), + JUPYTER_PATH=str(checkout / ".venv/share/jupyter"), + JUPYTER_PREFER_ENV_PATH="1", + PATH=str(checkout / ".venv/bin") + os.pathsep + env.get("PATH", ""), + ) + return env + + +def docs_build( + *, ref: str, output: Path, repo: Path | None = None +) -> dict[str, Any]: + """Build in a fresh checkout without editing the controller.""" + from cuphoton_dev.transforms import postprocess + + repo = (repo or Path.cwd()).resolve() + output = output.resolve() + if output.exists(): + raise ValueError(f"Output already exists: {output}") + source_sha = resolve(repo, ref) + version = ref if FINAL_TAG.fullmatch(ref) else "main" + controller_repo = Path(__file__).resolve().parents[3] + controller_sha = resolve(controller_repo, "HEAD") + output.parent.mkdir(parents=True, exist_ok=True) + with tempfile.TemporaryDirectory(prefix="cuphoton-docs-") as temporary: + checkout = Path(temporary) / "source" + run( + [ + "git", + "clone", + "--quiet", + "--no-local", + "--no-checkout", + str(repo), + str(checkout), + ] + ) + git(checkout, "checkout", "--quiet", "--detach", source_sha) + guide = checkout / "docs/guide" + if not (guide / "_quarto.yml").is_file(): + raise ValueError( + f"Documentation is unavailable at {ref} ({source_sha})" + ) + workflow = (checkout / ".github/workflows/docs.yml").read_text() + pin = re.search(r"releases/download/v([\d.]+)/quarto", workflow) + if not pin: + raise ValueError( + "Target has no recognized pinned Quarto renderer" + ) + renderer = pin[1] + quarto = renderer_for(renderer, Path(temporary)) + env = render_environment(checkout) + # Allow a site-specific environment provisioning wrapper. + uv = os.environ.get("CUPHOTON_DOCS_UV", "uv") + run( + [ + uv, + "sync", + "--locked", + "--python", + "3.12", + "--group", + "docs", + "--extra", + "ximage", + "--extra", + "catalog", + ], + cwd=checkout, + env=env, + capture=False, + ) + run( + [ + str(checkout / ".venv/bin/python"), + "-m", + "ipykernel", + "install", + "--prefix", + str(checkout / ".venv"), + "--name", + "python3", + ], + cwd=checkout, + env=env, + capture=False, + ) + run( + [ + str(quarto), + "render", + "docs/guide", + "--execute", + "--no-cache", + ], + cwd=checkout, + env=env, + capture=False, + ) + git(checkout, "diff", "--exit-code") + rendered = guide / "_book" + receipt = postprocess( + rendered, + version=version, + source_sha=source_sha, + controller_sha=controller_sha, + renderer=renderer, + lock_sha256=hashlib.sha256( + (checkout / "uv.lock").read_bytes() + ).hexdigest(), + ) + # Output appears only after rendering and all snapshot checks pass. + with tempfile.TemporaryDirectory( + prefix=".docs-output-", dir=output.parent + ) as stage: + staged = Path(stage) / "snapshot" + shutil.copytree(rendered, staged) + staged.rename(output) + return {"output": str(output), **receipt} diff --git a/dev/src/cuphoton_dev/cli.py b/dev/src/cuphoton_dev/cli.py new file mode 100644 index 00000000..25aa883b --- /dev/null +++ b/dev/src/cuphoton_dev/cli.py @@ -0,0 +1,165 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Developer commands using the product's command and invariant framework.""" + +from __future__ import annotations + +import json +from collections.abc import Mapping, Sequence +from pathlib import Path +from typing import Any, TextIO + +from cuphoton.core.cli import ( + BoolInvariant, + ComponentSpec, + InvariantAwareCommand, + PathValueInvariant, + StringInvariant, + run_component, +) + +DEVELOPER_COMPONENT = ComponentSpec( + "dev", + "cuphoton_dev", + "Repository development and documentation tools.", + commands_module="cuphoton_dev.cli", + parser_style="argparse", + supports_version_command=False, +) + + +class _DocsCommand(InvariantAwareCommand): + _log_level_ = False + _quiet_ = False + _verbose_ = False + _shortname_ = None + json = False + + class JsonArg(BoolInvariant): + _arg = "--json" + _help = "Write a machine-readable JSON result." + + def emit(self, result: Mapping[str, Any]) -> None: + if self.json: + self._out(json.dumps(result, sort_keys=True)) + return + for key, value in result.items(): + if isinstance(value, (dict, list)): + value = json.dumps(value, sort_keys=True) + self._out(f"{key}: {value}") + + +class DocsBuildCommand(_DocsCommand): + _description_ = "Render and validate documentation from an exact source." + ref: str + output_dir: Path + repo = Path(".") + + class RefArg(StringInvariant): + _arg = "--ref" + _required = True + _help = "Main revision or full release tag to render." + + class OutputDirArg(PathValueInvariant): + _arg = "--output" + _required = True + _help = "Destination for the validated snapshot." + + class RepoArg(PathValueInvariant): + _arg = "--repo" + _help = "Source Git checkout (default: current directory)." + + def run(self) -> None: + from .publisher import docs_build + + self.emit( + docs_build(ref=self.ref, output=self.output_dir, repo=self.repo) + ) + + +class DocsCheckCommand(_DocsCommand): + _description_ = "Validate a rendered snapshot or complete site archive." + directory: Path + + class DirectoryArg(PathValueInvariant): + _required = True + _metavar = "DIR" + + def run(self) -> None: + from .publisher import docs_check + + self.emit(docs_check(self.directory)) + + +class _RemoteDocsCommand(_DocsCommand): + repository = "NVIDIA/cuPhoton" + + class RepositoryArg(StringInvariant): + _arg = "--repository" + _help = "GitHub repository (default: NVIDIA/cuPhoton)." + + +class DocsStatusCommand(_RemoteDocsCommand): + _description_ = "List published, missing, and unavailable documentation." + + def run(self) -> None: + from .publisher import docs_status + + self.emit(docs_status(repository=self.repository)) + + +class DocsPublishCommand(_RemoteDocsCommand): + _description_ = "Dispatch publication on main and track its workflow run." + ref: str | None = None + missing = False + no_wait = False + + class RefArg(StringInvariant): + _arg = "--ref" + _help = "Publish main or an eligible full release tag." + + class MissingArg(BoolInvariant): + _arg = "--missing" + _help = "Backfill all eligible releases without documentation." + + class NoWaitArg(BoolInvariant): + _arg = "--no-wait" + _help = ( + "Return the tracked workflow run without waiting for completion." + ) + + def run(self) -> None: + from .publisher import docs_publish + + if (self.ref is None) == (not self.missing): + raise ValueError("supply exactly one of --ref or --missing") + self.emit( + docs_publish( + ref=self.ref, + missing=self.missing, + wait=not self.no_wait, + repository=self.repository, + ) + ) + + +def main( + argv: Sequence[str] | None = None, + *, + out: TextIO | None = None, + err: TextIO | None = None, + environ: Mapping[str, str] | None = None, + program_name: str = "cuphoton dev", +) -> int: + """Run the explicitly installed developer group.""" + + return run_component( + DEVELOPER_COMPONENT, + argv, + out=out, + err=err, + environ=environ, + program_name=program_name, + ) diff --git a/dev/src/cuphoton_dev/github.py b/dev/src/cuphoton_dev/github.py new file mode 100644 index 00000000..e3999295 --- /dev/null +++ b/dev/src/cuphoton_dev/github.py @@ -0,0 +1,215 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 +"""Authenticated GitHub operations and exact workflow-run tracking.""" + +from __future__ import annotations + +import json +import subprocess +import time +import uuid +from typing import Any +from urllib.error import HTTPError +from urllib.parse import quote +from urllib.request import urlopen + +from cuphoton_dev.build import FINAL_TAG + +REPOSITORY = "NVIDIA/cuPhoton" +SITE = "https://nvidia.github.io/cuPhoton/" + + +def api( + path: str, *, data: dict[str, Any] | None = None, missing_ok: bool = False +) -> Any: + args = ["gh", "api", "-H", "X-GitHub-Api-Version: 2026-03-10", path] + if data is not None: + args.extend(["--method", "POST", "--input", "-"]) + result = subprocess.run( + args, + input=json.dumps(data) if data is not None else None, + text=True, + capture_output=True, + ) + if result.returncode: + if missing_ok and "HTTP 404" in result.stderr: + return None + raise RuntimeError(f"GitHub request failed: {result.stderr.strip()}") + return json.loads(result.stdout) if result.stdout.strip() else None + + +def releases(repository: str = REPOSITORY) -> list[dict[str, Any]]: + result = [] + page = 1 + while True: + batch = api(f"repos/{repository}/releases?per_page=100&page={page}") + result.extend(batch) + if len(batch) < 100: + return result + page += 1 + + +def eligible(release: dict[str, Any]) -> bool: + return bool( + FINAL_TAG.fullmatch(release["tag_name"]) + and not release["draft"] + and not release["prerelease"] + and release["published_at"] + ) + + +def has_guide(tag: str, repository: str = REPOSITORY) -> bool: + return ( + api( + f"repos/{repository}/contents/docs/guide/_quarto.yml" + f"?ref={quote(tag, safe='')}", + missing_ok=True, + ) + is not None + ) + + +def published_catalog() -> dict[str, Any]: + try: + with urlopen(SITE + "versions.json", timeout=30) as response: + catalog = json.load(response) + except HTTPError as error: + if error.code == 404: + return {"schema": 1, "stable": None, "versions": []} + raise + if catalog.get("schema") != 1 or not isinstance( + catalog.get("versions"), list + ): + raise ValueError( + "Published version catalog has an unsupported schema" + ) + return dict(catalog) + + +def require_repository(repository: str) -> None: + if repository != REPOSITORY: + raise ValueError(f"Documentation publication supports {REPOSITORY}") + + +def docs_status(*, repository: str = REPOSITORY) -> dict[str, Any]: + require_repository(repository) + catalog = published_catalog() + published = {entry["version"] for entry in catalog["versions"]} + entries = [] + for release in releases(repository): + tag = release["tag_name"] + if not eligible(release): + state = "ineligible" + elif tag in published: + state = "published" + else: + state = "missing" if has_guide(tag, repository) else "unavailable" + entries.append( + { + "tag": tag, + "state": state, + "draft": release["draft"], + "prerelease": release["prerelease"], + "release_url": release["html_url"], + } + ) + return { + "repository": repository, + "site": SITE, + "stable": catalog["stable"], + "main": "published" if "main" in published else "missing", + "releases": entries, + } + + +def wait_for_run( + repository: str, run_id: int, *, wait: bool, request_id: str +) -> dict[str, Any]: + deadline = time.monotonic() + 7200 + while True: + run = api(f"repos/{repository}/actions/runs/{run_id}") + result = { + "request_id": request_id, + "run_id": run_id, + "url": run["html_url"], + "status": run["status"], + "conclusion": run["conclusion"], + "controller_sha": run["head_sha"], + } + if run["status"] == "completed": + if run["conclusion"] != "success": + raise RuntimeError( + f"Documentation publication {run['conclusion']}: " + f"{run['html_url']}" + ) + return result + if not wait: + return result + if time.monotonic() >= deadline: + raise RuntimeError( + f"Publication still running; inspect {run['html_url']}" + ) + time.sleep(5) + + +def docs_publish( + *, + ref: str | None = None, + missing: bool = False, + wait: bool = True, + repository: str = REPOSITORY, +) -> dict[str, Any]: + require_repository(repository) + if missing == (ref is not None): + raise ValueError("Specify exactly one of --ref or --missing") + tag = "missing" if missing else ref + if tag not in {"main", "missing"}: + if not tag or not FINAL_TAG.fullmatch(tag): + raise ValueError( + "Publication ref must be main or a full release tag vX.Y.Z" + ) + release = next( + (r for r in releases(repository) if r["tag_name"] == tag), None + ) + if release is None or not eligible(release): + raise ValueError(f"{tag} is not a published final GitHub Release") + if not has_guide(tag, repository): + raise ValueError(f"Documentation is unavailable at {tag}") + request_id = uuid.uuid4().hex + response = api( + f"repos/{repository}/actions/workflows/docs.yml/dispatches", + data={ + "ref": "main", + "inputs": {"tag": tag, "request_id": request_id}, + }, + ) + run_id = response.get("workflow_run_id") if response else None + if run_id is None: + # Older API deployments return 204. Correlate our unique request + # instead of selecting another caller's latest run. + deadline = time.monotonic() + 180 + while run_id is None: + runs = api( + f"repos/{repository}/actions/workflows/docs.yml/runs" + "?event=workflow_dispatch&branch=main&per_page=100" + ) + matches = [ + r + for r in runs["workflow_runs"] + if request_id in r["display_title"] + ] + if len(matches) > 1: + raise RuntimeError(f"Ambiguous workflow request {request_id}") + if matches: + run_id = matches[0]["id"] + elif time.monotonic() >= deadline: + raise RuntimeError( + f"Dispatch accepted; run not found for {request_id}. " + "Do not redispatch blindly." + ) + else: + time.sleep(3) + return wait_for_run( + repository, int(run_id), wait=wait, request_id=request_id + ) diff --git a/dev/src/cuphoton_dev/publisher.py b/dev/src/cuphoton_dev/publisher.py new file mode 100644 index 00000000..6acbf830 --- /dev/null +++ b/dev/src/cuphoton_dev/publisher.py @@ -0,0 +1,245 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 +"""One implementation for local commands and the main-only Pages publisher.""" + +from __future__ import annotations + +import argparse +import json +import os +import shutil +import subprocess +import tempfile +from pathlib import Path +from typing import Any + +from cuphoton_dev.build import FINAL_TAG, docs_build, git, resolve, run +from cuphoton_dev.github import ( + REPOSITORY, + docs_publish, + docs_status, + eligible, + has_guide, + releases, +) + +__all__ = ["docs_build", "docs_check", "docs_publish", "docs_status"] + + +def docs_check(directory: Path) -> dict[str, Any]: + from cuphoton_dev.archive import check_archive + from cuphoton_dev.transforms import check_snapshot + + if (directory / "versions.json").exists(): + return check_archive(directory) + return check_snapshot(directory) + + +def is_ancestor(repo: Path, older: str, newer: str) -> bool: + result = subprocess.run( + ["git", "-C", str(repo), "merge-base", "--is-ancestor", older, newer], + capture_output=True, + text=True, + ) + if result.returncode not in (0, 1): + raise RuntimeError(f"Cannot establish main ancestry: {result.stderr}") + return result.returncode == 0 + + +def clone_archive(destination: Path) -> None: + remote = f"https://github.com/{REPOSITORY}.git" + existing = run( + ["git", "ls-remote", "--heads", remote, "refs/heads/gh-pages"] + ) + if existing: + run( + [ + "git", + "clone", + "--quiet", + "--single-branch", + "--branch", + "gh-pages", + remote, + str(destination), + ] + ) + else: + destination.mkdir() + git(destination, "init", "--quiet", "--initial-branch=gh-pages") + git(destination, "remote", "add", "origin", remote) + + +def prepare( + *, tag: str, output: Path, request_id: str = "" +) -> dict[str, Any]: + """Assemble and retain a full site inside the workflow's publication lock. + + Deployment uses native Pages actions after this succeeds. A failed deploy + can retry this operation, reusing matching release snapshots verbatim. + """ + from cuphoton_dev.archive import assemble, check_archive + from cuphoton_dev.transforms import check_snapshot + + if ( + os.environ.get("GITHUB_REPOSITORY") != REPOSITORY + or os.environ.get("GITHUB_REF") != "refs/heads/main" + or os.environ.get("GITHUB_EVENT_NAME") + not in {"push", "workflow_dispatch"} + ): + raise ValueError( + "Archive publication requires the canonical main workflow; " + "use docs-publish" + ) + repo = Path.cwd().resolve() + controller = resolve(repo, "HEAD") + if controller != os.environ.get("GITHUB_SHA"): + raise ValueError( + "Controller checkout must match the workflow main SHA" + ) + output = output.resolve() + if output.exists(): + raise ValueError(f"Output already exists: {output}") + tag = tag or "main" + if tag not in {"main", "missing"} and not FINAL_TAG.fullmatch(tag): + raise ValueError( + "Expected main, missing, or a full release tag vX.Y.Z" + ) + release_records = releases() + eligible_tags = {r["tag_name"] for r in release_records if eligible(r)} + if tag not in {"main", "missing"} and tag not in eligible_tags: + raise ValueError(f"{tag} is not a published final GitHub Release") + if tag == "missing": + targets = sorted(t for t in eligible_tags if has_guide(t)) + else: + targets = [tag] + with tempfile.TemporaryDirectory( + prefix="cuphoton-publication-" + ) as temporary: + work = Path(temporary) + retained = work / "archive" + clone_archive(retained) + if (retained / "versions.json").exists(): + check_archive(retained) + if ( + not (retained / "main/build.json").exists() + and "main" not in targets + ): + targets.insert(0, "main") + for target in targets: + source_ref = ( + controller if target == "main" else f"refs/tags/{target}" + ) + source_sha = resolve(repo, source_ref) + prior = retained / target + receipt = check_snapshot(prior) if prior.exists() else None + if ( + target != "main" + and receipt is not None + and receipt["source_sha"] != source_sha + ): + raise ValueError( + f"Retained {target} conflicts with the current tag" + ) + reuse = receipt is not None and ( + target != "main" + or ( + receipt["source_sha"] == source_sha + and receipt["controller_sha"] == controller + ) + ) + if reuse: + # Retained main also permits deployment recovery without + # rendering again, but a new controller must rebuild it. + snapshot = prior + else: + snapshot = work / f"build-{target}" + docs_build( + ref=controller if target == "main" else target, + output=snapshot, + repo=repo, + ) + assemble( + retained, + snapshot, + eligible_releases=eligible_tags, + is_ancestor=lambda older, newer: is_ancestor( + repo, older, newer + ), + ) + if not targets: + # Empty reconciliation refreshes generated aliases/catalog. + assemble( + retained, + retained / "main", + eligible_releases=eligible_tags, + is_ancestor=lambda older, newer: is_ancestor( + repo, older, newer + ), + ) + # Release state can change during a render. Do not publish a decision + # made before a release was withdrawn or promoted; retry instead. + if eligible_tags != { + r["tag_name"] for r in releases() if eligible(r) + }: + raise RuntimeError( + "Release eligibility changed during publication; retry" + ) + catalog = check_archive(retained) + git(retained, "add", "--all") + if git(retained, "status", "--porcelain"): + git( + retained, + "-c", + "user.name=github-actions[bot]", + "-c", + "user.email=41898282+github-actions[bot]@users.noreply.github.com", + "-c", + "commit.gpgsign=false", + "commit", + "-m", + "Retain validated documentation and refresh version routes", + ) + # Scope credentials to this push. No credential is written + # to repository files, command arguments, logs or rendered output. + git( + retained, + "-c", + "credential.helper=", + "-c", + "credential.helper=!gh auth git-credential", + "push", + "origin", + "HEAD:refs/heads/gh-pages", + ) + archive_sha = resolve(retained, "HEAD") + shutil.copytree( + retained, output, ignore=shutil.ignore_patterns(".git") + ) + return { + "request_id": request_id, + "controller_sha": controller, + "archive_sha": archive_sha, + "output": str(output), + "catalog": catalog, + } + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + subcommands = parser.add_subparsers(dest="command", required=True) + command = subcommands.add_parser("prepare") + command.add_argument("--tag", default="main") + command.add_argument("--request-id", default="") + command.add_argument("--output", required=True, type=Path) + args = parser.parse_args() + result = prepare( + tag=args.tag, request_id=args.request_id, output=args.output + ) + print(json.dumps(result, sort_keys=True)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/dev/src/cuphoton_dev/renderers.py b/dev/src/cuphoton_dev/renderers.py new file mode 100644 index 00000000..e28e5b2e --- /dev/null +++ b/dev/src/cuphoton_dev/renderers.py @@ -0,0 +1,91 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Select a target renderer without changing the host installation.""" + +from __future__ import annotations + +import hashlib +import platform +import shutil +import subprocess +import tarfile +from pathlib import Path +from urllib.request import urlopen + +# Official quarto-dev/quarto-cli release asset digests, also published in +# quarto--checksums.txt. Retain old entries when upgrading main. +RENDERERS = { + "1.9.36": { + "amd64": ( + "39d2e4546274be39a27cceeeed21a60b693c4c477a8c8cb43fb34326442f3910" + ), + "arm64": ( + "6f4b2fee6be469ae038a23fe3196010f29d7716129eed2891524c1f88ad82f2f" + ), + }, +} + + +def _version(executable: Path) -> str | None: + try: + result = subprocess.run( + [str(executable), "--version"], + capture_output=True, + text=True, + timeout=30, + ) + except (OSError, subprocess.TimeoutExpired): + return None + return result.stdout.strip() if result.returncode == 0 else None + + +def renderer_for(version: str, scratch: Path) -> Path: + """Reuse a matching renderer or extract a verified one beneath scratch. + + The caller owns scratch and its lifetime. No global installation or + credentials are needed. Unknown versions require a reviewed table update. + """ + if version not in RENDERERS: + raise ValueError( + f"Unsupported Quarto {version}; add its verified release hashes " + "to the main controller's renderer table" + ) + installed = shutil.which("quarto") + if installed and _version(Path(installed)) == version: + return Path(installed).resolve() + machine = platform.machine().lower() + architecture = { + "x86_64": "amd64", + "amd64": "amd64", + "aarch64": "arm64", + "arm64": "arm64", + }.get(machine) + if platform.system() != "Linux" or architecture is None: + raise ValueError( + "Automatic Quarto provisioning supports Linux amd64 and arm64; " + f"install the supported Quarto {version} on this host" + ) + destination = scratch / f"quarto-{version}-{architecture}" + destination.mkdir(parents=True, exist_ok=False) + archive = destination / "renderer.tar.gz" + asset = f"quarto-{version}-linux-{architecture}.tar.gz" + url = ( + "https://github.com/quarto-dev/quarto-cli/releases/download/" + f"v{version}/{asset}" + ) + with urlopen(url, timeout=60) as response, archive.open("wb") as stream: + shutil.copyfileobj(response, stream) + with archive.open("rb") as stream: + digest = hashlib.file_digest(stream, "sha256").hexdigest() + if digest != RENDERERS[version][architecture]: + raise ValueError(f"Quarto {version} download checksum mismatch") + with tarfile.open(archive, "r:gz") as package: + package.extractall(destination, filter="data") + executable = destination / f"quarto-{version}" / "bin/quarto" + if _version(executable) != version: + raise ValueError( + f"Extracted Quarto does not report version {version}" + ) + return executable.resolve() diff --git a/dev/src/cuphoton_dev/transforms.py b/dev/src/cuphoton_dev/transforms.py new file mode 100644 index 00000000..acdebb99 --- /dev/null +++ b/dev/src/cuphoton_dev/transforms.py @@ -0,0 +1,439 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Convert rendered guide sources into self-contained snapshots.""" + +from __future__ import annotations + +import hashlib +import json +import posixpath +import re +import shutil +from pathlib import Path +from typing import Any +from urllib.parse import unquote, urlsplit, urlunsplit +from xml.etree import ElementTree as ET + +from bs4 import BeautifulSoup, NavigableString + +SITE_URL = "https://nvidia.github.io/cuPhoton/" +RELEASE = re.compile(r"v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\Z") +RECEIPT = "build.json" +_INSTALL = ( + "This clones the development branch, which this guide describes. " + "To use a published version instead, pick its tag from Releases, " + "add --branch TAG to the clone command, and use the documentation " + "in that checkout." +) +_REFERENCE = re.compile( + r"The links point to the repository[’']s main branch, " + r"which can be newer than this guide\." +) +_CLONE = "git clone https://github.com/NVIDIA/cuPhoton.git" +_REQUIRED = { + "index.html", + "install.html", + "reference.html", + "search.json", + "sitemap.xml", +} + + +def validate_version(version: str) -> None: + if version != "main" and not RELEASE.fullmatch(version): + raise ValueError(f"Not a documentation version: {version!r}") + + +def _write_json(path: Path, value: Any) -> None: + path.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n") + + +def file_hashes(path: Path) -> dict[str, str]: + """Hash regular files only; Pages artifacts cannot contain links.""" + hashes = {} + for file in sorted(path.rglob("*")): + if file.is_symlink(): + raise ValueError(f"Snapshot contains a symbolic link: {file}") + if file.is_file(): + if file.stat().st_nlink != 1: + raise ValueError(f"Snapshot contains a hard link: {file}") + relative = file.relative_to(path).as_posix() + if relative != RECEIPT: + hashes[relative] = hashlib.sha256( + file.read_bytes() + ).hexdigest() + return hashes + + +def _owned_url(value: str, version: str, site_url: str) -> str: + url = urlsplit(value) + if url.netloc.lower() in {"github.com", "raw.githubusercontent.com"}: + parts = url.path.split("/") + if len(parts) >= 4 and [p.lower() for p in parts[1:3]] == [ + "nvidia", + "cuphoton", + ]: + ref_index = 3 if url.netloc.lower().startswith("raw.") else 4 + if ( + len(parts) > ref_index + and parts[ref_index] == "main" + and ( + ref_index == 3 + or parts[3] in {"blob", "tree", "raw", "edit"} + ) + ): + parts[ref_index] = version + return urlunsplit(url._replace(path="/".join(parts))) + base = urlsplit(site_url) + if url.netloc == base.netloc and url.path.startswith(base.path): + tail = url.path[len(base.path) :] + if not tail.startswith(version + "/"): + return urlunsplit( + url._replace(path=base.path + version + "/" + tail) + ) + # Quarto may use root-relative navigation and asset references. + if not url.netloc and url.path.startswith(base.path) and base.path != "/": + tail = url.path[len(base.path) :] + if not tail.startswith(version + "/"): + return urlunsplit( + url._replace(path=base.path + version + "/" + tail) + ) + return value + + +def _release_text(value: str, version: str) -> str: + value = value.replace( + _INSTALL, + f"This clones release {version}, which this guide describes.", + ) + value = _REFERENCE.sub( + f"The links point to the repository's {version} tag, " + "matching this guide.", + value, + ) + return value.replace( + _CLONE, + f"git clone --branch {version} --single-branch " + "https://github.com/NVIDIA/cuPhoton.git", + ) + + +def _transform_json(value: Any, version: str, site_url: str) -> Any: + if isinstance(value, str): + value = _owned_url(value, version, site_url) + return _release_text(value, version) if version != "main" else value + if isinstance(value, list): + return [_transform_json(v, version, site_url) for v in value] + if isinstance(value, dict): + return { + k: _transform_json(v, version, site_url) for k, v in value.items() + } + return value + + +def _assert_release_text(text: str, filename: str) -> None: + normalized = " ".join(text.split()) + stale = ( + "This clones the development branch", + "--branch TAG", + "which can be newer than this guide", + _CLONE, + ) + if any(term in normalized for term in stale) or re.search( + r"https://(?:github\.com/NVIDIA/cuPhoton/(?:blob|tree|raw|edit)|" + r"raw\.githubusercontent\.com/NVIDIA/cuPhoton)/main(?:/|[\"\s])", + text, + re.IGNORECASE, + ): + raise ValueError( + f"Unconverted release instructions or links: {filename}" + ) + + +def postprocess( + output: Path, + *, + version: str, + source_sha: str, + controller_sha: str, + renderer: str, + site_url: str = SITE_URL, + lock_sha256: str | None = None, +) -> dict[str, Any]: + """Transform an isolated Quarto output, then record its validated bytes. + + Call only on freshly rendered output. Release transformation contracts + deliberately fail when known source instructions change, requiring the + controller and its fixtures to be reviewed together. + """ + output = Path(output) + validate_version(version) + site_url = site_url.rstrip("/") + "/" + if (output / RECEIPT).exists(): + raise ValueError( + "Output is already postprocessed; render a fresh tree" + ) + missing = _REQUIRED - set(file_hashes(output)) + if missing: + raise ValueError(f"Incomplete rendered guide: {sorted(missing)}") + pages: dict[str, list[str]] = {} + converted = {"clone": 0, "install": 0, "reference": 0} + for file in sorted(output.rglob("*.html")): + relative = file.relative_to(output).as_posix() + soup = BeautifulSoup(file.read_text(), "html.parser") + if soup.head is None or soup.body is None: + raise ValueError(f"Missing HTML head/body: {relative}") + for node in soup.find_all(True): + for attr in ("href", "src", "content", "data-url"): + value = node.get(attr) + if isinstance(value, str): + node[attr] = _owned_url(value, version, site_url) + if version != "main": + for paragraph in soup.find_all("p"): + text = " ".join(paragraph.get_text().split()) + if _INSTALL in text: + paragraph.clear() + paragraph.append(_release_text(text, version)) + converted["install"] += 1 + elif _REFERENCE.search(text): + paragraph.clear() + paragraph.append(_release_text(text, version)) + converted["reference"] += 1 + for code in soup.find_all("code"): + if _CLONE in code.get_text(): + # Preserve Quarto's line IDs and syntax highlighting. + for text in list(code.find_all(string=True)): + if ( + " clone https://github.com/" + "NVIDIA/cuPhoton.git" in text + ): + text.replace_with( + str(text).replace( + " clone https://github.com/" + "NVIDIA/cuPhoton.git", + f" clone --branch {version} " + "--single-branch " + "https://github.com/NVIDIA/cuPhoton.git", + ) + ) + converted["clone"] += 1 + elif _CLONE in text: + text.replace_with( + _release_text(str(text), version) + ) + converted["clone"] += 1 + _assert_release_text(str(soup), relative) + for old in soup.select('link[rel="canonical"]'): + old.decompose() + canonical = soup.new_tag( + "link", rel="canonical", href=site_url + version + "/" + relative + ) + soup.head.append(canonical) + for name, value in ( + ("cuphoton-version", version), + ("cuphoton-source", source_sha), + ): + soup.head.append( + soup.new_tag("meta", attrs={"name": name, "content": value}) + ) + label = "main (development)" if version == "main" else version + if soup.title: + soup.title.append(NavigableString(" · " + label)) + depth = len(Path(relative).parts) - 1 + prefix = "../" * depth + shared = "../" * (depth + 1) + soup.head.append( + soup.new_tag( + "link", + rel="stylesheet", + href=prefix + "_version/selector.css", + ) + ) + script = soup.new_tag( + "script", src=prefix + "_version/selector.js", defer="" + ) + script["data-catalog"] = shared + "versions.json" + script["data-page"] = relative + script["data-version"] = version + soup.head.append(script) + banner = soup.new_tag( + "nav", + attrs={ + "class": "cuphoton-version", + "aria-label": "Documentation version", + }, + ) + label_tag = soup.new_tag( + "label", attrs={"for": "cuphoton-version-select"} + ) + label_tag.append("Documentation: ") + banner.append(label_tag) + select = soup.new_tag( + "select", id="cuphoton-version-select", disabled="" + ) + option = soup.new_tag("option", value=version) + option.string = label + select.append(option) + banner.append(select) + fallback = soup.new_tag("a", href=shared + "versions.html") + fallback.string = "Versions" + banner.append(fallback) + notice = soup.new_tag("span", id="cuphoton-version-notice") + notice.string = ( + "Development documentation." + if version == "main" + else f"Documentation for release {version}." + ) + banner.append(notice) + # Inside main content avoids obscuring the fixed Quarto navigation. + container = soup.find("main") or soup.body + container.insert(0, banner) + pages[relative] = sorted( + {str(tag["id"]) for tag in soup.find_all(id=True)} + ) + file.write_text(str(soup)) + if version != "main" and converted != { + "clone": 1, + "install": 1, + "reference": 1, + }: + raise ValueError(f"Release conversion contracts changed: {converted}") + search_path = output / "search.json" + search = _transform_json( + json.loads(search_path.read_text()), version, site_url + ) + _write_json(search_path, search) + if version != "main": + _assert_release_text(search_path.read_text(), "search.json") + sitemap_path = output / "sitemap.xml" + tree = ET.parse(sitemap_path) + for location in tree.iter(): + if location.tag.rsplit("}", 1)[-1] == "loc" and location.text: + location.text = _owned_url(location.text, version, site_url) + tree.write(sitemap_path, encoding="utf-8", xml_declaration=True) + asset_dir = output / "_version" + asset_dir.mkdir(exist_ok=True) + for asset in (Path(__file__).parent / "assets").iterdir(): + shutil.copyfile(asset, asset_dir / asset.name) + receipt = { + "schema": 1, + "version": version, + "source_sha": source_sha, + "controller_sha": controller_sha, + "renderer": renderer, + "lock_sha256": lock_sha256, + "site_url": site_url, + "pages": pages, + "files": file_hashes(output), + } + _write_json(output / RECEIPT, receipt) + return check_snapshot(output) + + +def _local_target( + value: str, relative: str, receipt: dict[str, Any] +) -> str | None: + url = urlsplit(value) + base = urlsplit(receipt["site_url"]) + prefix = base.path + receipt["version"] + "/" + if url.scheme in {"mailto", "tel", "data", "javascript"}: + return None + if url.netloc: + if url.netloc != base.netloc or not url.path.startswith(base.path): + return None + if not url.path.startswith(prefix): + raise ValueError(f"Link escapes selected version: {value}") + return unquote(url.path[len(prefix) :]) or "index.html" + if url.path.startswith("/"): + if not url.path.startswith(prefix): + raise ValueError(f"Link escapes selected version: {value}") + return unquote(url.path[len(prefix) :]) or "index.html" + if not url.path: + return relative + target = posixpath.normpath( + posixpath.join(posixpath.dirname(relative), unquote(url.path)) + ) + return target + "index.html" if target.endswith("/") else target + + +def check_snapshot(path: Path) -> dict[str, Any]: + """Check receipt integrity and the browser-facing version boundary.""" + path = Path(path) + receipt: dict[str, Any] = json.loads((path / RECEIPT).read_text()) + if receipt.get("schema") != 1: + raise ValueError("Unsupported documentation receipt schema") + validate_version(receipt["version"]) + actual = file_hashes(path) + if actual != receipt["files"]: + raise ValueError(f"Snapshot hashes differ from receipt: {path}") + if _REQUIRED - actual.keys(): + raise ValueError("Snapshot is missing required guide output") + inventory = receipt["pages"] + if set(inventory) != {f for f in actual if f.endswith(".html")}: + raise ValueError("Snapshot HTML inventory is incomplete") + for relative, anchors in inventory.items(): + text = (path / relative).read_text() + soup = BeautifulSoup(text, "html.parser") + canonical = soup.select('link[rel="canonical"]') + expected = receipt["site_url"] + receipt["version"] + "/" + relative + if len(canonical) != 1 or canonical[0].get("href") != expected: + raise ValueError(f"Wrong canonical URL: {relative}") + if sorted({str(t["id"]) for t in soup.find_all(id=True)}) != anchors: + raise ValueError(f"Wrong anchor inventory: {relative}") + if receipt["version"] != "main": + _assert_release_text(text, relative) + _assert_release_text(soup.get_text(" "), relative) + for node in soup.find_all(True): + for attr in ("href", "src"): + value = node.get(attr) + if not isinstance(value, str): + continue + # The one deliberate escape is the shared fallback catalog. + if ( + node.name == "a" + and value + == "../" * len(Path(relative).parts) + "versions.html" + ): + continue + target = _local_target(value, relative, receipt) + if target is not None and target not in actual: + raise ValueError( + f"Missing local target in {relative}: {value}" + ) + fragment = unquote(urlsplit(value).fragment) + if ( + target in inventory + and fragment + and fragment not in inventory[target] + ): + raise ValueError( + f"Missing local bookmark in {relative}: {value}" + ) + search_text = (path / "search.json").read_text() + if receipt["version"] != "main": + _assert_release_text(search_text, "search.json") + for record in json.loads(search_text): + target = _local_target(record["href"], "index.html", receipt) + if target not in inventory: + raise ValueError( + f"Search target is outside snapshot: {record['href']}" + ) + fragment = unquote(urlsplit(record["href"]).fragment) + if fragment and fragment not in inventory[target]: + raise ValueError(f"Search bookmark is missing: {record['href']}") + locations = { + element.text + for element in ET.parse(path / "sitemap.xml").iter() + if element.tag.rsplit("}", 1)[-1] == "loc" + } + expected_locations = { + receipt["site_url"] + receipt["version"] + "/" + relative + for relative in inventory + } + if locations != expected_locations: + raise ValueError( + "Sitemap does not describe the snapshot's HTML pages" + ) + return receipt diff --git a/dev/tests/test_archive.py b/dev/tests/test_archive.py new file mode 100644 index 00000000..08318a56 --- /dev/null +++ b/dev/tests/test_archive.py @@ -0,0 +1,128 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +import json + +import pytest + +from cuphoton_dev.archive import assemble, check_archive, redirect_html +from cuphoton_dev.transforms import file_hashes + +from .test_transforms import snapshot + + +def test_archive_preserves_releases_and_semantic_stable(tmp_path): + archive = tmp_path / "site" + main = snapshot(tmp_path / "main", extra_page=True) + initial = assemble(archive, main, eligible_releases=set()) + assert initial["preferred"] == "main" + assert initial["stable"] is None + newest = snapshot(tmp_path / "new", "v0.10.0") + catalog = assemble(archive, newest, eligible_releases={"v0.10.0"}) + hashes = file_hashes(archive / "v0.10.0") + older = snapshot(tmp_path / "old", "v0.2.1") + catalog = assemble( + archive, older, eligible_releases={"v0.10.0", "v0.2.1"} + ) + assert catalog["stable"] == "v0.10.0" + assert file_hashes(archive / "v0.10.0") == hashes + assert ( + catalog["aliases"]["nested/example.html"] == "../v0.10.0/index.html" + ) + updated = snapshot(tmp_path / "next-main", sha="d" * 40) + assemble( + archive, + updated, + eligible_releases={"v0.10.0", "v0.2.1"}, + is_ancestor=lambda old, new: old == "a" * 40 and new == "d" * 40, + ) + assert file_hashes(archive / "v0.10.0") == hashes + assert check_archive(archive)["stable"] == "v0.10.0" + + +def test_duplicate_release_keeps_original_bytes_and_moved_tag_fails(tmp_path): + archive = tmp_path / "site" + first = snapshot(tmp_path / "first", "v0.2.0") + assemble(archive, first, eligible_releases={"v0.2.0"}) + original = file_hashes(archive) + duplicate = snapshot(tmp_path / "duplicate", "v0.2.0", extra_page=True) + assemble(archive, duplicate, eligible_releases={"v0.2.0"}) + assert file_hashes(archive) == original + moved = snapshot(tmp_path / "moved", "v0.2.0", sha="f" * 40) + with pytest.raises(ValueError, match="Tag moved"): + assemble(archive, moved, eligible_releases={"v0.2.0"}) + assert file_hashes(archive) == original + + +def test_failed_or_stale_update_leaves_archive_intact(tmp_path): + archive = tmp_path / "site" + main = snapshot(tmp_path / "main") + assemble(archive, main, eligible_releases=set()) + original = file_hashes(archive) + stale = snapshot(tmp_path / "stale", sha="c" * 40) + with pytest.raises(ValueError, match="Stale"): + assemble( + archive, + stale, + eligible_releases=set(), + is_ancestor=lambda old, new: False, + ) + assert file_hashes(archive) == original + with pytest.raises(ValueError, match="Stale"): + assemble(archive, stale, eligible_releases=set()) + (stale / "index.html").write_text("bad render") + with pytest.raises(ValueError, match="hashes"): + assemble(archive, stale, eligible_releases=set()) + assert file_hashes(archive) == original + # A retry of the valid state is idempotent and still deployable. + assemble(archive, main, eligible_releases=set()) + assert file_hashes(archive) == original + + +def test_draft_and_prerelease_are_not_publishable(tmp_path): + archive = tmp_path / "site" + release = snapshot(tmp_path / "release", "v0.2.0") + with pytest.raises(ValueError, match="not eligible"): + assemble(archive, release, eligible_releases=set()) + assert not archive.exists() + with pytest.raises(ValueError, match="Not a formal version"): + assemble(archive, release, eligible_releases={"v0.2.0rc1"}) + + +def test_catalog_and_alias_tampering_detected(tmp_path): + archive = tmp_path / "site" + main = snapshot(tmp_path / "main") + assemble(archive, main, eligible_releases=set()) + (archive / "install.html").write_text("wrong redirect") + with pytest.raises(ValueError, match="redirect"): + check_archive(archive) + assemble(archive, main, eligible_releases=set()) + catalog = json.loads((archive / "versions.json").read_text()) + catalog["versions"][0]["pages"].pop("install.html") + (archive / "versions.json").write_text(json.dumps(catalog)) + with pytest.raises(ValueError, match="Catalog"): + check_archive(archive) + + +def test_redirect_preserves_query_and_bookmark(): + text = redirect_html("v0.2.0/install.html") + assert "target.search = location.search" in text + assert "target.hash = location.hash" in text + assert '' in text + assert "http-equiv" in text + + +def test_removed_main_chapter_keeps_legacy_redirect(tmp_path): + archive = tmp_path / "site" + first = snapshot(tmp_path / "first", extra_page=True) + assemble(archive, first, eligible_releases=set()) + second = snapshot(tmp_path / "second", sha="e" * 40) + catalog = assemble( + archive, + second, + eligible_releases=set(), + is_ancestor=lambda old, new: True, + ) + assert catalog["aliases"]["nested/example.html"] == "../main/index.html" + assert check_archive(archive) == catalog diff --git a/dev/tests/test_ci_changes.py b/dev/tests/test_ci_changes.py new file mode 100644 index 00000000..ce4cf3bc --- /dev/null +++ b/dev/tests/test_ci_changes.py @@ -0,0 +1,123 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import importlib.util +import json +import subprocess +from pathlib import Path + +import pytest + +SCRIPT = Path(__file__).resolve().parents[2] / "scripts/ci/dev_changes.py" +SPEC = importlib.util.spec_from_file_location("dev_changes", SCRIPT) +assert SPEC and SPEC.loader +changes = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(changes) + + +@pytest.mark.parametrize( + "path", + [ + "dev/uv.lock", + "src/cuphoton/core/cli.py", + "src/cuphoton/__main__.py", + "pyproject.toml", + "uv.lock", + "MANIFEST.in", + ".gitattributes", + "tests/conftest.py", + "docs/guide/install.qmd", + ".github/workflows/release-docs.yml", + "new-unknown-build-file", + ], +) +def test_dependency_paths(path): + assert changes.affects_dev(path) + + +@pytest.mark.parametrize( + "path", + ["src/cuphoton/xray/models.py", "docs/xfit/README.md", "README.md"], +) +def test_unrelated_paths(path): + assert not changes.affects_dev(path) + + +def test_vetted_copy_uses_actual_pr_target(monkeypatch): + head, target = "a" * 40, "b" * 40 + monkeypatch.setattr( + changes, + "command", + lambda *args: json.dumps( + {"head": {"sha": head}, "base": {"sha": target}} + ), + ) + assert changes.comparison( + {"after": head, "before": "c" * 40}, + "push", + "refs/heads/pull-request/19", + "NVIDIA/cuPhoton", + ) == (target, head, True) + assert changes.classify( + {"after": "d" * 40}, + "push", + "refs/heads/pull-request/19", + "NVIDIA/cuPhoton", + )["dev"] + + +def test_unknown_ranges_are_conservative(): + assert changes.classify({}, "push", "refs/heads/main", "NVIDIA/cuPhoton")[ + "dev" + ] + assert changes.classify( + {}, "workflow_dispatch", "refs/heads/main", "NVIDIA/cuPhoton" + )["dev"] + + +def test_git_ranges_cover_divergence_renames_and_deletions( + tmp_path, monkeypatch +): + monkeypatch.chdir(tmp_path) + + def git(*args): + return subprocess.check_output(["git", *args], text=True).strip() + + git("init", "-q") + git("config", "user.email", "test@example.com") + git("config", "user.name", "Test") + git("config", "commit.gpgsign", "false") + (tmp_path / "dev").mkdir() + (tmp_path / "dev/input.py").write_text("input\n") + git("add", ".") + git("commit", "-qm", "base") + base = git("rev-parse", "HEAD") + git("checkout", "-qb", "target") + (tmp_path / "pyproject.toml").write_text("target-only\n") + git("add", ".") + git("commit", "-qm", "target") + target = git("rev-parse", "HEAD") + git("checkout", "-qb", "topic", base) + git("mv", "dev/input.py", "moved.py") + git("commit", "-qm", "rename") + head = git("rev-parse", "HEAD") + # PR comparison excludes unrelated target-branch changes and includes the + # removed name even when Git would otherwise report a rename. + assert set(changes.changed_paths(target, head, True)) == { + "dev/input.py", + "moved.py", + } + # Push comparisons include the actual before/after trees, even on rewinds. + assert set(changes.changed_paths(target, head, False)) == { + "dev/input.py", + "moved.py", + "pyproject.toml", + } + git("rm", "moved.py") + git("commit", "-qm", "delete") + assert changes.changed_paths(head, git("rev-parse", "HEAD"), False) == [ + "moved.py" + ] diff --git a/dev/tests/test_cli.py b/dev/tests/test_cli.py new file mode 100644 index 00000000..d25bc6e0 --- /dev/null +++ b/dev/tests/test_cli.py @@ -0,0 +1,208 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import importlib.metadata +import io +import json +import subprocess +import sys +import types +from pathlib import Path + +import pytest +from cuphoton.core.cli import COMPONENTS, ComponentSpec +from cuphoton.core.cli import app as product_cli + +from cuphoton_dev.cli import main + + +def test_root_help_and_invocation_require_explicit_installation( + monkeypatch: pytest.MonkeyPatch, +) -> None: + def missing(name: str) -> None: + assert name == "cuphoton-dev" + raise importlib.metadata.PackageNotFoundError(name) + + monkeypatch.setattr( + product_cli.importlib.metadata, "distribution", missing + ) + out, err = io.StringIO(), io.StringIO() + # Developer source is importable in this test environment, but metadata + # still controls the opt-in route and help advertisement. + assert product_cli.main(["--help"], out=out, err=err) == 0 + assert " dev " not in out.getvalue() + out.seek(0) + out.truncate() + assert product_cli.main(["dev", "--help"], out=out, err=err) == 2 + assert out.getvalue() == "" + assert "uv sync --project dev --locked" in err.getvalue() + + +def test_installed_root_help_is_lazy(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr( + product_cli.importlib.metadata, "distribution", lambda _: object() + ) + + def no_import(name: str) -> None: + pytest.fail(f"root help imported {name}") + + monkeypatch.setattr(product_cli.importlib, "import_module", no_import) + out, err = io.StringIO(), io.StringIO() + assert product_cli.main(["--help"], out=out, err=err) == 0 + assert " dev " in out.getvalue() + assert err.getvalue() == "" + assert "dev" not in {component.group for component in COMPONENTS} + + +def test_product_delegation_preserves_streams_and_program_name( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr( + product_cli.importlib.metadata, "distribution", lambda _: object() + ) + out, err = io.StringIO(), io.StringIO() + assert ( + product_cli.main( + ["help", "dev", "docs-publish"], + out=out, + err=err, + program_name="custom", + ) + == 0 + ) + assert "custom dev docs-publish" in out.getvalue() + assert "--no-wait" in out.getvalue() + assert err.getvalue() == "" + + +def test_external_namespace_exception_is_scoped() -> None: + assert ( + ComponentSpec("dev", "cuphoton_dev", "Developer tools.").group + == "dev" + ) + with pytest.raises(ValueError, match="namespace"): + ComponentSpec("other", "cuphoton_dev", "Other tools.") + with pytest.raises(ValueError, match="namespace"): + ComponentSpec("dev", "arbitrary_plugin", "Other tools.") + + +@pytest.fixture +def publisher(monkeypatch: pytest.MonkeyPatch) -> types.ModuleType: + module = types.ModuleType("cuphoton_dev.publisher") + monkeypatch.setitem(sys.modules, module.__name__, module) + return module + + +@pytest.mark.parametrize( + ("arguments", "function", "expected"), + [ + ( + ["docs-build", "--ref", "v0.2.0", "--output", "book"], + "docs_build", + {"ref": "v0.2.0", "output": Path("book"), "repo": Path(".")}, + ), + ( + ["docs-status"], + "docs_status", + {"repository": "NVIDIA/cuPhoton"}, + ), + ( + ["docs-publish", "--ref", "main", "--no-wait"], + "docs_publish", + { + "ref": "main", + "missing": False, + "wait": False, + "repository": "NVIDIA/cuPhoton", + }, + ), + ( + ["docs-publish", "--missing"], + "docs_publish", + { + "ref": None, + "missing": True, + "wait": True, + "repository": "NVIDIA/cuPhoton", + }, + ), + ], +) +def test_commands_share_publisher_and_return_json( + publisher: types.ModuleType, + arguments: list[str], + function: str, + expected: dict[str, object], +) -> None: + def invoke(**kwargs: object) -> dict[str, object]: + assert kwargs == expected + return {"url": "https://example.org/run/123", "run_id": 123} + + setattr(publisher, function, invoke) + out, err = io.StringIO(), io.StringIO() + assert main([*arguments, "--json"], out=out, err=err) == 0 + assert json.loads(out.getvalue())["run_id"] == 123 + assert err.getvalue() == "" + + +def test_check_accepts_positional_directory( + publisher: types.ModuleType, +) -> None: + def check(directory: Path) -> dict[str, object]: + assert directory == Path("site") + return {"valid": True} + + publisher.docs_check = check + out, err = io.StringIO(), io.StringIO() + assert main(["docs-check", "site", "--json"], out=out, err=err) == 0 + assert json.loads(out.getvalue()) == {"valid": True} + assert err.getvalue() == "" + + +@pytest.mark.parametrize( + "arguments", + [ + ["docs-publish"], + ["docs-publish", "--missing", "--ref", "main"], + ["docs-build", "--ref", "main"], + ["docs-check"], + ], +) +def test_invalid_options_fail_without_calling_publisher( + publisher: types.ModuleType, + arguments: list[str], +) -> None: + def forbidden(**kwargs: object) -> None: + pytest.fail("invalid arguments reached publication") + + publisher.docs_publish = forbidden + out, err = io.StringIO(), io.StringIO() + assert main(arguments, out=out, err=err) != 0 + assert out.getvalue() == "" + assert err.getvalue() + + +def test_workflow_failure_propagates(publisher: types.ModuleType) -> None: + def publish(**kwargs: object) -> None: + raise RuntimeError("Publication failed: https://example.org/run/123") + + publisher.docs_publish = publish + out, err = io.StringIO(), io.StringIO() + assert main(["docs-publish", "--ref", "main"], out=out, err=err) == 1 + assert out.getvalue() == "" + assert "https://example.org/run/123" in err.getvalue() + + +def test_module_entrypoint() -> None: + result = subprocess.run( + [sys.executable, "-m", "cuphoton_dev", "--help"], + check=True, + capture_output=True, + text=True, + ) + assert "docs-build" in result.stdout + assert "docs-publish" in result.stdout + assert result.stderr == "" diff --git a/dev/tests/test_packaging.py b/dev/tests/test_packaging.py new file mode 100644 index 00000000..ffdb7382 --- /dev/null +++ b/dev/tests/test_packaging.py @@ -0,0 +1,230 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Build distributions and exercise developer opt-in in clean environments.""" + +from __future__ import annotations + +import io +import os +import shutil +import subprocess +import sys +import tarfile +import zipfile +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] + + +def run( + *arguments: str, + cwd: Path, + environment: Path | None = None, +) -> subprocess.CompletedProcess[str]: + env = os.environ.copy() + for key in tuple(env): + if key.startswith("SETUPTOOLS_SCM_") or key in { + "VIRTUAL_ENV", + "PYTHONPATH", + "UV_PROJECT_ENVIRONMENT", + }: + env.pop(key) + for component in ("XDR", "XFIT", "XRAY", "IMAGING"): + env[f"CUPHOTON_{component}_BUILD_EXT"] = "0" + if environment is not None: + env["UV_PROJECT_ENVIRONMENT"] = str(environment) + result = subprocess.run( + arguments, + cwd=cwd, + env=env, + capture_output=True, + text=True, + ) + assert result.returncode == 0, result.stdout + result.stderr + return result + + +@pytest.fixture(scope="module") +def source(tmp_path_factory: pytest.TempPathFactory) -> Path: + source = tmp_path_factory.mktemp("product-source") + files = run( + "git", + "ls-files", + "--cached", + "--others", + "--exclude-standard", + "-z", + cwd=ROOT, + ).stdout.split("\0") + for name in files: + if not name or not (ROOT / name).is_file(): + continue + destination = source / name + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(ROOT / name, destination) + run("git", "init", "--initial-branch=main", cwd=source) + run("git", "config", "user.name", "Packaging Tests", cwd=source) + run("git", "config", "user.email", "tests@example.org", cwd=source) + run("git", "config", "commit.gpgsign", "false", cwd=source) + run("git", "config", "tag.gpgsign", "false", cwd=source) + run("git", "add", ".", cwd=source) + run("git", "commit", "-m", "Packaging fixture", cwd=source) + run("git", "tag", "v0.2.0", cwd=source) + return source + + +def build(source: Path, output: Path) -> tuple[Path, Path]: + run( + "uv", + "build", + "--wheel", + "--sdist", + "--out-dir", + str(output), + cwd=source, + ) + return next(output.glob("*.whl")), next(output.glob("*.tar.gz")) + + +def probe(python: Path, cwd: Path, *, installed: bool) -> None: + run( + str(python), + "-c", + "import importlib.metadata as m, importlib.util, io; " + "from cuphoton.core.cli import main; " + f"installed = {installed!r}; " + "assert (importlib.util.find_spec('cuphoton_dev') is not None) " + "== installed; " + "names = {d.metadata['Name'] for d in m.distributions()}; " + "assert ('cuphoton-dev' in names) == installed; " + "out, err = io.StringIO(), io.StringIO(); " + "assert main(['--help'], out=out, err=err) == 0; " + "assert (' dev ' in out.getvalue()) == installed; " + "assert not err.getvalue(); " + "out, err = io.StringIO(), io.StringIO(); " + "assert main(['dev', '--help'], out=out, err=err) " + "== (0 if installed else 2)", + cwd=cwd, + ) + + +def test_product_artifacts_exclude_developer_project( + source: Path, tmp_path: Path +) -> None: + wheel, sdist = build(source, tmp_path / "initial") + with zipfile.ZipFile(wheel) as archive: + original_members = set(archive.namelist()) + assert not any("cuphoton_dev" in name for name in original_members) + assert not any(name.startswith("dev/") for name in original_members) + with tarfile.open(sdist) as archive: + assert not any( + "dev" in Path(name).parts[1:2] + or "cuphoton_dev" in Path(name).parts + for name in archive.getnames() + ) + archive.extractall(tmp_path / "extracted", filter="data") + extracted = next((tmp_path / "extracted").iterdir()) + # Conda uses this same extracted sdist as its complete source payload. + assert (extracted / "packaging/conda/recipe.yaml").is_file() + rebuilt, _ = build(extracted, tmp_path / "rebuilt") + with zipfile.ZipFile(rebuilt) as archive: + assert set(archive.namelist()) == original_members + + exported = subprocess.run( + ["git", "archive", "HEAD"], + cwd=source, + check=True, + capture_output=True, + ) + with tarfile.open(fileobj=io.BytesIO(exported.stdout)) as archive: + assert not any( + name == "dev" or name.startswith("dev/") + for name in archive.getnames() + ) + + +def test_installed_editable_sync_and_explicit_opt_in( + source: Path, tmp_path: Path +) -> None: + product_env = tmp_path / "product-env" + developer_env = tmp_path / "developer-env" + python = product_env / "bin/python" + wheel, _ = build(source, tmp_path / "before") + run( + "uv", "venv", str(product_env), "--python", sys.executable, cwd=source + ) + run( + "uv", + "pip", + "install", + "--python", + str(python), + str(wheel), + cwd=source, + ) + probe(python, source, installed=False) + run( + "uv", + "pip", + "install", + "--python", + str(python), + "-e", + ".", + cwd=source, + ) + probe(python, source, installed=False) + run("uv", "sync", "--locked", cwd=source, environment=product_env) + probe(python, source, installed=False) + run( + "uv", + "sync", + "--locked", + "--extra", + "dev", + cwd=source, + environment=product_env, + ) + probe(python, source, installed=False) + run( + "uv", + "pip", + "install", + "--python", + str(python), + "-e", + ".", + "-e", + "dev", + cwd=source, + ) + probe(python, source, installed=True) + after, _ = build(source, tmp_path / "after") + with zipfile.ZipFile(wheel) as before, zipfile.ZipFile(after) as current: + assert set(before.namelist()) == set(current.namelist()) + run( + "uv", + "pip", + "uninstall", + "--python", + str(python), + "cuphoton-dev", + cwd=source, + ) + probe(python, source, installed=False) + run( + "uv", + "sync", + "--locked", + "--project", + "dev", + cwd=source, + environment=developer_env, + ) + run("uv", "sync", "--locked", cwd=source, environment=product_env) + probe(python, source, installed=False) + probe(developer_env / "bin/python", source, installed=True) diff --git a/dev/tests/test_prepare.py b/dev/tests/test_prepare.py new file mode 100644 index 00000000..1fab3590 --- /dev/null +++ b/dev/tests/test_prepare.py @@ -0,0 +1,190 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Exercise publication transactions against real local Git repositories.""" + +from __future__ import annotations + +import subprocess +from types import SimpleNamespace + +import pytest + +from cuphoton_dev import publisher +from cuphoton_dev.transforms import file_hashes, postprocess + +from .test_publisher import release +from .test_transforms import rendered_guide + + +def git(path, *args): + return subprocess.check_output( + ["git", "-C", str(path), *args], text=True, stderr=subprocess.PIPE + ).strip() + + +@pytest.fixture +def publication(tmp_path, monkeypatch): + source = tmp_path / "source" + source.mkdir() + git(source, "init", "-q", "--initial-branch=main") + git(source, "config", "user.name", "Test") + git(source, "config", "user.email", "test@example.com") + git(source, "config", "commit.gpgsign", "false") + (source / "source.txt").write_text("first source\n") + git(source, "add", ".") + git(source, "commit", "-qm", "first source") + sha = git(source, "rev-parse", "HEAD") + git(source, "tag", "v0.2.0") + remote = tmp_path / "remote.git" + remote.mkdir() + git(remote, "init", "-q", "--bare") + + def clone(destination): + heads = git(remote, "for-each-ref", "refs/heads/gh-pages") + if heads: + subprocess.run( + [ + "git", + "clone", + "-q", + "--branch", + "gh-pages", + str(remote), + str(destination), + ], + check=True, + ) + else: + destination.mkdir() + git(destination, "init", "-q", "--initial-branch=gh-pages") + git(destination, "remote", "add", "origin", str(remote)) + + builds = [] + + def build(*, ref, output, repo): + builds.append(ref) + rendered_guide(output) + return postprocess( + output, + version=ref if ref.startswith("v") else "main", + source_sha=publisher.resolve(repo, ref), + controller_sha=publisher.resolve(source, "HEAD"), + renderer="1.9.36", + lock_sha256="c" * 64, + ) + + monkeypatch.chdir(source) + monkeypatch.setenv("GITHUB_REPOSITORY", "NVIDIA/cuPhoton") + monkeypatch.setenv("GITHUB_REF", "refs/heads/main") + monkeypatch.setenv("GITHUB_EVENT_NAME", "workflow_dispatch") + monkeypatch.setenv("GITHUB_SHA", sha) + monkeypatch.setattr(publisher, "clone_archive", clone) + monkeypatch.setattr(publisher, "docs_build", build) + monkeypatch.setattr(publisher, "releases", lambda: [release()]) + monkeypatch.setattr(publisher, "has_guide", lambda tag: True) + return SimpleNamespace( + source=source, + remote=remote, + sha=sha, + builds=builds, + root=tmp_path, + clone=clone, + ) + + +def test_prepare_retries_retained_main_after_deployment_failure( + publication, monkeypatch +): + first = publication.root / "first" + result = publisher.prepare(tag="main", output=first) + assert result["catalog"]["preferred"] == "main" + hashes = file_hashes(first) + assert len(publication.builds) == 1 + # Pages could fail after retention. Recovery must work even if rendering + # is temporarily unavailable and must preserve the complete artifact. + monkeypatch.setattr( + publisher, "docs_build", lambda **kwargs: pytest.fail("must reuse") + ) + retry = publication.root / "retry" + recovered = publisher.prepare(tag="main", output=retry) + assert recovered["archive_sha"] == result["archive_sha"] + assert file_hashes(retry) == hashes + assert not (retry / ".git").exists() + + +def test_prepare_duplicate_release_and_next_main_preserve_history( + publication, monkeypatch +): + first = publication.root / "first" + original = publisher.prepare(tag="v0.2.0", output=first) + release_hashes = file_hashes(first / "v0.2.0") + assert len(publication.builds) == 2 # Bootstrap main and the release. + duplicate = publisher.prepare( + tag="v0.2.0", output=publication.root / "duplicate" + ) + assert duplicate["archive_sha"] == original["archive_sha"] + assert len(publication.builds) == 2 + (publication.source / "source.txt").write_text("next source\n") + git(publication.source, "commit", "-qam", "next source") + sha = git(publication.source, "rev-parse", "HEAD") + monkeypatch.setenv("GITHUB_SHA", sha) + updated = publication.root / "updated" + publisher.prepare(tag="main", output=updated) + assert len(publication.builds) == 3 + assert file_hashes(updated / "v0.2.0") == release_hashes + assert publisher.docs_check(updated)["stable"] == "v0.2.0" + + +def test_prepare_rejects_moved_tag_without_pushing(publication, monkeypatch): + first = publication.root / "first" + original = publisher.prepare(tag="v0.2.0", output=first) + (publication.source / "source.txt").write_text("different source\n") + git(publication.source, "commit", "-qam", "different source") + sha = git(publication.source, "rev-parse", "HEAD") + monkeypatch.setenv("GITHUB_SHA", sha) + git(publication.source, "tag", "-f", "v0.2.0") + output = publication.root / "rejected" + with pytest.raises(ValueError, match="conflicts with the current tag"): + publisher.prepare(tag="v0.2.0", output=output) + assert not output.exists() + assert ( + git(publication.remote, "rev-parse", "gh-pages") + == original["archive_sha"] + ) + + +@pytest.mark.parametrize("failure", ["build", "eligibility", "push"]) +def test_prepare_failure_does_not_change_retained_site( + publication, monkeypatch, failure +): + original = publisher.prepare( + tag="main", output=publication.root / "first" + ) + if failure == "build": + + def broken_build(**kwargs): + raise RuntimeError("renderer failed") + + monkeypatch.setattr(publisher, "docs_build", broken_build) + elif failure == "eligibility": + records = iter([[release()], [release(draft=True)]]) + monkeypatch.setattr(publisher, "releases", lambda: next(records)) + else: + real_git = publisher.git + + def broken_push(repo, *args): + if "push" in args: + raise RuntimeError("push failed") + return real_git(repo, *args) + + monkeypatch.setattr(publisher, "git", broken_push) + output = publication.root / "failed" + with pytest.raises(RuntimeError): + publisher.prepare(tag="v0.2.0", output=output) + assert not output.exists() + assert ( + git(publication.remote, "rev-parse", "gh-pages") + == original["archive_sha"] + ) diff --git a/dev/tests/test_publisher.py b/dev/tests/test_publisher.py new file mode 100644 index 00000000..88dcfa32 --- /dev/null +++ b/dev/tests/test_publisher.py @@ -0,0 +1,213 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 +"""Publication eligibility, isolated builds, and workflow correlation.""" + +from pathlib import Path + +import pytest + +from cuphoton_dev import build, github, publisher + + +def release(tag="v0.2.0", **changes): + return { + "tag_name": tag, + "draft": False, + "prerelease": False, + "published_at": "2026-11-11T00:00:00Z", + "html_url": "https://example.test/release", + **changes, + } + + +@pytest.mark.parametrize( + "changes", + [ + {"draft": True}, + {"prerelease": True}, + {"published_at": None}, + {"tag_name": "v0.2.0rc0"}, + {"tag_name": "v01.2.0"}, + ], +) +def test_ineligible(changes): + assert not github.eligible(release(**changes)) + + +def test_promotion(): + assert not github.eligible(release(prerelease=True)) + assert github.eligible(release(prerelease=False)) + + +def test_build_environment_does_not_use_controller(monkeypatch, tmp_path): + for key in ( + "PYTHONPATH", + "PYTHONHOME", + "VIRTUAL_ENV", + "UV_PROJECT_ENVIRONMENT", + "UV_PROJECT", + "UV_WORKING_DIR", + "JUPYTER_PATH", + "QUARTO_PROFILE", + "GH_TOKEN", + "GITHUB_TOKEN", + "SETUPTOOLS_SCM_PRETEND_VERSION", + ): + monkeypatch.setenv(key, "/controller") + env = build.render_environment(tmp_path) + assert env["QUARTO_PYTHON"] == str(tmp_path / ".venv/bin/python") + assert env["UV_PROJECT_ENVIRONMENT"] == str(tmp_path / ".venv") + assert env["CUPHOTON_REPO"] == str(tmp_path) + assert "PYTHONPATH" not in env + assert "VIRTUAL_ENV" not in env + assert env["CUDA_VISIBLE_DEVICES"] == "" + assert "GH_TOKEN" not in env + assert "GITHUB_TOKEN" not in env + assert "SETUPTOOLS_SCM_PRETEND_VERSION" not in env + assert env["PATH"].startswith(str(tmp_path / ".venv/bin") + ":") + assert env["JUPYTER_PATH"] == str(tmp_path / ".venv/share/jupyter") + + +def test_dispatch_exact_run_id(monkeypatch): + calls = [] + + def api(path, *, data=None, **kwargs): + calls.append((path, data)) + if data: + assert data["ref"] == "main" + assert data["inputs"]["tag"] == "main" + return {"workflow_run_id": 123} + assert path.endswith("/123") + return { + "status": "in_progress", + "conclusion": None, + "head_sha": "abc", + "html_url": "https://example.test/runs/123", + } + + monkeypatch.setattr(github, "api", api) + result = github.docs_publish(ref="main", wait=False) + assert result["run_id"] == 123 + assert result["conclusion"] is None + assert len(calls) == 2 + + +def test_legacy_dispatch_correlates_unique_request(monkeypatch): + request_id = None + + def api(path, *, data=None, **kwargs): + nonlocal request_id + if data: + request_id = data["inputs"]["request_id"] + return None + if "workflow_dispatch" in path: + return { + "workflow_runs": [ + {"id": 999, "display_title": "unrelated"}, + {"id": 123, "display_title": f"docs main / {request_id}"}, + ] + } + assert path.endswith("/123") + return { + "status": "completed", + "conclusion": "success", + "head_sha": "abc", + "html_url": "https://example.test/runs/123", + } + + monkeypatch.setattr(github, "api", api) + assert github.docs_publish(ref="main")["run_id"] == 123 + + +def test_failed_run_propagates_url(monkeypatch): + monkeypatch.setattr( + github, + "api", + lambda *a, **k: { + "status": "completed", + "conclusion": "failure", + "head_sha": "abc", + "html_url": "https://example.test/runs/123", + }, + ) + with pytest.raises( + RuntimeError, match="failure: https://example.test/runs/123" + ): + github.wait_for_run( + github.REPOSITORY, 123, wait=True, request_id="test" + ) + + +def test_draft_cannot_dispatch(monkeypatch): + monkeypatch.setattr(github, "releases", lambda *a: [release(draft=True)]) + monkeypatch.setattr( + github, "api", lambda *a, **k: pytest.fail("must not dispatch") + ) + with pytest.raises(ValueError, match="published final"): + github.docs_publish(ref="v0.2.0") + + +def test_status_reports_unavailable_and_draft(monkeypatch): + monkeypatch.setattr( + github, + "published_catalog", + lambda: { + "stable": "v0.2.0", + "versions": [{"version": "main"}, {"version": "v0.2.0"}], + }, + ) + monkeypatch.setattr( + github, + "releases", + lambda *a: [ + release("v0.1.3"), + release(), + release("v0.2.1", draft=True), + release("v0.3.0"), + ], + ) + monkeypatch.setattr(github, "has_guide", lambda tag, *a: tag != "v0.1.3") + result = github.docs_status() + assert [r["state"] for r in result["releases"]] == [ + "unavailable", + "published", + "ineligible", + "missing", + ] + + +def test_release_pagination(monkeypatch): + pages = iter([[release()] * 100, [release("v0.1.3")]]) + monkeypatch.setattr(github, "api", lambda *a: next(pages)) + assert len(github.releases()) == 101 + + +def test_prepare_rejects_tag_workflow(monkeypatch, tmp_path): + monkeypatch.setenv("GITHUB_REPOSITORY", github.REPOSITORY) + monkeypatch.setenv("GITHUB_REF", "refs/tags/v0.2.0") + monkeypatch.setenv("GITHUB_EVENT_NAME", "release") + with pytest.raises(ValueError, match="canonical main"): + publisher.prepare(tag="v0.2.0", output=tmp_path / "site") + + +def test_build_failure_preserves_existing_output(tmp_path): + output = tmp_path / "output" + output.mkdir() + (output / "index.html").write_text("previous") + with pytest.raises(ValueError, match="already exists"): + build.docs_build(ref="main", output=output, repo=Path.cwd()) + assert (output / "index.html").read_text() == "previous" + + +def test_build_progress_supports_core_captured_streams(): + import io + import sys + from contextlib import redirect_stderr + + progress = io.StringIO() + with redirect_stderr(progress): + build.run( + [sys.executable, "-c", "print('render progress')"], capture=False + ) + assert progress.getvalue() == "render progress\n" diff --git a/dev/tests/test_release_hook.py b/dev/tests/test_release_hook.py new file mode 100644 index 00000000..d4b246fb --- /dev/null +++ b/dev/tests/test_release_hook.py @@ -0,0 +1,68 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import json +import os +import subprocess +from pathlib import Path + +import pytest +import yaml + +HOOK = ( + Path(__file__).resolve().parents[2] / ".github/workflows/release-docs.yml" +) + + +@pytest.mark.parametrize( + ("tag", "dispatch"), + [ + ("v0.2.0", True), + ("v1.20.301", True), + ("v0.2.0rc0", False), + ("v0.2.0-rc.1", False), + ("v01.2.0", False), + ("0.2.x", False), + ("v0.2.0; touch injected", False), + ], +) +def test_hook_dispatches_only_final_tags_on_main(tmp_path, tag, dispatch): + workflow = yaml.safe_load(HOOK.read_text()) + script = workflow["jobs"]["forward"]["steps"][0]["run"] + # Execute the actual hook with a recording CLI, without network access. + gh = tmp_path / "gh" + gh.write_text( + "#!/usr/bin/env python3\n" + "import json, os, pathlib, sys\n" + "pathlib.Path(os.environ['CALL_FILE']).write_text(" + "json.dumps(sys.argv[1:]))\n" + ) + gh.chmod(0o755) + call = tmp_path / "call.json" + env = { + **os.environ, + "PATH": f"{tmp_path}{os.pathsep}{os.environ['PATH']}", + "CALL_FILE": str(call), + "GITHUB_REPOSITORY": "NVIDIA/cuPhoton", + "RELEASE_TAG": tag, + } + subprocess.run( + ["bash", "-e", "-o", "pipefail", "-c", script], env=env, check=True + ) + assert call.exists() == dispatch + if dispatch: + assert json.loads(call.read_text()) == [ + "workflow", + "run", + "docs.yml", + "--repo", + "NVIDIA/cuPhoton", + "--ref", + "main", + "--field", + f"tag={tag}", + ] + assert not (tmp_path / "injected").exists() diff --git a/dev/tests/test_renderers.py b/dev/tests/test_renderers.py new file mode 100644 index 00000000..1e7fbadb --- /dev/null +++ b/dev/tests/test_renderers.py @@ -0,0 +1,85 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import hashlib +import io +import tarfile + +import pytest + +from cuphoton_dev import renderers + + +def test_matching_installed_renderer_does_not_use_network( + tmp_path, monkeypatch +): + binary = tmp_path / "quarto" + binary.write_text("#!/bin/sh\nprintf '1.9.36\\n'\n") + binary.chmod(0o755) + monkeypatch.setattr(renderers.shutil, "which", lambda name: str(binary)) + monkeypatch.setattr( + renderers, "urlopen", lambda *a, **k: pytest.fail("must not download") + ) + scratch = tmp_path / "unused" + assert renderers.renderer_for("1.9.36", scratch) == binary + assert not scratch.exists() + + +def test_unknown_renderer_requires_controller_update(tmp_path, monkeypatch): + monkeypatch.setattr( + renderers.shutil, "which", lambda name: pytest.fail("unsupported pin") + ) + with pytest.raises(ValueError, match="Unsupported Quarto 99.0.0"): + renderers.renderer_for("99.0.0", tmp_path) + + +@pytest.mark.parametrize("checksum_matches", [True, False]) +def test_mismatch_downloads_and_verifies_target( + tmp_path, monkeypatch, checksum_matches +): + installed = tmp_path / "quarto-newer" + installed.write_text("#!/bin/sh\nprintf '2.0.0\\n'\n") + installed.chmod(0o755) + monkeypatch.setattr( + renderers.shutil, "which", lambda name: str(installed) + ) + monkeypatch.setattr(renderers.platform, "system", lambda: "Linux") + monkeypatch.setattr(renderers.platform, "machine", lambda: "x86_64") + buffer = io.BytesIO() + binary = b"#!/bin/sh\nprintf '1.9.36\\n'\n" + with tarfile.open(fileobj=buffer, mode="w:gz") as package: + member = tarfile.TarInfo("quarto-1.9.36/bin/quarto") + member.size = len(binary) + member.mode = 0o755 + package.addfile(member, io.BytesIO(binary)) + payload = buffer.getvalue() + expected = ( + hashlib.sha256(payload).hexdigest() if checksum_matches else "0" * 64 + ) + monkeypatch.setattr( + renderers, "RENDERERS", {"1.9.36": {"amd64": expected}} + ) + urls = [] + + def download(url, **kwargs): + urls.append(url) + return io.BytesIO(payload) + + monkeypatch.setattr(renderers, "urlopen", download) + scratch = tmp_path / "render" + if checksum_matches: + executable = renderers.renderer_for("1.9.36", scratch) + assert executable.is_relative_to(scratch) + assert renderers._version(executable) == "1.9.36" + assert installed.read_text() == "#!/bin/sh\nprintf '2.0.0\\n'\n" + else: + with pytest.raises(ValueError, match="checksum mismatch"): + renderers.renderer_for("1.9.36", scratch) + assert not (scratch / "quarto-1.9.36-amd64/quarto-1.9.36").exists() + assert urls == [ + "https://github.com/quarto-dev/quarto-cli/releases/download/" + "v1.9.36/quarto-1.9.36-linux-amd64.tar.gz" + ] diff --git a/dev/tests/test_transforms.py b/dev/tests/test_transforms.py new file mode 100644 index 00000000..49c2200c --- /dev/null +++ b/dev/tests/test_transforms.py @@ -0,0 +1,258 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import json +import os +from pathlib import Path + +import pytest +from bs4 import BeautifulSoup + +from cuphoton_dev.transforms import SITE_URL, check_snapshot, postprocess + + +def rendered_guide(path: Path, *, extra_page: bool = False) -> Path: + """Small Quarto-shaped fixture preserving v0.2.0's split syntax spans.""" + path.mkdir(parents=True) + pages = { + "index.html": ( + "

    The main image calculations remain unchanged.

    " + '
    Install' + ), + "install.html": ( + '
    '
    +            'git clone '
    +            "https://github.com/NVIDIA/cuPhoton.git\n"
    +            'cd cuPhoton
    ' + "

    This clones the development branch, " + "which this guide describes. " + "To use a published version instead, pick its tag from " + '' + "Releases, " + "add --branch TAG to the clone command, and use the " + "documentation in that checkout.

    " + ), + "reference.html": ( + "

    The links point to the repository’s " + "main branch, " + "which can be newer than this guide.

    " + 'API' + 'Other' + 'Raw' + ), + } + if extra_page: + pages["nested/example.html"] = ( + 'Home

    New

    ' + ) + for name, body in pages.items(): + file = path / name + file.parent.mkdir(parents=True, exist_ok=True) + file.write_text( + "cuPhoton" + "
    " + body + "
    " + ) + (path / "search.json").write_text( + json.dumps( + [ + { + "href": name, + "objectID": name, + "text": BeautifulSoup(body, "html.parser").get_text(), + } + for name, body in pages.items() + ] + ) + ) + (path / "sitemap.xml").write_text( + '' + + "".join(f"{SITE_URL}{name}" for name in pages) + + "" + ) + return path + + +def snapshot( + path: Path, version: str = "main", sha: str = "a" * 40, **kwargs +) -> Path: + rendered_guide(path, **kwargs) + postprocess( + path, + version=version, + source_sha=sha, + controller_sha="b" * 40, + renderer="1.9.36", + lock_sha256="c" * 64, + ) + return path + + +def test_release_conversion_preserves_unrelated_main_and_markup(tmp_path): + path = snapshot(tmp_path / "render", "v0.2.0", extra_page=True) + install = BeautifulSoup( + (path / "install.html").read_text(), "html.parser" + ) + assert ( + "git clone --branch v0.2.0 --single-branch https://github.com/NVIDIA/cuPhoton.git" + in install.code.get_text() + ) + assert install.find(id="cb1-1") is not None + assert "This clones release v0.2.0" in install.get_text() + reference = (path / "reference.html").read_text() + assert "/cuPhoton/blob/v0.2.0/" in reference + assert "/cuPhoton/v0.2.0/README.md" in reference + assert "/another/project/blob/main/" in reference + assert ( + "The main image calculations remain unchanged" + in (path / "index.html").read_text() + ) + assert "development branch" not in (path / "search.json").read_text() + receipt = check_snapshot(path) + assert receipt["lock_sha256"] == "c" * 64 + assert "clone-the-repository" in receipt["pages"]["install.html"] + nested = BeautifulSoup( + (path / "nested/example.html").read_text(), "html.parser" + ) + assert ( + nested.select_one("script[data-catalog]")["data-catalog"] + == "../../versions.json" + ) + assert ( + nested.select_one('link[rel="canonical"]')["href"] + == SITE_URL + "v0.2.0/nested/example.html" + ) + + +def test_main_keeps_authored_install_and_source_links(tmp_path): + path = snapshot(tmp_path / "main") + assert "development branch" in (path / "install.html").read_text() + assert "/cuPhoton/blob/main/" in (path / "reference.html").read_text() + assert "main (development)" in (path / "index.html").read_text() + + +@pytest.mark.parametrize("mutation", ["wording", "clone", "search", "link"]) +def test_release_conversion_fails_on_changed_contract(tmp_path, mutation): + path = rendered_guide(tmp_path / "render") + file = path / ("search.json" if mutation == "search" else "install.html") + text = file.read_text() + if mutation == "wording": + text = text.replace( + "This clones the development branch", "This checks out main" + ) + elif mutation == "clone": + text = text.replace("git clone", "git clone") + elif mutation == "search": + text = text.replace( + "This clones the development branch", + "This clones the development branch (updated)", + ) + else: + text = text.replace( + "", 'Missing' + ) + file.write_text(text) + with pytest.raises(ValueError): + postprocess( + path, + version="v0.2.0", + source_sha="a", + controller_sha="b", + renderer="test", + ) + + +def test_checks_detect_tampering_and_external_asset_escape(tmp_path): + path = snapshot(tmp_path / "render") + (path / "index.html").write_text("tampered") + with pytest.raises(ValueError, match="hashes"): + check_snapshot(path) + path2 = rendered_guide(tmp_path / "other") + (path2 / "index.html").write_text( + (path2 / "index.html") + .read_text() + .replace("", '') + ) + with pytest.raises(ValueError, match="Missing local target"): + postprocess( + path2, + version="v0.2.0", + source_sha="a", + controller_sha="b", + renderer="test", + ) + + +def test_source_contract_tracks_guide_inputs(tmp_path): + """Keep authored instructions synchronized with conversion fixtures.""" + guide = Path(__file__).parents[2] / "docs" / "guide" + install = (guide / "install.qmd").read_text() + reference = (guide / "reference.qmd").read_text() + fixture = rendered_guide(tmp_path / "fixture") + paragraph = ( + next( + line + for line in install.splitlines() + if line.startswith("This clones") + ) + .replace( + "[Releases](https://github.com/NVIDIA/cuPhoton/releases)", + "Releases", + ) + .replace("`", "") + ) + fixture_html = BeautifulSoup( + (fixture / "install.html").read_text(), "html.parser" + ) + assert fixture_html.p.get_text() == paragraph + assert "git clone https://github.com/NVIDIA/cuPhoton.git" in install + assert ( + "This clones the development branch, which this guide describes." + in install + ) + assert ( + "The links point to the repository's `main` branch, " + "which can be newer than this guide." in reference + ) + + +@pytest.mark.parametrize("link", ["symbolic", "hard"]) +def test_snapshot_rejects_links_that_pages_cannot_upload(tmp_path, link): + path = rendered_guide(tmp_path / "render") + target = path / "linked.html" + if link == "symbolic": + target.symlink_to("index.html") + else: + os.link(path / "index.html", target) + with pytest.raises(ValueError, match="link"): + postprocess( + path, + version="main", + source_sha="a", + controller_sha="b", + renderer="test", + ) + + +@pytest.mark.parametrize("location", ["html", "search"]) +def test_snapshot_rejects_missing_bookmarks(tmp_path, location): + path = rendered_guide(tmp_path / "render") + file = path / ("index.html" if location == "html" else "search.json") + text = file.read_text() + if location == "html": + text = text.replace("#clone-the-repository", "#missing") + else: + records = json.loads(text) + records[0]["href"] = "install.html#missing" + text = json.dumps(records) + file.write_text(text) + with pytest.raises(ValueError, match="bookmark"): + postprocess( + path, + version="main", + source_sha="a", + controller_sha="b", + renderer="test", + ) diff --git a/dev/uv.lock b/dev/uv.lock new file mode 100644 index 00000000..dd124afb --- /dev/null +++ b/dev/uv.lock @@ -0,0 +1,741 @@ +version = 1 +revision = 3 +requires-python = ">=3.12, <3.15" + +[[package]] +name = "astropy" +version = "8.0.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "astropy-iers-data" }, + { name = "numpy" }, + { name = "packaging" }, + { name = "pyerfa" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/95/57/02089e6da0fc00846d309034ad74e13ebcadc67b1c5cef397ae0597473fa/astropy-8.0.2.tar.gz", hash = "sha256:e6af35823099ad6a40b57dbe5ff845f577374ea131925c9fa4b49eeab06c5310", size = 7178167, upload-time = "2026-10-15T21:44:45.383Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/be/ac/2a62e03b4bfb9dd679693cf8b149d202683005b8f5b75386f10e40c2f618/astropy-8.0.2-cp311-abi3-macosx_10_9_x86_64.whl", hash = "sha256:3d8492ac4987e2a0634610e387b14b79962b15e8dc5d51667d9100f770aa86e7", size = 6665519, upload-time = "2026-10-15T21:44:23.81Z" }, + { url = "https://files.pythonhosted.org/packages/3d/8c/a6b8e81d87268d79f3a7ed3e5deeaee8d96908f1b59955b0e36ea5e47b69/astropy-8.0.2-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:fd67922cca66b7557b58dfcc2271f3871957d85e67c65e712a129ce04ad9ed51", size = 6652674, upload-time = "2026-10-15T21:44:26.32Z" }, + { url = "https://files.pythonhosted.org/packages/cb/1a/0944850807ebddc690eb77dc07e8dbf7865c7dcdd86bcb81d2ff133e4e38/astropy-8.0.2-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d0e63e0011cc984426c478da8601fe177975fe4cb0b2a059ee88d26d60a0890f", size = 10405557, upload-time = "2026-10-15T21:44:29.516Z" }, + { url = "https://files.pythonhosted.org/packages/42/c2/0e9849f6591dd113a1f217e061a9be1de766819bc076c7c7c8cb24851432/astropy-8.0.2-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:000d6998bcf4f097257b3776f29f1dafde0967bf1b091edbad95df564eee4eea", size = 10419022, upload-time = "2026-10-15T21:44:32.115Z" }, + { url = "https://files.pythonhosted.org/packages/5d/2a/1d84743c8be16846f8fbdc21b0af6f8ed1cff1db02026e19a4bf0cd3a87a/astropy-8.0.2-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:f462b80fe16e0603e813efd1098d4d6d94a487e64f95e2d9699e46b641577f8b", size = 10373480, upload-time = "2026-10-15T21:44:34.825Z" }, + { url = "https://files.pythonhosted.org/packages/ba/03/02f928891fdb2a89a7bdf10afc958e7c5c255c711d462e6b6aa0d387f95b/astropy-8.0.2-cp311-abi3-win32.whl", hash = "sha256:57b2388a229ec572437c5786e0387cb21a08ffe6001e5422ae59d2b8b9242001", size = 6412912, upload-time = "2026-10-15T21:44:37.63Z" }, + { url = "https://files.pythonhosted.org/packages/f4/ec/bfb4be449c689a0d80aa1b02cfa7c34e709556c9b58d8022366d67017d4a/astropy-8.0.2-cp311-abi3-win_amd64.whl", hash = "sha256:8baaf4451dc4fdbdf635e033378cbb626a9fd4755803c8fdc30ef520fb1688ba", size = 6547000, upload-time = "2026-10-15T21:44:40.442Z" }, + { url = "https://files.pythonhosted.org/packages/1b/00/4dfc968f9560fafee2cc04c31fb3abd9e39fd1bac7b0f81bf495db0c5740/astropy-8.0.2-cp311-abi3-win_arm64.whl", hash = "sha256:0827b3f83edbae1bda32ad5ab92d0b85f78dc71cfc2fd5c843c30d57de96d4cb", size = 6427839, upload-time = "2026-10-15T21:44:42.914Z" }, +] + +[[package]] +name = "astropy-iers-data" +version = "0.2026.11.9.0.35.9" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/c4/29/195d78d3549fec3a7e89c8c7bd269ecfbadfcc2a856b8e0cf9a2c8600aed/astropy_iers_data-0.2026.11.9.0.35.9.tar.gz", hash = "sha256:8454817ba4cca74a66892ddcafc1e51a31f0264698005c9a697365f1bbb8c19e", size = 2009678, upload-time = "2026-11-09T00:36:15.511Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3b/16/e2ee2334839669a21dbd23c33686619147f41ac5c5e29fb0c745ee4ae001/astropy_iers_data-0.2026.11.9.0.35.9-py3-none-any.whl", hash = "sha256:4fbe5b414c5183496b92d300160e4fcdb4f2cc25f8731f23028a0a21a9153f8c", size = 2007670, upload-time = "2026-11-09T00:36:13.313Z" }, +] + +[[package]] +name = "beautifulsoup4" +version = "4.15.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "soupsieve" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/43/65/318323f98dbee45d42dff61d8f047181bc6f2268a9068cfad035a46be5af/beautifulsoup4-4.15.0.tar.gz", hash = "sha256:288e3ca7d54b06f2ac191970bc275c1939cb46d450b255bf6718b04aa37ab4f7", size = 632571, upload-time = "2026-06-07T16:44:20.453Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/88/c6/92fcd42f1ba33e1184263f25bfabf3d27c383410470f169e4b8163bf9c17/beautifulsoup4-4.15.0-py3-none-any.whl", hash = "sha256:d6f88de62e1d4e38ecb1077eb9724cd0eff29d2a08ca16a401e9b9e93f117cf9", size = 109924, upload-time = "2026-06-07T16:44:21.566Z" }, +] + +[[package]] +name = "colorama" +version = "0.4.6" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" }, +] + +[[package]] +name = "coverage" +version = "7.17.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/78/4a/740c3134227763ebc30a226d7f2f29b25e35898d162dd8b2dd792be83fb2/coverage-7.17.2.tar.gz", hash = "sha256:d05a1bef52f4d7f1b484a1cf46a8929e50963f910e51396373f06cd3b6248f38", size = 996756, upload-time = "2026-11-04T19:52:34.313Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/22/6a/a51808ac625c457326fb37b174d35e1badb1324c6def5d9668089c4b14ef/coverage-7.17.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:289a24443352713745f79c1b6aae4e99ced2f5ff3e86bb630c33c631d50f217c", size = 227838, upload-time = "2026-11-04T19:49:49.546Z" }, + { url = "https://files.pythonhosted.org/packages/31/24/f32ec1a5ef947294252e77c5d40ac0903ba1de4c92638edfcca8629c067f/coverage-7.17.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:da4b0aef427eb96e422b444e5c2c3d38768fedb9141346294c38717a8b15b416", size = 228060, upload-time = "2026-11-04T19:49:51.221Z" }, + { url = "https://files.pythonhosted.org/packages/01/8e/3097367327c69e65521b9d9bf8b9d2ddecefa8c21bd08e17bc068bd3db93/coverage-7.17.2-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:90c6c5f93606b8803bd7f8a0b2ae05df7e35da4504a1c53cfe9294a1731e1f49", size = 260359, upload-time = "2026-11-04T19:49:52.756Z" }, + { url = "https://files.pythonhosted.org/packages/73/65/774fc4ec86807b6ee66b46465bc49b34bb6d291e9bff6ddfa9708ccb4053/coverage-7.17.2-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:36314997533266bde3d07765289674304d61bfe49165bb1b4fa9be12cb4ba0d1", size = 263687, upload-time = "2026-11-04T19:49:54.351Z" }, + { url = "https://files.pythonhosted.org/packages/d8/72/17b5df5d8211e1880169b93197ba98b21b30ccf8f116284536113b7582c5/coverage-7.17.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1682d98ded28524bc6853cc4e7c65175b3e917f38b2e2ddebb28cafd8ab4de74", size = 264220, upload-time = "2026-11-04T19:49:56.172Z" }, + { url = "https://files.pythonhosted.org/packages/de/0c/603ba7fff1aa4c8064fdf4a1fff6d9fb51c72a5828429dfe858be48e38b3/coverage-7.17.2-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8eab0a5cff8dbc563d1416a6e079ba3c146712e47167c022a5df5ea01bd76df9", size = 266498, upload-time = "2026-11-04T19:49:57.718Z" }, + { url = "https://files.pythonhosted.org/packages/f4/ca/f2ae6e47e18b35a0dbddb9d8f51be34a6d66b41120f2e0f7363ccc0812f4/coverage-7.17.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:635337a96895f2ffcfe2aa7554468a988f468fb67a8007c1a65e95148c1855a9", size = 260591, upload-time = "2026-11-04T19:49:59.159Z" }, + { url = "https://files.pythonhosted.org/packages/b2/4b/b09540a46395a6a1052ad114bf366e383c64e223374f4911a85620667930/coverage-7.17.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:79cd2d9742419b6d1aaeb1f3fb77a8e6a01c09ebe5bd1b27011752410a5e3781", size = 262107, upload-time = "2026-11-04T19:50:00.607Z" }, + { url = "https://files.pythonhosted.org/packages/ec/c4/42783cb43481fafafffbc7be7fe6026258ffd30a575707733109c9ef0679/coverage-7.17.2-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:b0209fff1ca92f1e2e344d54b5b3def74efbdb46ba807cd81976a5e9e569cac3", size = 260271, upload-time = "2026-11-04T19:50:02.06Z" }, + { url = "https://files.pythonhosted.org/packages/37/07/192ee81dd1ec4da58ae0f03fdd0045d2b821007e4194f7704d6e495733f0/coverage-7.17.2-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:7a3984fb8c2407721f9bc05573fc9a770752efc756d55068ccbde1fe53e42233", size = 264320, upload-time = "2026-11-04T19:50:03.613Z" }, + { url = "https://files.pythonhosted.org/packages/dd/94/8d983310d98299a19ba23efbb324492f4bf8d8668d610eacd304e451f138/coverage-7.17.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:698ca1575135215be25ac9c5d14f0b5455135d29602b7ee81e511d64a0435c85", size = 259774, upload-time = "2026-11-04T19:50:05.363Z" }, + { url = "https://files.pythonhosted.org/packages/1a/85/6c923d71c76566c6c65a2af104d39d69d44ae708a700de017e6c56fedfc6/coverage-7.17.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:686b6f8f9e57afc3a44096b17ee8de7e11e0a12f2da819e25047af1eb3b0fc6f", size = 262258, upload-time = "2026-11-04T19:50:06.807Z" }, + { url = "https://files.pythonhosted.org/packages/54/f9/fd3c37b09891bfdfece486a6145345bf2b32332045a678afd293a7f2f05d/coverage-7.17.2-cp312-cp312-win32.whl", hash = "sha256:ee083412170118074bcc74361fcbc7104eb6d0b7c9c75eb3b84a4c324410c531", size = 229659, upload-time = "2026-11-04T19:50:08.184Z" }, + { url = "https://files.pythonhosted.org/packages/dc/b8/4d395163c9bfae0e991abbd14dea9c9bbb4ade904e5f297cbfb7b8150216/coverage-7.17.2-cp312-cp312-win_amd64.whl", hash = "sha256:e269dddf5ebac20dfcc5a2a459528a9d221ab828cb31dfdf19c7cfacdbcee673", size = 230240, upload-time = "2026-11-04T19:50:09.715Z" }, + { url = "https://files.pythonhosted.org/packages/a3/02/1024b8d4f60a9ecc0ee41a6000425caa63855d63e51da84c93c0b1dff894/coverage-7.17.2-cp312-cp312-win_arm64.whl", hash = "sha256:bac3c79c31f45274117ed64c65efeaed85665668aeba7d809c7c38801ada6ed4", size = 230043, upload-time = "2026-11-04T19:50:11.187Z" }, + { url = "https://files.pythonhosted.org/packages/e0/32/d750d7b10b0a9436349b3fb78491c5bb8f9b524f01ae6994d935d77d6ab8/coverage-7.17.2-cp313-cp313-android_24_arm64_v8a.whl", hash = "sha256:882cade9b6dc43b2bc819bb444c0a13e4ed1f669a50e0de74adeec54fce486f3", size = 228978, upload-time = "2026-11-04T19:50:12.782Z" }, + { url = "https://files.pythonhosted.org/packages/63/33/468f8c63aff5deef81bfb8e44771f68ebba328c0aa46c8a6ff27dedd0fda/coverage-7.17.2-cp313-cp313-android_24_x86_64.whl", hash = "sha256:f5a875e92f10c6463027d8151459f2d92b4c13527402ed1301eaddabd79d8cf5", size = 229048, upload-time = "2026-11-04T19:50:14.255Z" }, + { url = "https://files.pythonhosted.org/packages/10/91/c8723e48c1497a3c56a3194973a416a6f0fb24560425685f960888e03b20/coverage-7.17.2-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:e8da5e158d13556457f69245deacf6d8401a2c9c31afaddd18bea691e849b5fd", size = 227293, upload-time = "2026-11-04T19:50:15.857Z" }, + { url = "https://files.pythonhosted.org/packages/61/4f/2f57b3dc6ef31e12a99e6dcb820c4ab04d973ea1466f73c856bf920a740c/coverage-7.17.2-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:42133a2647982db7968db138c0f4a57f5836101d8d504600a87ef8ebfa22a4cf", size = 227599, upload-time = "2026-11-04T19:50:17.418Z" }, + { url = "https://files.pythonhosted.org/packages/9c/fa/967e829238dda21c4bce17aef2f739187678c8e6e6fc880a8454945a7433/coverage-7.17.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e6c89d63d43738712ce1febddb7758ffeb56de08f1b2be68aeb9a9c7fee712c7", size = 227727, upload-time = "2026-11-04T19:50:18.924Z" }, + { url = "https://files.pythonhosted.org/packages/9d/df/803ba08e8937759dc3f18b93ece82f81b2fb446e3846e4d60a06a4e77647/coverage-7.17.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f94d465ee00ebe694ca866d66bbe45fa04618b1afcb377de934694f624fa7cf6", size = 227987, upload-time = "2026-11-04T19:50:20.867Z" }, + { url = "https://files.pythonhosted.org/packages/4a/12/92dcd9206e7bb817af42b8663cfeefdbb2c5a6c92cc7069d43e6892bbdeb/coverage-7.17.2-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:7ce0acb27a823e8e5169282f538f0e182854cc8b472b88d45456f09b6fe364fd", size = 259154, upload-time = "2026-11-04T19:50:22.328Z" }, + { url = "https://files.pythonhosted.org/packages/48/2d/6b028df8050caef4ce0df177686c92dba16ab7cf004040e5518f95b57021/coverage-7.17.2-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:70daa8e4b49541b51c0baeba0d802b0d14d3214daeebc071b3db0b0c7dc84646", size = 262065, upload-time = "2026-11-04T19:50:23.745Z" }, + { url = "https://files.pythonhosted.org/packages/62/c3/429b500937ac446e36fcce517d040b0b8bd04a4bfa087bdf864175553fea/coverage-7.17.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:95bd8dc5b356f78f10a967ec50f8902d56f24c623753ac9fce0aba9d6213d5c5", size = 262997, upload-time = "2026-11-04T19:50:25.223Z" }, + { url = "https://files.pythonhosted.org/packages/c1/91/263224a77de3ab1ee42d110b09f1ac9a02638794d3e002a859822638256a/coverage-7.17.2-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a5565a9dd715a5a94ffcf9a0ad4b6b1501b5441fd67d660e78742adff5d37a0a", size = 265062, upload-time = "2026-11-04T19:50:26.829Z" }, + { url = "https://files.pythonhosted.org/packages/0f/44/99b72f2961f4ba54ac14ccb016f3b212cc9a9dfda4c37e07a208efe01f9f/coverage-7.17.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:091eba4248d31b03828fc657c96d14adfaa8754f5aec7b73298b82894858db06", size = 259201, upload-time = "2026-11-04T19:50:28.386Z" }, + { url = "https://files.pythonhosted.org/packages/be/a7/e97f63a7c345077e4e398d15e3aa5068edc28cb061f997f71fd0e32703e1/coverage-7.17.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d2742952851c7f88b1484385f68c42c6388153520efb40ff09fc852c3783aa5c", size = 261155, upload-time = "2026-11-04T19:50:29.806Z" }, + { url = "https://files.pythonhosted.org/packages/16/0c/73e470df7db83962e2cdd6c1a7ca7dc8f8632c17a6d378d6d9124ff8bc6b/coverage-7.17.2-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:1da1999e3c371edd669b48a1029c86dc0474cdc6ff152d58cb3f15cb3337af72", size = 259077, upload-time = "2026-11-04T19:50:31.437Z" }, + { url = "https://files.pythonhosted.org/packages/50/43/db8bc1b92d933b0b5f57d0e3377594c4f78ea31e84e8fbc22627fd17ecf4/coverage-7.17.2-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:7804a6022fcd5e1d4de4dc676e985d6aea0119249e88c041e943f3cd07953527", size = 263172, upload-time = "2026-11-04T19:50:33.014Z" }, + { url = "https://files.pythonhosted.org/packages/c4/f4/3e9e5cc9ccc911f8fb9595053da1ce58b9de8941b27e2f2f7058cdfc87f1/coverage-7.17.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:6bdf3821fd0740b5369b9ab58b4e9d0d68a2c5c75a7ee0cd3beb624f9f15e4fa", size = 258926, upload-time = "2026-11-04T19:50:34.513Z" }, + { url = "https://files.pythonhosted.org/packages/72/9f/0d67883bf55adf50424728937cbee54d76fa137817e6bb20f97061d01816/coverage-7.17.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e09c37817768bb71fe3e70b6ce5e6ac1a0cd7398536c2f30a4460218c7b66e93", size = 261006, upload-time = "2026-11-04T19:50:35.956Z" }, + { url = "https://files.pythonhosted.org/packages/a8/22/71965edc14736073b55a40e521791d9233d5c3194fa6887a94f4431fbbcc/coverage-7.17.2-cp313-cp313-win32.whl", hash = "sha256:c10f2a2748dd084e44811bb9b26979763af9003115d9bf93c1da69011944719f", size = 229602, upload-time = "2026-11-04T19:50:37.564Z" }, + { url = "https://files.pythonhosted.org/packages/47/0d/715cb37f51f908a6f6f33fe8c6fc95ab638b17cb014b1650daae0893c160/coverage-7.17.2-cp313-cp313-win_amd64.whl", hash = "sha256:8dc07ed34bcb206f69d5b54fd3874f7bf39ac941c9f7aec2b53b29874fcfd77a", size = 230329, upload-time = "2026-11-04T19:50:38.988Z" }, + { url = "https://files.pythonhosted.org/packages/39/f2/a5099bdc2a530f29c818a1c7e706669451c10e5f0eb62dcff76ef3568668/coverage-7.17.2-cp313-cp313-win_arm64.whl", hash = "sha256:bb74283661a239fdaf738ac0b07db4ed9b476c7532d3e713abf0f6a072781e60", size = 230055, upload-time = "2026-11-04T19:50:40.479Z" }, + { url = "https://files.pythonhosted.org/packages/96/f9/30d6ff7a66e1519d79940fdee542ead9a63601de60be5cc9fe62c74bab58/coverage-7.17.2-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:0439f77deb5c023003533ae8909a9aa1e174c847d655327035b1e542c7c8a54e", size = 229094, upload-time = "2026-11-04T19:50:42.193Z" }, + { url = "https://files.pythonhosted.org/packages/1a/db/82c722c37dce98fe1abc953768903752bdd415dfe8cfeb7b744a7236a735/coverage-7.17.2-cp314-cp314-android_24_x86_64.whl", hash = "sha256:e86a66f96d80c770daeed78394c1d4f6e8d03e5a3e08c5dab5275d56414f296a", size = 229213, upload-time = "2026-11-04T19:50:43.779Z" }, + { url = "https://files.pythonhosted.org/packages/7d/07/71b68d870975776cb185f11cd80e053b01739f3646488fe8b9721744f56a/coverage-7.17.2-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:87b30f3daa0bedda6b770b303410a6def007844772aaa143dc52675b3d95cd8a", size = 227374, upload-time = "2026-11-04T19:50:45.258Z" }, + { url = "https://files.pythonhosted.org/packages/aa/23/ed60f79576175e108c77df2bdc116f46e367aab108542ddeecaab752f0f6/coverage-7.17.2-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:3f219efbc3ec71c377e278dee201633e1d4ad0d2d9bdaddfd9489b2869d584c4", size = 227676, upload-time = "2026-11-04T19:50:47.095Z" }, + { url = "https://files.pythonhosted.org/packages/10/7e/60a51850d3ff659b82cc211bc98fa126aab2ac9b81bd4ed6abc3e3720a09/coverage-7.17.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:36248fb6c03341501169539bcab35eb3a59159100be1246fad3c14cb73c17685", size = 227915, upload-time = "2026-11-04T19:50:48.581Z" }, + { url = "https://files.pythonhosted.org/packages/77/80/a9539c15076fb9b95d8cbdb7f0caec90857d80bddca3eeca439f5e2e64e2/coverage-7.17.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:2a6281011cf85699763bf88ab55e0774f6696f87b390f39152b14ecefadccb59", size = 228072, upload-time = "2026-11-04T19:50:50.073Z" }, + { url = "https://files.pythonhosted.org/packages/7f/3b/0a84b6032511834105fd4f8a8b4e76927783cea03dc4796032d5c4bfec8b/coverage-7.17.2-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:3dfefb1ec16ca1a01e5da40ba162e268ced8bd3624b9eba4e9384ebfa14af7ec", size = 259991, upload-time = "2026-11-04T19:50:51.665Z" }, + { url = "https://files.pythonhosted.org/packages/2e/e4/a3e6b8bcc219b00ea91e36f071c2659b253e5d6e1b258c31eb4524231718/coverage-7.17.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:34e5c7a2da36804c6e6f10b368eae01ad56f5a4ac5ecce7297300a3d46fdef2a", size = 262995, upload-time = "2026-11-04T19:50:53.236Z" }, + { url = "https://files.pythonhosted.org/packages/05/54/a666b65c5bb145d8796b7902ff1c0f60600a6c2a08949e20f2fb7af15de3/coverage-7.17.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e6bf531deaebf8f69ba6015bba3fb817cab6694dfb69ac2a708889dc59a3926e", size = 263980, upload-time = "2026-11-04T19:50:55.366Z" }, + { url = "https://files.pythonhosted.org/packages/a6/73/ac9d06da9e0c143b874a68b17d8dfeedc45acdf1bdcee5b22a42bece098e/coverage-7.17.2-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:88d4dc83b6ad09a2134cad9d8ec780b274b17ac7dfba8c2c6e92e3bc468fe85d", size = 266457, upload-time = "2026-11-04T19:50:57.04Z" }, + { url = "https://files.pythonhosted.org/packages/87/b1/8a500e16cf787383b00b5a86eb50a490b4d8ebde505f92e1aaca515afc0a/coverage-7.17.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8dc17707fd463b4dfab53792e41d50a23316ac6b98539007aa2388a1d44a8535", size = 259768, upload-time = "2026-11-04T19:50:58.508Z" }, + { url = "https://files.pythonhosted.org/packages/f7/be/642762c5973b89e2b8bf66c95778bdd80e96ceea442ae8fa753732597b73/coverage-7.17.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:df0a34d445eea64f3766e9ca2ff57bcde600a89c7c0330434a7a37e8d6e2549f", size = 261831, upload-time = "2026-11-04T19:51:00.25Z" }, + { url = "https://files.pythonhosted.org/packages/e4/b1/f7d6c0ef0a4aecf3f91f19df4ab3fa131fec8c89f554187511716584c9f5/coverage-7.17.2-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:c5a98aff9eb681312ed403ecb7beb5f15fd25d6e0acc2554b9ca4b4d6f0b6705", size = 259871, upload-time = "2026-11-04T19:51:01.776Z" }, + { url = "https://files.pythonhosted.org/packages/c7/c0/3ae087d52cfa5119ad9ecbd193c40089924d1101cef7333f15a86dccb444/coverage-7.17.2-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:7565c17092f2f4021abbe3f5007300c224f362364a388f5ddad9216dab44b611", size = 264169, upload-time = "2026-11-04T19:51:03.365Z" }, + { url = "https://files.pythonhosted.org/packages/c5/95/d324108991f892cb361ef8b2f91bd4cda9c2563e0954247409e9e6b911ab/coverage-7.17.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:555257578e20a46020c27b2af4ef99059cd906aa9b8e163baf9da9a5afb65a64", size = 259502, upload-time = "2026-11-04T19:51:04.91Z" }, + { url = "https://files.pythonhosted.org/packages/14/b5/13a62eac66cecbaaa098bb753a3693b44454a4d21d53db4f1a0953f35f0b/coverage-7.17.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:460ba2139866e758c3a8e9d9422fdc889942bcbc5ccaf710dc4fbd8707d14aa8", size = 261613, upload-time = "2026-11-04T19:51:06.414Z" }, + { url = "https://files.pythonhosted.org/packages/53/13/9ea31cfa72434449b9a98666760169d1e0ab31b3f6cdb12e68149106668e/coverage-7.17.2-cp314-cp314-win32.whl", hash = "sha256:e72cf9556f799c3fce7597c1bd7dbfc9104befbd08088deb3b9ae9fd98117c02", size = 229842, upload-time = "2026-11-04T19:51:08.61Z" }, + { url = "https://files.pythonhosted.org/packages/f6/cc/aa8f34b014979c973740f5a5ed6861ecfc6009082c70e72030ca1519e0f8/coverage-7.17.2-cp314-cp314-win_amd64.whl", hash = "sha256:205f9e329d9d5e47c320f8712326a01620689edae50531cc8934511e2c5e8f7e", size = 230474, upload-time = "2026-11-04T19:51:10.167Z" }, + { url = "https://files.pythonhosted.org/packages/49/64/16afaa19b3886dc157c3c5ebace5241b84b96a005cb28545584e66b80895/coverage-7.17.2-cp314-cp314-win_arm64.whl", hash = "sha256:a5909dd087006c70c128297312ba67d877123e871100645d9bd73ae021a4d01d", size = 230325, upload-time = "2026-11-04T19:51:11.63Z" }, + { url = "https://files.pythonhosted.org/packages/e8/95/acc865e1411c8ebc5c5d230367f3bfed5c605ed54bb41b84fc58f4e7f137/coverage-7.17.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:674bcd023a3743666d4d7a15238e57a00c968553780a36c80d3779fc410b912c", size = 228384, upload-time = "2026-11-04T19:51:13.729Z" }, + { url = "https://files.pythonhosted.org/packages/10/98/02c37c6a928ccfc84b7a43eda44d96d3b1ccbc93989c178754b7e67e7650/coverage-7.17.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ba45dc072bfbf1798e68ec81379b73473fc912174bff9f91924d77711a1d2b30", size = 228758, upload-time = "2026-11-04T19:51:15.394Z" }, + { url = "https://files.pythonhosted.org/packages/28/ab/d503b0aaebb92b171260469463915af5e16a64457b289d4cb844e8c366ac/coverage-7.17.2-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:0d8a5dc709da9b90ad5cc859a9b88c9b801e65ca2fbf7cbdbed5b9cbf457fcc9", size = 268749, upload-time = "2026-11-04T19:51:17.179Z" }, + { url = "https://files.pythonhosted.org/packages/f6/e5/6d6ba15bde22fcccd07e14305be14291d041f732771a73f787297445d3e7/coverage-7.17.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:248873a144c067f981742ff4bbfb48b57e281a8cb7a3821d4e293bdb50b47970", size = 271301, upload-time = "2026-11-04T19:51:18.893Z" }, + { url = "https://files.pythonhosted.org/packages/63/e7/bd6dcec5b8130f5bd8679087a2bc3a50a53c4ee78d5ec449610020088ff3/coverage-7.17.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d0332e2b27fc5cc761d6b8a33118b958e6a46be7f00fd30e03a5cf103350c0b3", size = 273924, upload-time = "2026-11-04T19:51:20.605Z" }, + { url = "https://files.pythonhosted.org/packages/55/c1/b3f06aa1f1c51f4295fdfa6500eb7409aaa6273cf5f27bafc25217f3547d/coverage-7.17.2-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:27fc4384a1154f7df30d304ccddc05ef457368c065670ecbd392606279b3329a", size = 275412, upload-time = "2026-11-04T19:51:22.09Z" }, + { url = "https://files.pythonhosted.org/packages/a7/f0/b68ab3654af3541488b26856e3043c13c782d8e6104fc8149746ecaa83f0/coverage-7.17.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:603140eeae3f9adc562f91b1b98d4d1fc491bd1f66c5082482c568d0b7891bb1", size = 268638, upload-time = "2026-11-04T19:51:23.653Z" }, + { url = "https://files.pythonhosted.org/packages/fd/16/4a9d56bd4ca4572cbd20f9843813623cef1b88b15f979ec4f381704d2f84/coverage-7.17.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:be0fec33b69c40f845c76f67fb4495b62a84da8c31a579dc6e18c5a63fa6a1f3", size = 271211, upload-time = "2026-11-04T19:51:25.678Z" }, + { url = "https://files.pythonhosted.org/packages/78/d2/1c04b38bab92d2b7d62718d170b5bea43755fefee7e29cc056448c433d92/coverage-7.17.2-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:960e199965e506d78f62252355397a05c8cee8072ad2d82d932745517d566539", size = 268638, upload-time = "2026-11-04T19:51:27.262Z" }, + { url = "https://files.pythonhosted.org/packages/26/c9/2c639e9aee78b0522cb3dc245de09685e34b479bcc45d4d2a277d0de1174/coverage-7.17.2-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:d7a363c0788435ff5324d9582d37c63f215c75f974d755cfd6cfc9fbe0e64b04", size = 272935, upload-time = "2026-11-04T19:51:28.96Z" }, + { url = "https://files.pythonhosted.org/packages/79/1f/11bdaf03c1b12f88094b57420b4238d3974ebec6a7d674b645a54e24f90c/coverage-7.17.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:afd81658f17b1a50bbc1d247a61fa435be0be471246136eb946f9cbfc437a4fa", size = 268057, upload-time = "2026-11-04T19:51:30.44Z" }, + { url = "https://files.pythonhosted.org/packages/bb/f6/43d40d1b4d4892e54c68a241cd5b92efed4d5934109e0e5e24a94759f732/coverage-7.17.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:d88fcc24470d73ed4360e910f8549718b913ba56fb8775d9ef929a647835dfea", size = 269986, upload-time = "2026-11-04T19:51:31.913Z" }, + { url = "https://files.pythonhosted.org/packages/8e/33/6874185b791c71684c401fc74abd71bbdb102e8ee41c8f380cf25af41d29/coverage-7.17.2-cp314-cp314t-win32.whl", hash = "sha256:2c42c222939b8699e7bc0e453149627f211ebbbb2f74c1a04331b0cd9834e2c8", size = 230160, upload-time = "2026-11-04T19:51:33.304Z" }, + { url = "https://files.pythonhosted.org/packages/16/e0/9057b4cf962ca6089b144f0d93a748f5e2d13876dd0f33f9d5a2c2ec49d2/coverage-7.17.2-cp314-cp314t-win_amd64.whl", hash = "sha256:b94c509e26603ba7f8cb1bf8bb63967c7be533493be5668d8442cd06ec853d76", size = 231086, upload-time = "2026-11-04T19:51:35.002Z" }, + { url = "https://files.pythonhosted.org/packages/5e/4f/bd626297c942380279dff323e1d8a8937990d553119a4f887358488b1b54/coverage-7.17.2-cp314-cp314t-win_arm64.whl", hash = "sha256:eca90e028932de597e2c50f454ad8cc631281e14d20b9f801a649ab555deb580", size = 230657, upload-time = "2026-11-04T19:51:36.742Z" }, + { url = "https://files.pythonhosted.org/packages/da/91/1805cc144497d76a436f66a21fa57492bee7ed1257826fb992f03b9b2b6f/coverage-7.17.2-py3-none-any.whl", hash = "sha256:e674027ceb6bfd959f1bb035000fd20fa8b717dc6765adaaf8bca347822c8c7d", size = 219280, upload-time = "2026-11-04T19:52:32.726Z" }, +] + +[[package]] +name = "cuphoton" +source = { editable = "../" } +dependencies = [ + { name = "astropy" }, + { name = "h5py" }, + { name = "numpy" }, + { name = "pyarrow" }, + { name = "pyyaml" }, + { name = "scipy" }, +] + +[package.metadata] +requires-dist = [ + { name = "astropy", specifier = ">=7.2.0" }, + { name = "bokeh", marker = "extra == 'viz'", specifier = ">=3.9" }, + { name = "coverage", marker = "extra == 'dev'", specifier = ">=7.10.6,<8" }, + { name = "cuda-bindings", marker = "sys_platform == 'linux' and extra == 'io'", specifier = ">=13,<14" }, + { name = "cuda-pathfinder", marker = "sys_platform == 'linux' and extra == 'io'", specifier = ">=1.5.6,<2" }, + { name = "cuda-tile", marker = "sys_platform == 'linux' and extra == 'cutile'", specifier = ">=1.6,<2" }, + { name = "cuda-toolkit", extras = ["cufile"], marker = "sys_platform == 'linux' and extra == 'io'", specifier = ">=13,<14" }, + { name = "cuphoton", extras = ["io", "photometry"], marker = "extra == 'gpu'" }, + { name = "cuphoton", extras = ["photometry", "torch"], marker = "extra == 'ximage'" }, + { name = "cupy-cuda13x", extras = ["ctk"], marker = "sys_platform == 'linux' and extra == 'cutile'", specifier = ">=14,<15" }, + { name = "cupy-cuda13x", extras = ["ctk"], marker = "sys_platform == 'linux' and extra == 'io'", specifier = ">=14,<15" }, + { name = "dragonhpc", marker = "extra == 'dragon'", specifier = ">=0.14.2,<0.15" }, + { name = "filelock", marker = "sys_platform == 'linux' and extra == 'gpu'", specifier = ">=4.2.1" }, + { name = "filelock", marker = "extra == 'dev'", specifier = ">=4.2.1" }, + { name = "filelock", marker = "extra == 'torch'", specifier = ">=4.2.1" }, + { name = "h5py", specifier = ">=3.10" }, + { name = "httpx", marker = "extra == 'xlens-inference'", specifier = ">=0.28,<1" }, + { name = "kvikio-cu13", marker = "sys_platform == 'linux' and extra == 'io'", specifier = "==26.6.*" }, + { name = "libkvikio-cu13", marker = "sys_platform == 'linux' and extra == 'io'", specifier = "==26.6.*" }, + { name = "lsst-images", extras = ["https"], marker = "extra == 'rubin'", specifier = "==30.0.10" }, + { name = "mpi4py", marker = "extra == 'mpi'", specifier = ">=4.1.2,<5" }, + { name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" }, + { name = "numexpr", marker = "extra == 'catalog'", specifier = ">=2.10" }, + { name = "numpy", specifier = ">=2.0,<2.6" }, + { name = "nvidia-libnvcomp-cu13", marker = "sys_platform == 'linux' and extra == 'io'", specifier = "==5.2.*" }, + { name = "nvidia-nvcomp-cu13", marker = "sys_platform == 'linux' and extra == 'io'", specifier = "==5.2.*" }, + { name = "pandas", marker = "extra == 'catalog'", specifier = ">=2.2" }, + { name = "photutils", marker = "extra == 'photometry'", specifier = ">=3.0" }, + { name = "pillow", marker = "extra == 'viz'", specifier = ">=13.0.0" }, + { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=4.0" }, + { name = "pyarrow", specifier = ">=23.0" }, + { name = "pydantic", marker = "extra == 'dev'", specifier = ">=2.11,<3" }, + { name = "pydantic", marker = "extra == 'ximage'", specifier = ">=2.11,<3" }, + { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.3" }, + { name = "pyyaml", specifier = ">=6.0" }, + { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15.12" }, + { name = "scipy", specifier = ">=1.13" }, + { name = "setuptools", marker = "extra == 'dev'", specifier = ">=84.2.1" }, + { name = "torch", marker = "sys_platform == 'linux' and extra == 'gpu'", specifier = ">=2.13,<3" }, + { name = "torch", marker = "extra == 'torch'", specifier = ">=2.13,<3" }, + { name = "tornado", marker = "extra == 'viz'", specifier = ">=6.6" }, + { name = "types-pyyaml", marker = "extra == 'dev'", specifier = ">=6.0.12" }, + { name = "virtualenv", marker = "extra == 'dev'", specifier = ">=21.15.4" }, + { name = "zarr", marker = "extra == 'ximage'", specifier = ">=3,<4" }, +] +provides-extras = ["catalog", "ximage", "rubin", "xlens-inference", "photometry", "torch", "viz", "io", "gpu", "cutile", "mpi", "dragon", "dev"] + +[package.metadata.requires-dev] +docs = [ + { name = "filelock", specifier = ">=4.2.1" }, + { name = "ipykernel", specifier = ">=6,<8" }, + { name = "matplotlib", specifier = ">=3.10,<4" }, + { name = "nbclient", specifier = ">=0.10,<1" }, + { name = "torch", specifier = ">=2.13,<3", index = "https://download.pytorch.org/whl/cpu", conflict = { package = "cuphoton", group = "docs" } }, +] +native-build = [ + { name = "pybind11", specifier = ">=3.0,<4" }, + { name = "setuptools", specifier = ">=84.2.1" }, + { name = "setuptools-scm", specifier = "==10.3.4" }, + { name = "wheel" }, +] +notebook = [ + { name = "ipykernel", specifier = ">=6,<8" }, + { name = "jupyterlab", specifier = ">=4,<5" }, +] + +[[package]] +name = "cuphoton-dev" +version = "0.1.0" +source = { editable = "." } +dependencies = [ + { name = "beautifulsoup4" }, + { name = "cuphoton" }, +] + +[package.dev-dependencies] +dev = [ + { name = "coverage" }, + { name = "mypy" }, + { name = "pytest" }, + { name = "ruff" }, + { name = "types-beautifulsoup4" }, +] + +[package.metadata] +requires-dist = [ + { name = "beautifulsoup4", specifier = ">=4.14,<5" }, + { name = "cuphoton", editable = "../" }, +] + +[package.metadata.requires-dev] +dev = [ + { name = "coverage", specifier = ">=7.10.6,<8" }, + { name = "mypy", specifier = "==1.19.1" }, + { name = "pytest", specifier = ">=8.3" }, + { name = "ruff", specifier = ">=0.15.12" }, + { name = "types-beautifulsoup4", specifier = ">=4.12" }, +] + +[[package]] +name = "h5py" +version = "3.16.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "numpy" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/db/33/acd0ce6863b6c0d7735007df01815403f5589a21ff8c2e1ee2587a38f548/h5py-3.16.0.tar.gz", hash = "sha256:a0dbaad796840ccaa67a4c144a0d0c8080073c34c76d5a6941d6818678ef2738", size = 446526, upload-time = "2026-03-06T13:49:08.07Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/c8/c0/5d4119dba94093bbafede500d3defd2f5eab7897732998c04b54021e530b/h5py-3.16.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c5313566f4643121a78503a473f0fb1e6dcc541d5115c44f05e037609c565c4d", size = 3685604, upload-time = "2026-03-06T13:48:04.198Z" }, + { url = "https://files.pythonhosted.org/packages/b0/42/c84efcc1d4caebafb1ecd8be4643f39c85c47a80fe254d92b8b43b1eadaf/h5py-3.16.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:42b012933a83e1a558c673176676a10ce2fd3759976a0fedee1e672d1e04fc9d", size = 3061940, upload-time = "2026-03-06T13:48:05.783Z" }, + { url = "https://files.pythonhosted.org/packages/89/84/06281c82d4d1686fde1ac6b0f307c50918f1c0151062445ab3b6fa5a921d/h5py-3.16.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:ff24039e2573297787c3063df64b60aab0591980ac898329a08b0320e0cf2527", size = 5198852, upload-time = "2026-03-06T13:48:07.482Z" }, + { url = "https://files.pythonhosted.org/packages/9e/e9/1a19e42cd43cc1365e127db6aae85e1c671da1d9a5d746f4d34a50edb577/h5py-3.16.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:dfc21898ff025f1e8e67e194965a95a8d4754f452f83454538f98f8a3fcb207e", size = 5405250, upload-time = "2026-03-06T13:48:09.628Z" }, + { url = "https://files.pythonhosted.org/packages/b7/8e/9790c1655eabeb85b92b1ecab7d7e62a2069e53baefd58c98f0909c7a948/h5py-3.16.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:698dd69291272642ffda44a0ecd6cd3bda5faf9621452d255f57ce91487b9794", size = 5190108, upload-time = "2026-03-06T13:48:11.26Z" }, + { url = "https://files.pythonhosted.org/packages/51/d7/ab693274f1bd7e8c5f9fdd6c7003a88d59bedeaf8752716a55f532924fbb/h5py-3.16.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2b2c02b0a160faed5fb33f1ba8a264a37ee240b22e049ecc827345d0d9043074", size = 5419216, upload-time = "2026-03-06T13:48:13.322Z" }, + { url = "https://files.pythonhosted.org/packages/03/c1/0976b235cf29ead553e22f2fb6385a8252b533715e00d0ae52ed7b900582/h5py-3.16.0-cp312-cp312-win_amd64.whl", hash = "sha256:96b422019a1c8975c2d5dadcf61d4ba6f01c31f92bbde6e4649607885fe502d6", size = 3182868, upload-time = "2026-03-06T13:48:15.759Z" }, + { url = "https://files.pythonhosted.org/packages/14/d9/866b7e570b39070f92d47b0ff1800f0f8239b6f9e45f02363d7112336c1f/h5py-3.16.0-cp312-cp312-win_arm64.whl", hash = "sha256:39c2838fb1e8d97bcf1755e60ad1f3dd76a7b2a475928dc321672752678b96db", size = 2653286, upload-time = "2026-03-06T13:48:17.279Z" }, + { url = "https://files.pythonhosted.org/packages/0f/9e/6142ebfda0cb6e9349c091eae73c2e01a770b7659255248d637bec54a88b/h5py-3.16.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:370a845f432c2c9619db8eed334d1e610c6015796122b0e57aa46312c22617d9", size = 3671808, upload-time = "2026-03-06T13:48:19.737Z" }, + { url = "https://files.pythonhosted.org/packages/b0/65/5e088a45d0f43cd814bc5bec521c051d42005a472e804b1a36c48dada09b/h5py-3.16.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:42108e93326c50c2810025aade9eac9d6827524cdccc7d4b75a546e5ab308edb", size = 3045837, upload-time = "2026-03-06T13:48:21.854Z" }, + { url = "https://files.pythonhosted.org/packages/da/1e/6172269e18cc5a484e2913ced33339aad588e02ba407fafd00d369e22ef3/h5py-3.16.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:099f2525c9dcf28de366970a5fb34879aab20491589fa89ce2863a84218bb524", size = 5193860, upload-time = "2026-03-06T13:48:24.071Z" }, + { url = "https://files.pythonhosted.org/packages/bd/98/ef2b6fe2903e377cbe870c3b2800d62552f1e3dbe81ce49e1923c53d1c5c/h5py-3.16.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:9300ad32dea9dfc5171f94d5f6948e159ed93e4701280b0f508773b3f582f402", size = 5400417, upload-time = "2026-03-06T13:48:25.728Z" }, + { url = "https://files.pythonhosted.org/packages/bc/81/5b62d760039eed64348c98129d17061fdfc7839fc9c04eaaad6dee1004e4/h5py-3.16.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:171038f23bccddfc23f344cadabdfc9917ff554db6a0d417180d2747fe4c75a7", size = 5185214, upload-time = "2026-03-06T13:48:27.436Z" }, + { url = "https://files.pythonhosted.org/packages/28/c4/532123bcd9080e250696779c927f2cb906c8bf3447df98f5ceb8dcded539/h5py-3.16.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:7e420b539fb6023a259a1b14d4c9f6df8cf50d7268f48e161169987a57b737ff", size = 5414598, upload-time = "2026-03-06T13:48:29.49Z" }, + { url = "https://files.pythonhosted.org/packages/c3/d9/a27997f84341fc0dfcdd1fe4179b6ba6c32a7aa880fdb8c514d4dad6fba3/h5py-3.16.0-cp313-cp313-win_amd64.whl", hash = "sha256:18f2bbcd545e6991412253b98727374c356d67caa920e68dc79eab36bf5fedad", size = 3175509, upload-time = "2026-03-06T13:48:31.131Z" }, + { url = "https://files.pythonhosted.org/packages/a5/23/bb8647521d4fd770c30a76cfc6cb6a2f5495868904054e92f2394c5a78ff/h5py-3.16.0-cp313-cp313-win_arm64.whl", hash = "sha256:656f00e4d903199a1d58df06b711cf3ca632b874b4207b7dbec86185b5c8c7d4", size = 2647362, upload-time = "2026-03-06T13:48:33.411Z" }, + { url = "https://files.pythonhosted.org/packages/48/3c/7fcd9b4c9eed82e91fb15568992561019ae7a829d1f696b2c844355d95dd/h5py-3.16.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:9c9d307c0ef862d1cd5714f72ecfafe0a5d7529c44845afa8de9f46e5ba8bd65", size = 3678608, upload-time = "2026-03-06T13:48:35.183Z" }, + { url = "https://files.pythonhosted.org/packages/6a/b7/9366ed44ced9b7ef357ab48c94205280276db9d7f064aa3012a97227e966/h5py-3.16.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:8c1eff849cdd53cbc73c214c30ebdb6f1bb8b64790b4b4fc36acdb5e43570210", size = 3054773, upload-time = "2026-03-06T13:48:37.139Z" }, + { url = "https://files.pythonhosted.org/packages/58/a5/4964bc0e91e86340c2bbda83420225b2f770dcf1eb8a39464871ad769436/h5py-3.16.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:e2c04d129f180019e216ee5f9c40b78a418634091c8782e1f723a6ca3658b965", size = 5198886, upload-time = "2026-03-06T13:48:38.879Z" }, + { url = "https://files.pythonhosted.org/packages/f1/16/d905e7f53e661ce2c24686c38048d8e2b750ffc4350009d41c4e6c6c9826/h5py-3.16.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:e4360f15875a532bc7b98196c7592ed4fc92672a57c0a621355961cafb17a6dd", size = 5404883, upload-time = "2026-03-06T13:48:41.324Z" }, + { url = "https://files.pythonhosted.org/packages/4b/f2/58f34cb74af46d39f4cd18ea20909a8514960c5a3e5b92fd06a28161e0a8/h5py-3.16.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:3fae9197390c325e62e0a1aa977f2f62d994aa87aab182abbea85479b791197c", size = 5192039, upload-time = "2026-03-06T13:48:43.117Z" }, + { url = "https://files.pythonhosted.org/packages/ce/ca/934a39c24ce2e2db017268c08da0537c20fa0be7e1549be3e977313fc8f5/h5py-3.16.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:43259303989ac8adacc9986695b31e35dba6fd1e297ff9c6a04b7da5542139cc", size = 5421526, upload-time = "2026-03-06T13:48:44.838Z" }, + { url = "https://files.pythonhosted.org/packages/3e/14/615a450205e1b56d16c6783f5ccd116cde05550faad70ae077c955654a75/h5py-3.16.0-cp314-cp314-win_amd64.whl", hash = "sha256:fa48993a0b799737ba7fd21e2350fa0a60701e58180fae9f2de834bc39a147ab", size = 3183263, upload-time = "2026-03-06T13:48:47.117Z" }, + { url = "https://files.pythonhosted.org/packages/7b/48/a6faef5ed632cae0c65ac6b214a6614a0b510c3183532c521bdb0055e117/h5py-3.16.0-cp314-cp314-win_arm64.whl", hash = "sha256:1897a771a7f40d05c262fc8f37376ec37873218544b70216872876c627640f63", size = 2663450, upload-time = "2026-03-06T13:48:48.707Z" }, + { url = "https://files.pythonhosted.org/packages/5d/32/0c8bb8aedb62c772cf7c1d427c7d1951477e8c2835f872bc0a13d1f85f86/h5py-3.16.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:15922e485844f77c0b9d275396d435db3baa58292a9c2176a386e072e0cf2491", size = 3760693, upload-time = "2026-03-06T13:48:50.453Z" }, + { url = "https://files.pythonhosted.org/packages/1d/1f/fcc5977d32d6387c5c9a694afee716a5e20658ac08b3ff24fdec79fb05f2/h5py-3.16.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:df02dd29bd247f98674634dfe41f89fd7c16ba3d7de8695ec958f58404a4e618", size = 3181305, upload-time = "2026-03-06T13:48:52.221Z" }, + { url = "https://files.pythonhosted.org/packages/f5/a1/af87f64b9f986889884243643621ebbd4ac72472ba8ec8cec891ac8e2ca1/h5py-3.16.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:0f456f556e4e2cebeebd9d66adf8dc321770a42593494a0b6f0af54a7567b242", size = 5074061, upload-time = "2026-03-06T13:48:54.089Z" }, + { url = "https://files.pythonhosted.org/packages/cc/d0/146f5eaff3dc246a9c7f6e5e4f42bd45cc613bce16693bcd4d1f7c958bf5/h5py-3.16.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:3e6cb3387c756de6a9492d601553dffea3fe11b5f22b443aac708c69f3f55e16", size = 5279216, upload-time = "2026-03-06T13:48:56.75Z" }, + { url = "https://files.pythonhosted.org/packages/a1/9d/12a13424f1e604fc7df9497b73c0356fb78c2fb206abd7465ce47226e8fd/h5py-3.16.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8389e13a1fd745ad2856873e8187fd10268b2d9677877bb667b41aebd771d8b7", size = 5070068, upload-time = "2026-03-06T13:48:59.169Z" }, + { url = "https://files.pythonhosted.org/packages/41/8c/bbe98f813722b4873818a8db3e15aa3e625b59278566905ac439725e8070/h5py-3.16.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:346df559a0f7dcb31cf8e44805319e2ab24b8957c45e7708ce503b2ec79ba725", size = 5300253, upload-time = "2026-03-06T13:49:02.033Z" }, + { url = "https://files.pythonhosted.org/packages/32/9e/87e6705b4d6890e7cecdf876e2a7d3e40654a2ae37482d79a6f1b87f7b92/h5py-3.16.0-cp314-cp314t-win_amd64.whl", hash = "sha256:4c6ab014ab704b4feaa719ae783b86522ed0bf1f82184704ed3c9e4e3228796e", size = 3381671, upload-time = "2026-03-06T13:49:04.351Z" }, + { url = "https://files.pythonhosted.org/packages/96/91/9fad90cfc5f9b2489c7c26ad897157bce82f0e9534a986a221b99760b23b/h5py-3.16.0-cp314-cp314t-win_arm64.whl", hash = "sha256:faca8fb4e4319c09d83337adc80b2ca7d5c5a343c2d6f1b6388f32cfecca13c1", size = 2740706, upload-time = "2026-03-06T13:49:06.347Z" }, +] + +[[package]] +name = "iniconfig" +version = "2.3.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/01/e1/2069291243c926a2ff1cd706c7f3eeb9b62144bf60f77c9fb9ff2fb26bd3/iniconfig-2.3.1.tar.gz", hash = "sha256:67f4b9c50da0dedf52af349e7749a80a9057a5031199791b906c3bb3ae878960", size = 21209, upload-time = "2026-10-06T22:48:38.076Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/56/43/4ca9e49d27a1fcf6bece6f6aec0ea46bb9112489b93d4b688fb415457bdb/iniconfig-2.3.1-py3-none-any.whl", hash = "sha256:9121e2c1fdb355232495be3194c8dfe87ccc2d5dee45947b78e68f499790d7a7", size = 7552, upload-time = "2026-10-06T22:48:36.959Z" }, +] + +[[package]] +name = "librt" +version = "0.16.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/04/f5/9dc696772d241814bacac7880bac32f2930b5a6ebc1f85317b83161a011c/librt-0.16.0.tar.gz", hash = "sha256:ac38d6d8d66bf3d744148dbbc0b8e193e195a51e364ed55e224631f5721891fc", size = 219839, upload-time = "2026-09-29T00:55:32.891Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ad/76/bbdaeb87b7c47b5c7343e90222b9bfa4e4a8a83f647e02933ad0129225b1/librt-0.16.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:fe52bf4641069e7978a14253b036cb9002def1926317e710f2e249f8a8c47742", size = 151028, upload-time = "2026-09-29T00:52:41.508Z" }, + { url = "https://files.pythonhosted.org/packages/fd/0c/ab8ed3dab0085931aec4a792c7eaac8dc6c5ff4691fda3a5360d9d8a9cd2/librt-0.16.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:5bcc2c4726ced915b00de0c9856a4eeabfb3fddb93e10e0b8f735b7709358b6d", size = 155283, upload-time = "2026-09-29T00:52:42.873Z" }, + { url = "https://files.pythonhosted.org/packages/eb/36/494e79d460c80c1f030661e8287c9eca5e1ad652dc2b2180b6cd42abce0a/librt-0.16.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ff7baa55f8e7c69851419e50a666015d02a74198716fd45c0125a2112e0a389f", size = 503185, upload-time = "2026-09-29T00:52:44.638Z" }, + { url = "https://files.pythonhosted.org/packages/9b/34/a8464038dd9db6e4381fa2b6eb73dc9a50888d77102c4c139304ac35cddc/librt-0.16.0-cp312-cp312-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:b95d5d92ab83d39e760a52091bb1baba664f3a2351e39b1e16801e5747c2f0e9", size = 496738, upload-time = "2026-09-29T00:52:46.441Z" }, + { url = "https://files.pythonhosted.org/packages/6a/53/e0e5e334ef0c6ed27039d323819368b9ef6712be87d55ee2bf9799398afd/librt-0.16.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:b6d085d70bce51d43c5c7c36d63490770180d8779e71c49305c87b4213918de7", size = 513818, upload-time = "2026-09-29T00:52:48.068Z" }, + { url = "https://files.pythonhosted.org/packages/ad/f7/7ce72cbf19d0addd05090b339152fd0548a02562c2866a603e6e3b3da2df/librt-0.16.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:36e53948e99bbe3ffea257124cfcae1cfb01831555c9a9c903c9f9a72db7fd07", size = 531952, upload-time = "2026-09-29T00:52:49.816Z" }, + { url = "https://files.pythonhosted.org/packages/83/22/0b1bcb6a8e723c8b4fd60dfc8ae8ec6461c54073fbc8685efeb8d900d407/librt-0.16.0-cp312-cp312-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:54d11f726aae9df5a6ffbbf0a03a52449bbac84a53ef03669cb41cdfd4ae41bf", size = 524465, upload-time = "2026-09-29T00:52:51.354Z" }, + { url = "https://files.pythonhosted.org/packages/64/2e/e9c23b8b9df1813da1be205deca9606beb7ddd033972246cd426d05374a0/librt-0.16.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:4323193ac0cd025f85af531df8ba91bf24d1973b401697347a6282e8fd3fcf5e", size = 543191, upload-time = "2026-09-29T00:52:53.284Z" }, + { url = "https://files.pythonhosted.org/packages/bc/e5/6a8b21b342c03ed7e230fa3afbfd2edc58e6e87ef1f0d11fa2b9a748c252/librt-0.16.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:e42f8e098b9c5396fefa05fb1cc7e33b0e08fc51da106b5de4a45fd22aac6743", size = 546979, upload-time = "2026-09-29T00:52:54.932Z" }, + { url = "https://files.pythonhosted.org/packages/84/9e/b5129023eced1be01e01c22757f53be551d463b1bb7264f787927404c1d6/librt-0.16.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:39ec1d5a14e37baf1450a6cabf03fe552340808bf1ad9d71824ab90117716459", size = 555317, upload-time = "2026-09-29T00:52:56.869Z" }, + { url = "https://files.pythonhosted.org/packages/71/89/28bba5938c725fe91f06bf93f7fa6c6b150229df53a87b454b0d5c2a796e/librt-0.16.0-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:d1aabe3925cbb4a08d15b7b20ba4011b53019da0c4173a25155139b7b1baed65", size = 535846, upload-time = "2026-09-29T00:52:58.475Z" }, + { url = "https://files.pythonhosted.org/packages/22/92/63773026614f888c5d4e370e395ce42ca604b89f70b3acdfedbf94851b80/librt-0.16.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:300c3ffdc459f4a779a8411ecb188e3ac0b1ff3a3a7b099642555dedae06c69b", size = 573700, upload-time = "2026-09-29T00:53:00.127Z" }, + { url = "https://files.pythonhosted.org/packages/66/8f/347d4677eefb57cd9f8e01d95a1dcee9a91b4e44e664173c32ff6f3752e5/librt-0.16.0-cp312-cp312-win32.whl", hash = "sha256:c17194318e4c0c0348b36f36c2ec7534436fe0a4c15582403162a4f08c80797a", size = 106158, upload-time = "2026-09-29T00:53:02.031Z" }, + { url = "https://files.pythonhosted.org/packages/f0/2c/5193dc81127cd5ddfad031391b046bf32dda219b38463ab872407ca30646/librt-0.16.0-cp312-cp312-win_amd64.whl", hash = "sha256:25a58a19ea8d83b68209f04912df765e9260635ef77646542ed4b4abe6bc7940", size = 126176, upload-time = "2026-09-29T00:53:03.445Z" }, + { url = "https://files.pythonhosted.org/packages/ff/3d/9668a400c8dd81d162eba38b33fa49fa6205f1a64493570a13fbb815c3ee/librt-0.16.0-cp312-cp312-win_arm64.whl", hash = "sha256:f7be7cf555bc30ec12622e9447299cc4a9b8ff307548b634794353db0c2065dc", size = 116572, upload-time = "2026-09-29T00:53:04.815Z" }, + { url = "https://files.pythonhosted.org/packages/46/cd/ae5e0e9dba45d1399aa04a5395bcc0bead40d9fa06dc903634a7b4d7473d/librt-0.16.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:c5e6144e68b577f157519f2ba88ca20e3ed61c29b00e5cdfa76cd2d45acf059a", size = 151036, upload-time = "2026-09-29T00:53:06.284Z" }, + { url = "https://files.pythonhosted.org/packages/41/5a/48a16e323c5f9447a94cce7b59babf60fa04e62c3365ecf060c77ed8b320/librt-0.16.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:33f41443a1f4e1f099331b3d8120e409fbff84b9760bc1cc9ea496f37ddaa5cc", size = 155211, upload-time = "2026-09-29T00:53:07.72Z" }, + { url = "https://files.pythonhosted.org/packages/3f/29/0f59299eb4251a409b2e690ad4b7d9f8a676db829d7817ec961f32b44f7e/librt-0.16.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7e510b7770bee609617a3374a96548eb114cae048023e3f049ee449e7ff2db32", size = 502587, upload-time = "2026-09-29T00:53:09.191Z" }, + { url = "https://files.pythonhosted.org/packages/de/ba/d6fb4ef8d1537c396079d72289f16be7cd35a366e5065c51253fea2760b6/librt-0.16.0-cp313-cp313-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:efc49c462d4516b8a58b00b490078fa64689fd1fe66970cc190131d7afb8027e", size = 496146, upload-time = "2026-09-29T00:53:11.016Z" }, + { url = "https://files.pythonhosted.org/packages/52/fc/8c50dd4d7cc97c0ee8f252c8a3104980f234391cf1519b554e8b9de08b60/librt-0.16.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:92caf82ebef5e12d21c72242b70d1e92536f1711cf2a727a4c276de4b4469087", size = 513336, upload-time = "2026-09-29T00:53:12.655Z" }, + { url = "https://files.pythonhosted.org/packages/a9/59/16c409c56f708eda2db9a0553662845d45e3871c77d70a240dae3f3bdc56/librt-0.16.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:17bac7f7a16b328fff77e440287693eb017abde913595b5827ebccbc21ecd8a6", size = 531689, upload-time = "2026-09-29T00:53:14.39Z" }, + { url = "https://files.pythonhosted.org/packages/88/82/d34772a6c29d1446dcca6e64d74062efd508523ab351aa16625a4689d5cc/librt-0.16.0-cp313-cp313-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5b976054553670829985ed767feb78fb6bcede0175327c4844dd5c281c1be659", size = 524537, upload-time = "2026-09-29T00:53:16.064Z" }, + { url = "https://files.pythonhosted.org/packages/77/8f/24c5631313746131ccee53bc91fdc8374f9cf25e0082a1fee9c93bb98acc/librt-0.16.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:0058f9d68721094105917254c72ac0569117bb7b13b9769cf45d26d89f9d21cd", size = 543231, upload-time = "2026-09-29T00:53:17.939Z" }, + { url = "https://files.pythonhosted.org/packages/f2/cb/5f8e0d41dbd8b499c2265e939c31acc9ba59845565bf99539ad1c06aebcf/librt-0.16.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:30b7beaf3f4487b7d8adef1f158b49067cb4d5a19fa7a3bf31a4e7a820e435c5", size = 546499, upload-time = "2026-09-29T00:53:19.666Z" }, + { url = "https://files.pythonhosted.org/packages/be/61/063052de441d1385f59cea4223f184bf9e5d125de1ae3239b490aa1e486e/librt-0.16.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:468df902df016a06eb0e40b0747dc8d14e47d7a38b18b63b1fb167d85cb94d63", size = 555261, upload-time = "2026-09-29T00:53:21.292Z" }, + { url = "https://files.pythonhosted.org/packages/14/11/a2ada0529372268d6401afa9d457a095b68cd7753532b6f7f33049a19b43/librt-0.16.0-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:aea7b1f2b125dad5de85f049136651bff256c883c65e6b9209b2da0a1ac3cdef", size = 536029, upload-time = "2026-09-29T00:53:23.07Z" }, + { url = "https://files.pythonhosted.org/packages/23/9d/5bb6d38853382986dca702fc7e06c8256d30f5fa0676d882773b744610dc/librt-0.16.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:a8afb6557920860b7a3a596eb804cf37e09e7cf8a803db2478c202acc72d8c2e", size = 573748, upload-time = "2026-09-29T00:53:24.696Z" }, + { url = "https://files.pythonhosted.org/packages/99/f6/0025cde35ff7f607684dc775a2b2d732cce2561cec050a6ee1fb2e1fc6fe/librt-0.16.0-cp313-cp313-pyemscripten_2025_0_wasm32.whl", hash = "sha256:77c7a2b4fe2c1369e0d5aa1cade26740a7b14be32fbc9a5535d617d20065c39d", size = 79861, upload-time = "2026-09-29T00:53:26.089Z" }, + { url = "https://files.pythonhosted.org/packages/93/93/303b8592909bd583f83f02818ffbea3f7647ca1e22b1cd5465d04b8145fe/librt-0.16.0-cp313-cp313-win32.whl", hash = "sha256:02d89c813d5ff74b17df72d3a34819d132cd168e56b81bf755b809bd9e46b8c4", size = 106236, upload-time = "2026-09-29T00:53:27.43Z" }, + { url = "https://files.pythonhosted.org/packages/cf/24/80bbb463c60ed18e29cb26aba386ddb76609580e4e7160710e550587018c/librt-0.16.0-cp313-cp313-win_amd64.whl", hash = "sha256:14ed6ebe3e4f85f326d7920011ad30ff49ed9334e62cf88caef9ba973d9e3a92", size = 126180, upload-time = "2026-09-29T00:53:28.7Z" }, + { url = "https://files.pythonhosted.org/packages/43/80/b1a6fbdd7da825cdd55c71aa81eb6cfa82c513c360774152eacb50b4a771/librt-0.16.0-cp313-cp313-win_arm64.whl", hash = "sha256:83d4041a3d9b2fd053a8a4e1f22878b3e5833e2712956382d5c048d791454e91", size = 116557, upload-time = "2026-09-29T00:53:30.012Z" }, + { url = "https://files.pythonhosted.org/packages/1e/93/9e0cf7da129a93c3dc7f45bc3cd4a660f2aaa995aa8a6f95c2583ef41239/librt-0.16.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:931a0bb0fcac88f263e269e46eb30ba8e21402cd3c62ca40cb97034c0693fab1", size = 149844, upload-time = "2026-09-29T00:53:31.391Z" }, + { url = "https://files.pythonhosted.org/packages/8f/26/8a90d2a8f2b2e471bb486b7aec117b8ae622715ed6c39853aec48ea20073/librt-0.16.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1bc17e54e5305f8d40b7ca203671ff5a9e59c1d0f8ea0f625dcca53a3984de11", size = 154111, upload-time = "2026-09-29T00:53:32.718Z" }, + { url = "https://files.pythonhosted.org/packages/35/ce/67abb46258da4d3e42ff5b141db6f38c59357bef84c7979f183b22f924f1/librt-0.16.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:877698bf6bca5721d8be345f2fe09778e40ecadea8b58c73075f2b1a53666bf2", size = 494234, upload-time = "2026-09-29T00:53:34.466Z" }, + { url = "https://files.pythonhosted.org/packages/12/f9/ea7162414a16f8f1bbd3b493ad6d22b926c5471916e078350bdbca8c4e5f/librt-0.16.0-cp314-cp314-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:5981c011b306781ce561e18e14230a14524a3d8109b97553666c942c18f31a96", size = 491173, upload-time = "2026-09-29T00:53:36.124Z" }, + { url = "https://files.pythonhosted.org/packages/b1/09/9b3e869060dd33f9989b80ba4fea306f6db8cecefcdfe6d7346ef0603f65/librt-0.16.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:afced3dfc17cd805ecf7a3d77996a71cf5f2c75aa66eb0c21a9930f4fc992f86", size = 505547, upload-time = "2026-09-29T00:53:37.686Z" }, + { url = "https://files.pythonhosted.org/packages/50/07/79007d2165f649ea93e08c0962d1d62c70af9cde77965255095bf9d96f9a/librt-0.16.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ca8052401c55d7511dda6760719fda7618067e83535d7d0010096d216c34b667", size = 523057, upload-time = "2026-09-29T00:53:39.301Z" }, + { url = "https://files.pythonhosted.org/packages/61/0c/8fbaff66d0ba376d8864653f5acce1569bae27e89648671f26f7eca67ab8/librt-0.16.0-cp314-cp314-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1e511762a074005bb0aa569166779834e75e438370226930d0ce1866d4b6a33b", size = 515158, upload-time = "2026-09-29T00:53:41.012Z" }, + { url = "https://files.pythonhosted.org/packages/df/2e/23ff0dece76f07a4124413a57682efa0bbeb5765ac0122bc0955513f82ca/librt-0.16.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:f1e8591bd8a5a628cd7f07954c6a1592359a878bf032957a8e9057a41d644311", size = 534183, upload-time = "2026-09-29T00:53:42.451Z" }, + { url = "https://files.pythonhosted.org/packages/26/c4/e11dea21d9a29486eba78887380374189d472734fa32cc50cb37ca44d3d0/librt-0.16.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:a4aaefb4ba6c07e1aeebb2795c8958148f1d6f9af3b555b53d23d766edb6d67a", size = 540663, upload-time = "2026-09-29T00:53:44.272Z" }, + { url = "https://files.pythonhosted.org/packages/44/75/e873ae158a8b7f5359be33e7fd6c1fbe02d9a78a3e89a77de6b0e837f476/librt-0.16.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:d92db7a0f6aee44f1baee94750457e8d2d1c6ccea41842de6268d34e8dc7eddd", size = 545908, upload-time = "2026-09-29T00:53:45.812Z" }, + { url = "https://files.pythonhosted.org/packages/ba/36/8939d3f6a93e11bd9592e6fe28d2b44f1c2dc4bed6e22e72359a91e18ffb/librt-0.16.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:378dfaffb38e59c24a87cde5713cd865d51ff7383fa12947f3907f306ea1ca55", size = 523302, upload-time = "2026-09-29T00:53:47.596Z" }, + { url = "https://files.pythonhosted.org/packages/71/14/35309f44a077f0f42ade0e2e7cd88c0cea760c661af205c01ea90d3c0e1f/librt-0.16.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:3e0c39bdc85370422e8b637be76eb1fd07d30967551b03e62267dd156f553152", size = 565911, upload-time = "2026-09-29T00:53:49.278Z" }, + { url = "https://files.pythonhosted.org/packages/78/0c/df6255b94967f3159ebc46f08d8e783c12da6ee269ddb74b2efed63c640c/librt-0.16.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:1b384b90ab79a7bc30b566895809a636e0666f21f3cf12b54823d025b7e83839", size = 79119, upload-time = "2026-09-29T00:53:50.938Z" }, + { url = "https://files.pythonhosted.org/packages/6b/44/d30d5a5461378c9d33f36736c6791c3b4c4ba4b1ffe0da7350aedcb2c9a0/librt-0.16.0-cp314-cp314-win32.whl", hash = "sha256:52327da75a94012e7f932f913d20d3876bed3c102be00e6c3e8600ff7bdd58a7", size = 100140, upload-time = "2026-09-29T00:53:52.205Z" }, + { url = "https://files.pythonhosted.org/packages/c2/98/769712f356a1e897df3581bb0c3100375d054a000de26099360ea65b5111/librt-0.16.0-cp314-cp314-win_amd64.whl", hash = "sha256:3f0b8114c44b2ac06ff5dacd08e07e8e807ff4f46083f2a1602685122559be41", size = 120464, upload-time = "2026-09-29T00:53:53.495Z" }, + { url = "https://files.pythonhosted.org/packages/bf/d3/ae2abccc8bdc8b063c1613a77686e17b74e9d3d60cfe6f12c63fa2821b9f/librt-0.16.0-cp314-cp314-win_arm64.whl", hash = "sha256:8caf96a4ef8fb27d0ac0d1ad8337d26a240acd4a02fe4345d0a8f264753e8f99", size = 110889, upload-time = "2026-09-29T00:53:54.817Z" }, + { url = "https://files.pythonhosted.org/packages/e4/26/0737d4be058dd6376eade7dd8b380d4b869b6394cee929393a5a431c45bb/librt-0.16.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:953107e2f68d0f3512c48f898b0dbf0ce5cc52bba0f318d847c985dc555ee4cc", size = 159838, upload-time = "2026-09-29T00:53:56.22Z" }, + { url = "https://files.pythonhosted.org/packages/01/96/9bc96531d7c620e9949af904470f02e3fa8f35129ab8e8f281c51eaa3788/librt-0.16.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ad37d5b9abd49c9a655dcda7ea52a8a752884062ef1ee71ae17c2f2a0f81fe6a", size = 162018, upload-time = "2026-09-29T00:53:57.532Z" }, + { url = "https://files.pythonhosted.org/packages/0e/fa/b0289dcb186eb3f97221ba00da5f4bd3ba7fa5e99752d48aa8d336615334/librt-0.16.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2c4aa329c17bd1aaea4f6e89335d8ccd494b3a5830b6654462273e50e11023f0", size = 703983, upload-time = "2026-09-29T00:53:59.024Z" }, + { url = "https://files.pythonhosted.org/packages/d9/ab/05ebbbde7530fc5eeb58fbd1581522a9f64f132fa703c4c595eed6e14760/librt-0.16.0-cp314-cp314t-manylinux2014_i686.manylinux_2_17_i686.manylinux_2_28_i686.whl", hash = "sha256:0ead24d2562a49473dddd9efef8581f020007eb0054389c3ee3ffad38b1ca4c9", size = 683847, upload-time = "2026-09-29T00:54:00.671Z" }, + { url = "https://files.pythonhosted.org/packages/a3/75/f52aeecd4dbadbddf80725ba7de126d8bd5d0eb66247eae17a81ed90dd4d/librt-0.16.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:02118f56a9c36ddd07dfd9b919d9ecc117ba20a90987d56aa4c429fa34509188", size = 698045, upload-time = "2026-09-29T00:54:02.247Z" }, + { url = "https://files.pythonhosted.org/packages/e6/55/fa277a835cd6eb42380591ceb85f48c5b4d2b2d7e2cb9869e1e17d24d237/librt-0.16.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4e29522c62e28595ff7e324c6834ade51127707f0e255b18d1c1cf03d39c1048", size = 724640, upload-time = "2026-09-29T00:54:04.078Z" }, + { url = "https://files.pythonhosted.org/packages/25/e4/2cf64354f3fde8ebd591b3b48f96510bee24ac5f7d1e567adbbe210abdbd/librt-0.16.0-cp314-cp314t-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3ff4b2367926b69c6215635902cccb04048e73094e9862900d27cb2c6bbff143", size = 731748, upload-time = "2026-09-29T00:54:05.741Z" }, + { url = "https://files.pythonhosted.org/packages/f8/c9/c180af3e94e01aa529fa93d7733fec2abc47f222345400cf21d5481d5f8a/librt-0.16.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c6f1b27bf1632a7e016af9f145f82be95e1edd7721a646505c21059257cb5a04", size = 754960, upload-time = "2026-09-29T00:54:07.38Z" }, + { url = "https://files.pythonhosted.org/packages/95/d6/01073aa78c58f356b10d9c57b3fe9abb143df338142bcd316df417b89db0/librt-0.16.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:5696d7f52e7b37217cb3a8f92c744fe835942602fdd4c1a8bc4741d3bfdce15e", size = 747000, upload-time = "2026-09-29T00:54:09.06Z" }, + { url = "https://files.pythonhosted.org/packages/f7/d8/1de3783908658d697a8cfc00582f61299ffba7796d7260c112e4700b1109/librt-0.16.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:6072e92dd876ff6ceeb6cf371e35e51f479349837391341f479b08df4564242b", size = 749569, upload-time = "2026-09-29T00:54:10.702Z" }, + { url = "https://files.pythonhosted.org/packages/b7/32/e817f66c96d6caa8bb8435ff93c4c220624d59efc506be59ab98fcd01d0c/librt-0.16.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:39ca4f2f2fe05de8e63493da592d84311adabe5bef52b193851981da9816b302", size = 729483, upload-time = "2026-09-29T00:54:12.25Z" }, + { url = "https://files.pythonhosted.org/packages/7c/c9/23992ccd2b9d22798fdd0f61353183a47414e651da782ad83eb680f50833/librt-0.16.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f9807485a908f00355820f18e91e045ffdcdc5adb68aaec40a1e2b88c5f7bba1", size = 776584, upload-time = "2026-09-29T00:54:13.837Z" }, + { url = "https://files.pythonhosted.org/packages/67/3b/e8af957f08e6e2e8e566b099e43d2748418aa565df6ee1d9d3331209fdfe/librt-0.16.0-cp314-cp314t-win32.whl", hash = "sha256:94be5cb7bca4df6201f4183e9e4fa2086c655283d20b38cd84500a69057575a7", size = 104402, upload-time = "2026-09-29T00:54:15.568Z" }, + { url = "https://files.pythonhosted.org/packages/ca/1c/946e6443d7cd32347a086043395e421e52fd603c9163d2ec970ceab8eed6/librt-0.16.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d46ca272b251d033dd4527b0dec5f261a28a52bd5fa0f99c117b0a1f8588cc2d", size = 126227, upload-time = "2026-09-29T00:54:17.165Z" }, + { url = "https://files.pythonhosted.org/packages/c2/a3/bc4f9959d3c62bcbf9e5fd3470a8bbd8bf33224ed4c25d7fba173201b8ac/librt-0.16.0-cp314-cp314t-win_arm64.whl", hash = "sha256:b9d6d4b14e92d876f8026b54c20c445f36425214c1081dc76f74e40db386b82b", size = 116493, upload-time = "2026-09-29T00:54:18.567Z" }, +] + +[[package]] +name = "mypy" +version = "1.19.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "librt", marker = "platform_python_implementation != 'PyPy'" }, + { name = "mypy-extensions" }, + { name = "pathspec" }, + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f5/db/4efed9504bc01309ab9c2da7e352cc223569f05478012b5d9ece38fd44d2/mypy-1.19.1.tar.gz", hash = "sha256:19d88bb05303fe63f71dd2c6270daca27cb9401c4ca8255fe50d1d920e0eb9ba", size = 3582404, upload-time = "2025-12-15T05:03:48.42Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/06/8a/19bfae96f6615aa8a0604915512e0289b1fad33d5909bf7244f02935d33a/mypy-1.19.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:a8174a03289288c1f6c46d55cef02379b478bfbc8e358e02047487cad44c6ca1", size = 13206053, upload-time = "2025-12-15T05:03:46.622Z" }, + { url = "https://files.pythonhosted.org/packages/a5/34/3e63879ab041602154ba2a9f99817bb0c85c4df19a23a1443c8986e4d565/mypy-1.19.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ffcebe56eb09ff0c0885e750036a095e23793ba6c2e894e7e63f6d89ad51f22e", size = 12219134, upload-time = "2025-12-15T05:03:24.367Z" }, + { url = "https://files.pythonhosted.org/packages/89/cc/2db6f0e95366b630364e09845672dbee0cbf0bbe753a204b29a944967cd9/mypy-1.19.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b64d987153888790bcdb03a6473d321820597ab8dd9243b27a92153c4fa50fd2", size = 12731616, upload-time = "2025-12-15T05:02:44.725Z" }, + { url = "https://files.pythonhosted.org/packages/00/be/dd56c1fd4807bc1eba1cf18b2a850d0de7bacb55e158755eb79f77c41f8e/mypy-1.19.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c35d298c2c4bba75feb2195655dfea8124d855dfd7343bf8b8c055421eaf0cf8", size = 13620847, upload-time = "2025-12-15T05:03:39.633Z" }, + { url = "https://files.pythonhosted.org/packages/6d/42/332951aae42b79329f743bf1da088cd75d8d4d9acc18fbcbd84f26c1af4e/mypy-1.19.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:34c81968774648ab5ac09c29a375fdede03ba253f8f8287847bd480782f73a6a", size = 13834976, upload-time = "2025-12-15T05:03:08.786Z" }, + { url = "https://files.pythonhosted.org/packages/6f/63/e7493e5f90e1e085c562bb06e2eb32cae27c5057b9653348d38b47daaecc/mypy-1.19.1-cp312-cp312-win_amd64.whl", hash = "sha256:b10e7c2cd7870ba4ad9b2d8a6102eb5ffc1f16ca35e3de6bfa390c1113029d13", size = 10118104, upload-time = "2025-12-15T05:03:10.834Z" }, + { url = "https://files.pythonhosted.org/packages/de/9f/a6abae693f7a0c697dbb435aac52e958dc8da44e92e08ba88d2e42326176/mypy-1.19.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e3157c7594ff2ef1634ee058aafc56a82db665c9438fd41b390f3bde1ab12250", size = 13201927, upload-time = "2025-12-15T05:02:29.138Z" }, + { url = "https://files.pythonhosted.org/packages/9a/a4/45c35ccf6e1c65afc23a069f50e2c66f46bd3798cbe0d680c12d12935caa/mypy-1.19.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:bdb12f69bcc02700c2b47e070238f42cb87f18c0bc1fc4cdb4fb2bc5fd7a3b8b", size = 12206730, upload-time = "2025-12-15T05:03:01.325Z" }, + { url = "https://files.pythonhosted.org/packages/05/bb/cdcf89678e26b187650512620eec8368fded4cfd99cfcb431e4cdfd19dec/mypy-1.19.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f859fb09d9583a985be9a493d5cfc5515b56b08f7447759a0c5deaf68d80506e", size = 12724581, upload-time = "2025-12-15T05:03:20.087Z" }, + { url = "https://files.pythonhosted.org/packages/d1/32/dd260d52babf67bad8e6770f8e1102021877ce0edea106e72df5626bb0ec/mypy-1.19.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c9a6538e0415310aad77cb94004ca6482330fece18036b5f360b62c45814c4ef", size = 13616252, upload-time = "2025-12-15T05:02:49.036Z" }, + { url = "https://files.pythonhosted.org/packages/71/d0/5e60a9d2e3bd48432ae2b454b7ef2b62a960ab51292b1eda2a95edd78198/mypy-1.19.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:da4869fc5e7f62a88f3fe0b5c919d1d9f7ea3cef92d3689de2823fd27e40aa75", size = 13840848, upload-time = "2025-12-15T05:02:55.95Z" }, + { url = "https://files.pythonhosted.org/packages/98/76/d32051fa65ecf6cc8c6610956473abdc9b4c43301107476ac03559507843/mypy-1.19.1-cp313-cp313-win_amd64.whl", hash = "sha256:016f2246209095e8eda7538944daa1d60e1e8134d98983b9fc1e92c1fc0cb8dd", size = 10135510, upload-time = "2025-12-15T05:02:58.438Z" }, + { url = "https://files.pythonhosted.org/packages/de/eb/b83e75f4c820c4247a58580ef86fcd35165028f191e7e1ba57128c52782d/mypy-1.19.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:06e6170bd5836770e8104c8fdd58e5e725cfeb309f0a6c681a811f557e97eac1", size = 13199744, upload-time = "2025-12-15T05:03:30.823Z" }, + { url = "https://files.pythonhosted.org/packages/94/28/52785ab7bfa165f87fcbb61547a93f98bb20e7f82f90f165a1f69bce7b3d/mypy-1.19.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:804bd67b8054a85447c8954215a906d6eff9cabeabe493fb6334b24f4bfff718", size = 12215815, upload-time = "2025-12-15T05:02:42.323Z" }, + { url = "https://files.pythonhosted.org/packages/0a/c6/bdd60774a0dbfb05122e3e925f2e9e846c009e479dcec4821dad881f5b52/mypy-1.19.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:21761006a7f497cb0d4de3d8ef4ca70532256688b0523eee02baf9eec895e27b", size = 12740047, upload-time = "2025-12-15T05:03:33.168Z" }, + { url = "https://files.pythonhosted.org/packages/32/2a/66ba933fe6c76bd40d1fe916a83f04fed253152f451a877520b3c4a5e41e/mypy-1.19.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:28902ee51f12e0f19e1e16fbe2f8f06b6637f482c459dd393efddd0ec7f82045", size = 13601998, upload-time = "2025-12-15T05:03:13.056Z" }, + { url = "https://files.pythonhosted.org/packages/e3/da/5055c63e377c5c2418760411fd6a63ee2b96cf95397259038756c042574f/mypy-1.19.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:481daf36a4c443332e2ae9c137dfee878fcea781a2e3f895d54bd3002a900957", size = 13807476, upload-time = "2025-12-15T05:03:17.977Z" }, + { url = "https://files.pythonhosted.org/packages/cd/09/4ebd873390a063176f06b0dbf1f7783dd87bd120eae7727fa4ae4179b685/mypy-1.19.1-cp314-cp314-win_amd64.whl", hash = "sha256:8bb5c6f6d043655e055be9b542aa5f3bdd30e4f3589163e85f93f3640060509f", size = 10281872, upload-time = "2025-12-15T05:03:05.549Z" }, + { url = "https://files.pythonhosted.org/packages/8d/f4/4ce9a05ce5ded1de3ec1c1d96cf9f9504a04e54ce0ed55cfa38619a32b8d/mypy-1.19.1-py3-none-any.whl", hash = "sha256:f1235f5ea01b7db5468d53ece6aaddf1ad0b88d9e7462b86ef96fe04995d7247", size = 2471239, upload-time = "2025-12-15T05:03:07.248Z" }, +] + +[[package]] +name = "mypy-extensions" +version = "1.2.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d0/6f/43edf3be2748d0e40974a5ee046a8bb4c9961a4bdd3e7d5c6dcbf32d1af6/mypy_extensions-1.2.0.tar.gz", hash = "sha256:c6e275a07f1c2fc096b62940452d0eaa3f3af7de45d704787866240a7c6d5a51", size = 6566, upload-time = "2026-11-03T16:26:33.692Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b5/99/7b1adac7e97ce7bbda34792dc6e9b2f5cc5cffd1875883f78a818b2a2687/mypy_extensions-1.2.0-py3-none-any.whl", hash = "sha256:993e7a20aa5671eb41a7132cf555af30062da99729601601b9a8382b11cae768", size = 5114, upload-time = "2026-11-03T16:26:32.731Z" }, +] + +[[package]] +name = "numpy" +version = "2.5.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/95/b0/c7453d0b6e2073c3264468b106ee1563750cecc910965e67357e3698c83e/numpy-2.5.4.tar.gz", hash = "sha256:9a94cf751c9ad8ebaa835bcd3d40dacf8534ad086b88c38029b65123c7999d2a", size = 20866315, upload-time = "2026-10-10T20:05:31.422Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d0/97/ba2074e92b7befea137e77ea8471e768bbd87c339b7e8c9f5a931949f977/numpy-2.5.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c6342f54c67093cae5c0227eb0eb772fdb79f2a2c37a6eb278b9909ee06aa356", size = 17001609, upload-time = "2026-10-10T20:02:40.843Z" }, + { url = "https://files.pythonhosted.org/packages/ff/a9/bac826765e971d8e16e2064e9ac7525fd69b40ac17c905033a7f5442023f/numpy-2.5.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:b11e8fda06a7d69f15ebf542660b74466c2e51094800c1fb794f47ad4faeef17", size = 12015718, upload-time = "2026-10-10T20:02:43.45Z" }, + { url = "https://files.pythonhosted.org/packages/31/2f/5ea3570fcb8ccd0882bea99436a513b2c85dad8f774a2057849130a8fb99/numpy-2.5.4-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:9cb18a327b49c5c337f972b03682f6a49855525faaf3c0d3e9c96cd0fd8880a8", size = 5451717, upload-time = "2026-10-10T20:02:46.169Z" }, + { url = "https://files.pythonhosted.org/packages/34/f2/b4fc1bafca03868220b5eaf729d2f21ebd7d7b151c0f9e144fe212bbca35/numpy-2.5.4-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:aec3fc4b32ff82421274f5d205c559c51c840c8df66a78efd7f3612dd005a26a", size = 6789926, upload-time = "2026-10-10T20:02:48.139Z" }, + { url = "https://files.pythonhosted.org/packages/dc/96/8319e2457ae4333c62c815c7006b869a4f60985c1e01024c2f8c6c040fe5/numpy-2.5.4-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fe4d21ab149f15e4e6043dfb0de87e6e5f34ac176cde83060e9802981fca2ac2", size = 15695312, upload-time = "2026-10-10T20:02:50.115Z" }, + { url = "https://files.pythonhosted.org/packages/43/a3/c799c62e19c337e6d3770b08e475887fb30ce8477d3c09efca6b2f0228a6/numpy-2.5.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fbde6962867ee75b48b0ee29b2b9372ec5d617799dbaf38e82dc0596f2f7738a", size = 16727283, upload-time = "2026-10-10T20:02:53.186Z" }, + { url = "https://files.pythonhosted.org/packages/39/6b/3604e53fb00314d0dc1b94ec9125a1484f649c0a17480b1f0f0c7a9d6250/numpy-2.5.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:381a7a3d2e65e64c0ec302795ab9dc12bb1e73f150904699c153716177eebdaf", size = 17047890, upload-time = "2026-10-10T20:02:56.038Z" }, + { url = "https://files.pythonhosted.org/packages/4a/7a/e8b58a5289a0d464c52885de47c35a935cdd70c03a4c3ab94a5126416dd0/numpy-2.5.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b89d0aaae2fe498c648f4c4795c084db535af5bd98ef942b2a3681fb74ce8645", size = 18485839, upload-time = "2026-10-10T20:02:59.018Z" }, + { url = "https://files.pythonhosted.org/packages/6f/c9/47094f597015009f310b8c900def59065ef1ff5a6fe7b51fc65ec58ec2c6/numpy-2.5.4-cp312-cp312-win32.whl", hash = "sha256:9968ab7e49b93ac6e1c3b2239732183152c9150f16308d30b66a372cffe3483c", size = 6138936, upload-time = "2026-10-10T20:03:01.626Z" }, + { url = "https://files.pythonhosted.org/packages/12/33/fefe62073dc8acfd0f2b9ed7c003af2f50aa61555e113e6db02b8f79f145/numpy-2.5.4-cp312-cp312-win_amd64.whl", hash = "sha256:a7b1b6353e36a7e50de2973a38d705c88ee93adcf120673cee7f45a4a3fa223a", size = 12573091, upload-time = "2026-10-10T20:03:04.349Z" }, + { url = "https://files.pythonhosted.org/packages/1a/07/161270b0c2eec56e4c905f6d6d22e1b836887b2cb189d3f5820aa588e9dd/numpy-2.5.4-cp312-cp312-win_arm64.whl", hash = "sha256:aa1cce2ff3f8d953de38b76bf44602caeb69f101430208f64a10067f7cb4b1d3", size = 10521630, upload-time = "2026-10-10T20:03:06.767Z" }, + { url = "https://files.pythonhosted.org/packages/67/14/1c3ee0118a8fce08565a5d8482631608426a33af10a01077fada5dc7c119/numpy-2.5.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:2377da2dd3ba2c1200956acbab2a358c83b8e1f8531191672d1cd6ad83250d53", size = 16997729, upload-time = "2026-10-10T20:03:09.291Z" }, + { url = "https://files.pythonhosted.org/packages/83/8c/b0ea9477fb1f0d4484bbc5cba21678cc9969704d8d7f3f158d1db35f8e14/numpy-2.5.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:7415db95818b39ec475a5eea54d9e3b6bc83e3912158e46da3438cdce399804d", size = 12009826, upload-time = "2026-10-10T20:03:11.946Z" }, + { url = "https://files.pythonhosted.org/packages/e2/84/6a3d75b3ba3dfe84ac0053450753d1e6d250a8bf80f66474cc46d1fb643f/numpy-2.5.4-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:6d6a71b9d9a97c03633aa12565ef2825ffa036cc1d99cfd50dacf0f128af4fe2", size = 5445803, upload-time = "2026-10-10T20:03:14.329Z" }, + { url = "https://files.pythonhosted.org/packages/61/18/bb993f267ca20b376e07092a16793a5b31ed3138751e9ba480011a14d742/numpy-2.5.4-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:d8200f16437b289a5bb927c6e184eccc3e8389bc0070fea4cd5b9e13c1757959", size = 6786220, upload-time = "2026-10-10T20:03:16.602Z" }, + { url = "https://files.pythonhosted.org/packages/db/b6/135bb0953b61dc21c6cafa14b424ae666944e4899cf140e00c2b322a1a45/numpy-2.5.4-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c2e71b04c6cad90026e544501bbe0ab9290fa8a4d845e7e8c0d124fb429c988", size = 15689178, upload-time = "2026-10-10T20:03:18.721Z" }, + { url = "https://files.pythonhosted.org/packages/da/24/3bd070f3269dc609d8f26b2643f62ef91bb415841c0b294805aaf7fe06da/numpy-2.5.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6ffa07666f8da0eef81d149934a626d0d95fbd6838432a33e66245423a9062c0", size = 16718044, upload-time = "2026-10-10T20:03:21.386Z" }, + { url = "https://files.pythonhosted.org/packages/c7/8e/9d15bd356b0a019c965312b1a3c6a727cac4cae5bc40045fbc12ce4cff9c/numpy-2.5.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:2fa3328f784fc8277fc48026f6cad516f5c561c5d8e2e39b3c9e0c8f23223b34", size = 17048364, upload-time = "2026-10-10T20:03:24.468Z" }, + { url = "https://files.pythonhosted.org/packages/dc/fe/9d5b560db964f15871885f2250795d15945f8699e17ef90c0c2ff4c875b2/numpy-2.5.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:b86966fbe4ad7de710422175572bcdc75fdedadfb54bc6fab7deabccddd7780b", size = 18474904, upload-time = "2026-10-10T20:03:27.895Z" }, + { url = "https://files.pythonhosted.org/packages/e9/98/d27552990f1bd611ef3e7466adadc78312ea2df63b83aad47fdc3d3ca8df/numpy-2.5.4-cp313-cp313-win32.whl", hash = "sha256:5258bc06526964be5face2fc6f756857a3f24f21ec3e72ca131337a75b165d6c", size = 6134537, upload-time = "2026-10-10T20:03:30.511Z" }, + { url = "https://files.pythonhosted.org/packages/90/8c/140a40398a66b4471211be1affdb6ed24c486d581bd28d07b7f2fcb69540/numpy-2.5.4-cp313-cp313-win_amd64.whl", hash = "sha256:8b4d2fd2d34e5f8c9235ee787de5631a37a28402b15cb80814df973d2be54129", size = 12566113, upload-time = "2026-10-10T20:03:32.612Z" }, + { url = "https://files.pythonhosted.org/packages/34/52/01d205e5e8ccb27b2b0b141e801f22b830198c979111b0fa44771438d9a9/numpy-2.5.4-cp313-cp313-win_arm64.whl", hash = "sha256:bc39ac66a7a9a3fbd6134fda43136b60ffde99c8f4501e64e0d2b24da137babf", size = 10519523, upload-time = "2026-10-10T20:03:35.163Z" }, + { url = "https://files.pythonhosted.org/packages/99/ba/005cb5edd580d2f84d7ca3206b92dc17d4388e56e6f87ffe8f2762f83139/numpy-2.5.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:c668b2f0d651605b58892644b0e302c7157f7159544227758c896982ef384b18", size = 17005499, upload-time = "2026-10-10T20:03:37.961Z" }, + { url = "https://files.pythonhosted.org/packages/f3/49/fee7587c33ee35f7977f9051d7f2023d4e7246d62710c80f20c2361ea232/numpy-2.5.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ffa6ce09a1c6a08e9667dd9c97aa0b14184e8d18f2a14b78b2a2328c9147f076", size = 12019666, upload-time = "2026-10-10T20:03:40.606Z" }, + { url = "https://files.pythonhosted.org/packages/d5/b2/c6ce165acffceb15a82c07b9cc77d391f86b3f379ba62911908ae5d34b91/numpy-2.5.4-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:956555e0603a4d38019ae6925711cb9dc43195c076a928accf7ea5d50bddfe53", size = 5455617, upload-time = "2026-10-10T20:03:43.138Z" }, + { url = "https://files.pythonhosted.org/packages/77/7f/dd85ce260a669a89be06842cf355d7353a33e6cfbc590fb8ebb947d88dc9/numpy-2.5.4-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:2c2c4afffdeb7920e445028dd71eb932cac3e704792e964bc2a232426d4f1255", size = 6791932, upload-time = "2026-10-10T20:03:44.874Z" }, + { url = "https://files.pythonhosted.org/packages/63/d6/34b0a2b0741386a63025a65a2c09caaaaaad6d0ca95b66cd65c30dd7fcb5/numpy-2.5.4-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4054173604cd8658796053f1f3bc0befb68ec1c0762c57fdad61e199256a8617", size = 15710899, upload-time = "2026-10-10T20:03:46.839Z" }, + { url = "https://files.pythonhosted.org/packages/16/d5/928078d2b28f26829b138b4a6c3980045022fb409f570657a224ae60ef4e/numpy-2.5.4-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d549420b8858885cea8838a727842249218b9c1da24dd517e25c9c7a948310a3", size = 16721710, upload-time = "2026-10-10T20:03:49.489Z" }, + { url = "https://files.pythonhosted.org/packages/f9/cf/673fd1b8f4cd78eb6320e87ec4c90ac19c095644259e3749853a405c70f4/numpy-2.5.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:823874a507a84af050493b622affde94b6f7c3a0dc22cb2801381bc03b871c00", size = 17066182, upload-time = "2026-10-10T20:03:52.25Z" }, + { url = "https://files.pythonhosted.org/packages/f3/92/a77b5061b1b3e2643928c37976d79ee173e1b171ed158b7a3c61056b41bc/numpy-2.5.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:4e263278bfb5ee6409db8aedbc4cc32973b1b82bc1e8d3c668551d04d83a7e37", size = 18480315, upload-time = "2026-10-10T20:03:55.39Z" }, + { url = "https://files.pythonhosted.org/packages/bb/1d/1486ef3d3fb2279fd93c4c43c1bbbf1ca389a19816696684409f71babaab/numpy-2.5.4-cp314-cp314-win32.whl", hash = "sha256:cfd73180400042a7c532d30c5e287bdd03c59ff9ee1b4c0316af0539e29dfe23", size = 6185739, upload-time = "2026-10-10T20:03:58.186Z" }, + { url = "https://files.pythonhosted.org/packages/52/9a/e1e512ebc948d5b9dd33b08736760f0ebbed2848fd4eda1f553088a6dcee/numpy-2.5.4-cp314-cp314-win_amd64.whl", hash = "sha256:2ca144f15135b6212a5c47b1e2aeca6e412f102f95a2d5d88d8aec77eb255de3", size = 12703552, upload-time = "2026-10-10T20:04:00.28Z" }, + { url = "https://files.pythonhosted.org/packages/2c/05/de709a982d7bbcd688a3fad71f002e9ff80c2db39e03ee726609b610f1d1/numpy-2.5.4-cp314-cp314-win_arm64.whl", hash = "sha256:468397ba3c64427474706e5c9123fe266395496714dc684294eac75cd4930d1e", size = 10803901, upload-time = "2026-10-10T20:04:02.659Z" }, + { url = "https://files.pythonhosted.org/packages/13/34/083570ada3bb2a30fbe5d77c8c6fef9141144a15d33e6f793a67e9749ab8/numpy-2.5.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1ef3aa6d7e29bb13677323114280b05acc57607fa2300e66432d665d5418a162", size = 12138695, upload-time = "2026-10-10T20:04:05.012Z" }, + { url = "https://files.pythonhosted.org/packages/94/06/1f9c24db48eef0c2d1207e3b11fffb0478e39dfd8c1e1be7476936885eed/numpy-2.5.4-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:98b053943e5a0474ec0da309d2cb9d3f18ea57f8a2067c2ab7b5f763d1068380", size = 5574615, upload-time = "2026-10-10T20:04:07.316Z" }, + { url = "https://files.pythonhosted.org/packages/da/0f/593fba2e1560e949123bc7d2fc48b5893d56e58cd4bd5a273d2fbf60b220/numpy-2.5.4-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:b64a85f40e154983960a4167d4c1d57a50c7f109b3d3264a3a984154e90a8454", size = 6889383, upload-time = "2026-10-10T20:04:09.918Z" }, + { url = "https://files.pythonhosted.org/packages/eb/9f/b799dfdce4e05e80ed4bc815c71ff343a11533b2c0ffc221cae8538cda63/numpy-2.5.4-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a813ed7719bf45463c51779e6a98d0385fe905e48447526938a4b8337333d551", size = 15753763, upload-time = "2026-10-10T20:04:12.278Z" }, + { url = "https://files.pythonhosted.org/packages/34/88/16c5f12f86f5ad2817c4d103205131fc6c8acb3d1878af05a1a4f23ec859/numpy-2.5.4-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c9b80cdf5cedba0e90d93fa5f9a333c4d65bd545cd669b71bb97ce2b703c9d73", size = 16757212, upload-time = "2026-10-10T20:04:14.799Z" }, + { url = "https://files.pythonhosted.org/packages/ff/4f/a1fe40e18a898e6a5089f4f0d891f0a493eb0574d5b34458f0fbe5aa3e5c/numpy-2.5.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:2199ed071f460487c8db2c0e5c0b564494190edb4772fe80f9aad88b2604def5", size = 17116471, upload-time = "2026-10-10T20:04:17.58Z" }, + { url = "https://files.pythonhosted.org/packages/aa/46/e923a11c78e65c1722e7aaad817c06bd591324174b9d28ce5d31eee4d432/numpy-2.5.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:64f9c9878c1938476365e11ccfb6b770f3b9e5f045ccddc514235041e6959365", size = 18524063, upload-time = "2026-10-10T20:04:20.365Z" }, + { url = "https://files.pythonhosted.org/packages/5a/fa/84ab064514440c1f64a1b21088f2c82756defdd05e07c75ab233899565b2/numpy-2.5.4-cp314-cp314t-win32.whl", hash = "sha256:64d1c8ac28a4077cf987e0a71a7a0ef7e2df70722f07f0baa42dbb7eb6938647", size = 6340926, upload-time = "2026-10-10T20:04:22.865Z" }, + { url = "https://files.pythonhosted.org/packages/7e/7e/6cd886876f435b10685db9b9f7eeb70356f99e052116f4e5f11c5792c714/numpy-2.5.4-cp314-cp314t-win_amd64.whl", hash = "sha256:067374eb538c34c745436365cf7b0112595c1d326f21ce4ff340f61230239fbb", size = 12901584, upload-time = "2026-10-10T20:04:24.99Z" }, + { url = "https://files.pythonhosted.org/packages/38/1b/3c1684f6a06f7307f2335fca6e486cb162847fb97e91d65f8eb5cabad213/numpy-2.5.4-cp314-cp314t-win_arm64.whl", hash = "sha256:e94aef2c639da4a960ad0db8e06471208d8589974953d78b61d345b4eb99e394", size = 10891152, upload-time = "2026-10-10T20:04:27.52Z" }, +] + +[[package]] +name = "packaging" +version = "26.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" }, +] + +[[package]] +name = "pathspec" +version = "1.1.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/5a/82/42f767fc1c1143d6fd36efb827202a2d997a375e160a71eb2888a925aac1/pathspec-1.1.1.tar.gz", hash = "sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a", size = 135180, upload-time = "2026-04-27T01:46:08.907Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f1/d9/7fb5aa316bc299258e68c73ba3bddbc499654a07f151cba08f6153988714/pathspec-1.1.1-py3-none-any.whl", hash = "sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189", size = 57328, upload-time = "2026-04-27T01:46:07.06Z" }, +] + +[[package]] +name = "pluggy" +version = "1.7.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/bf/db/7fc19e6f2dc92a966727031389fc2e08b558f0f25eb7403c1119ad4713cd/pluggy-1.7.0.tar.gz", hash = "sha256:d1eaa46ebb595891b860ab086b4d09c8588af65ebd4361b8e8f4bb8920b90ba8", size = 123304, upload-time = "2026-10-15T09:50:58.343Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/40/9e/2b38731e0fc536806f16490e1a12d7f0dc2a1235aa8cc07bcc75416a7daa/pluggy-1.7.0-py3-none-any.whl", hash = "sha256:7dd7b0d8832ba3cb632c306926ded123429211b83641b35dc5c41ad2d34f9bec", size = 27082, upload-time = "2026-10-15T09:50:56.808Z" }, +] + +[[package]] +name = "pyarrow" +version = "26.0.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/bc/5e/9cb2a56d5e293aab4e2fbecc5b0620d93227d66b8d5a63c554c31e1f80fe/pyarrow-26.0.1.tar.gz", hash = "sha256:93affcbd8a343e98dc19e9ec8fe17271ebf8fe98102d8b7454175074409f8b72", size = 1237985, upload-time = "2026-11-03T10:54:17.563Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/61/81/dc5814d61f8c956363e81bcaba61b4712a5d227324d40c766b3858160711/pyarrow-26.0.1-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:217497a51fd41abb74502ba2f4900872e0944c226945c02ee8a1cb4f81df3392", size = 37290209, upload-time = "2026-11-03T10:49:25.185Z" }, + { url = "https://files.pythonhosted.org/packages/f7/c8/dcc42b1cceb69ff032fa16430bd82c086b933e35ef05ab521e56313b76be/pyarrow-26.0.1-cp312-cp312-macosx_12_0_x86_64.whl", hash = "sha256:a2c5e9cec45b318917b630dc040cf197aef624d94866ab2c8e709708057123d2", size = 39757493, upload-time = "2026-11-03T10:49:30.886Z" }, + { url = "https://files.pythonhosted.org/packages/ab/7e/da9831bfcaaa908ae6d5d049c04c2233a5a7e216d6b961e22861056ef3fd/pyarrow-26.0.1-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:6c18167774fb599d42444b7ac558a893d49e750fb14232b538955e6f0d1d51ea", size = 51818506, upload-time = "2026-11-03T10:49:37.89Z" }, + { url = "https://files.pythonhosted.org/packages/d3/79/e2fc9b1317b7a21e7bcd57eb035cac3fe72f47af3efe2ec3b4dea9a08a04/pyarrow-26.0.1-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:c718bf97a92a6dea97fd1062c3b9f9e2e83cb9cc926e752289fa4ffff41738f9", size = 55043763, upload-time = "2026-11-03T10:49:45.732Z" }, + { url = "https://files.pythonhosted.org/packages/e3/66/dbe72f5fa21a92b645d56410bacac605defe63e5d3e9794b2fd8c7d77030/pyarrow-26.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:40aea57ab8bd3cf35a11e604cd7d0c7436dc90d1ce9b88b6711ef2f1a232968e", size = 55438656, upload-time = "2026-11-03T10:49:53.74Z" }, + { url = "https://files.pythonhosted.org/packages/d1/b1/c91322fc4c1800c1f7dd78f911b1dd74187acaeb246d86478a0f064f6af5/pyarrow-26.0.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:73534fbda7f73cab0791b569b93112d4c9e1546cedd0f309d1f69889beb6a08f", size = 58625736, upload-time = "2026-11-03T10:50:01.442Z" }, + { url = "https://files.pythonhosted.org/packages/30/61/d94decccacb4dd40a4ebeed0ff3b2cea8f0b680f50184ea7eb0264db779b/pyarrow-26.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:9379f0d1056cad6866c4697aec83a15830202ec7e0bd52f8bd508b316260fa61", size = 29078866, upload-time = "2026-11-03T10:50:06.854Z" }, + { url = "https://files.pythonhosted.org/packages/15/b8/c31c51fbe7df901817d88c73eeec25079d0da5f7c7b67fc0bf071f6a2df5/pyarrow-26.0.1-cp313-cp313-macosx_12_0_arm64.whl", hash = "sha256:4cb739ccb87292c673e1f69819b68432a73bb8bb456e8599641bba9183a8a1dd", size = 37292947, upload-time = "2026-11-03T10:50:12.333Z" }, + { url = "https://files.pythonhosted.org/packages/fd/63/0c2559ae33ce59d2ca5ce74117676f8ff8da4cf102729a158ea46415eb50/pyarrow-26.0.1-cp313-cp313-macosx_12_0_x86_64.whl", hash = "sha256:50b40aea92f43b2b6da3427548a5337741b4b93b92e8015a8a3eefc0e75acca2", size = 39767535, upload-time = "2026-11-03T10:50:18.254Z" }, + { url = "https://files.pythonhosted.org/packages/31/02/d9462d1ae4e54c3964af38316a802b29c28970b7d375722ef190af736640/pyarrow-26.0.1-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:a3a79661404ba3d41b7c9a45cb56113246a244b38cb1393fadae289bc66b91b4", size = 51815955, upload-time = "2026-11-03T10:50:25.332Z" }, + { url = "https://files.pythonhosted.org/packages/96/54/33c2df56948d88a4d83a52999a4a81a4871b2de481ff25ccd6f5ccd2589a/pyarrow-26.0.1-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:f71221bbc7707e3fad920d0478db9350791d4714ec445299ee0d56559fbc156c", size = 55038406, upload-time = "2026-11-03T10:50:32.551Z" }, + { url = "https://files.pythonhosted.org/packages/99/57/8e1f886ee96c7edab89ab6f15fbb00c85c2bb2173f3cb504925731d00564/pyarrow-26.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:8ccfb9958bcd09f34678c64fb42a0e270b47cd092ae79578da51e0d7bb144296", size = 55437362, upload-time = "2026-11-03T10:50:39.89Z" }, + { url = "https://files.pythonhosted.org/packages/8c/c3/d87939a5f6cd30bb406bad6c20926fcedafc52ec5629f6eb27e4cd5db709/pyarrow-26.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:029e881af986375a2731da79c999fe734a72547fabb16503d65fc079d4bc7eb2", size = 58618865, upload-time = "2026-11-03T10:50:48.029Z" }, + { url = "https://files.pythonhosted.org/packages/c1/9e/b6c8afec2ffc06bbd00a88326826f9d66e4bbca752c0837ee8e2dbf2238f/pyarrow-26.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:8196f36a2f4cb8d2d6ef3651941b80e5ccf125d7653657d99af5bb298e7a7026", size = 28989592, upload-time = "2026-11-03T10:50:53.384Z" }, + { url = "https://files.pythonhosted.org/packages/de/48/999f6e30323e2e95a4439180b62f6308023970e4a37d31497080ea2a1a78/pyarrow-26.0.1-cp314-cp314-macosx_12_0_arm64.whl", hash = "sha256:15435b595c14583f6ac8495c3ef89ac3fed6bc94f168467bfd3b6ba53ad3a643", size = 37334639, upload-time = "2026-11-03T10:50:59.462Z" }, + { url = "https://files.pythonhosted.org/packages/7f/3a/4458972c69ead95af5d3b701c80885133c351075895382499df49ed92d36/pyarrow-26.0.1-cp314-cp314-macosx_12_0_x86_64.whl", hash = "sha256:a44a244867cac106cd326dd0a04be0850d2b8af3b1418ed7aeb8146d13aba360", size = 39802150, upload-time = "2026-11-03T10:51:05.743Z" }, + { url = "https://files.pythonhosted.org/packages/86/d0/fa4bc5d66f78cbc4ec8482b210c2fc3b8cb59564efe171f3ca9be416f8ee/pyarrow-26.0.1-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:0044cb9303c3ae082cc52a2493312109c955bcfa84e87be768736f7d6d8f6257", size = 51880097, upload-time = "2026-11-03T10:51:12.75Z" }, + { url = "https://files.pythonhosted.org/packages/f3/57/755a1b54d37c2a9e2c283d8bc648a50aa4ce57f977ce6a4b1d65eba29f51/pyarrow-26.0.1-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:7ae48ab53610b85e004b03bccff593fbdf22186d0ab48ed42c90797915dac814", size = 55063542, upload-time = "2026-11-03T10:51:20.417Z" }, + { url = "https://files.pythonhosted.org/packages/45/ba/7cd1d78c2ef5a36b1f8d137d1790179875639f197ed90702268084a2470a/pyarrow-26.0.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a97df0c52c966ae8970ac0899ae75d81083c5400eca267de2608ca0f13e6e118", size = 55490507, upload-time = "2026-11-03T10:51:28.295Z" }, + { url = "https://files.pythonhosted.org/packages/9f/02/39e18c5381ad908d7161cc16a02dce03b3db236d3c3ac99fc020878287fb/pyarrow-26.0.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5f665e73790222779613ae3d23d2a1d72f0f13a4646862277e9784bb46e14fca", size = 58648328, upload-time = "2026-11-03T10:51:36.303Z" }, + { url = "https://files.pythonhosted.org/packages/1c/18/2cd453cc2e282d465e9c9b60834d6ca17601dc08e2d402751cb40af92356/pyarrow-26.0.1-cp314-cp314-win_amd64.whl", hash = "sha256:492dc499097968e51cac46e03e0054c68dd3c5f39d75098343f5ad05ec79f7df", size = 29757743, upload-time = "2026-11-03T10:52:35.061Z" }, + { url = "https://files.pythonhosted.org/packages/db/46/b97f117adb46f93620aa94bf13747a81ccc5e099be534cc195c94b281ba7/pyarrow-26.0.1-cp314-cp314t-macosx_12_0_arm64.whl", hash = "sha256:ec196b35270263eda71fc3f43bd31a89b778c6787f19872df5abb9d4264057ff", size = 37452099, upload-time = "2026-11-03T10:51:42.419Z" }, + { url = "https://files.pythonhosted.org/packages/a6/40/ac1796654fc8591049d200f6bcd646a2319509010784f47c1cf6b09d1000/pyarrow-26.0.1-cp314-cp314t-macosx_12_0_x86_64.whl", hash = "sha256:8af2b4e004dc18da8dc77bce27d97c675d2f71348e3ade2741cecac85c3f0c21", size = 39888805, upload-time = "2026-11-03T10:51:48.766Z" }, + { url = "https://files.pythonhosted.org/packages/6c/93/bcff79148416896738a707992570c4ae8e3bb087bc9e0dca8df7dbf6e983/pyarrow-26.0.1-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:c2bf4444a7e86f109dc03e28b2c98eb6671e2eb95e6057c25043d25684e337e9", size = 51884587, upload-time = "2026-11-03T10:51:56.701Z" }, + { url = "https://files.pythonhosted.org/packages/fa/62/cb05e81d31cd1dc97c2e16151425e61fe3a19274ccd1254cafab3a173f96/pyarrow-26.0.1-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:b121de63e2f92704b6b9881fbe69cb3eeca786ea882379b59ce80b8012c1bd8c", size = 55018252, upload-time = "2026-11-03T10:52:05.813Z" }, + { url = "https://files.pythonhosted.org/packages/f8/f5/e8dbbb803bb28a32411491d502679e272c569af7f590816327e84725c748/pyarrow-26.0.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:40b9c1a5841559030ba8d1b8c15d6160bccb702ff2596b4ce296e1efd7665781", size = 55522075, upload-time = "2026-11-03T10:52:14.577Z" }, + { url = "https://files.pythonhosted.org/packages/9b/7a/5000d6082b116359d3db3ee6073a8f708f41cb4bb7d6414f94cd40a90fe7/pyarrow-26.0.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9519f70bd847f7628a2d16324d1ea8827e2ec1da347ee0bf96cc7c248195e923", size = 58625604, upload-time = "2026-11-03T10:52:23.045Z" }, + { url = "https://files.pythonhosted.org/packages/41/70/74a5a07eeee1a84cd51e81813b7fd2d5ffc90192a95981a51e97a8ced99e/pyarrow-26.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:6d9b558e1bce3270f1f422c61fd682615cfb34ffd320a51e765e868e8c155a72", size = 29925653, upload-time = "2026-11-03T10:52:29.188Z" }, +] + +[[package]] +name = "pyerfa" +version = "2.0.1.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "numpy" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/71/39/63cc8291b0cf324ae710df41527faf7d331bce573899199d926b3e492260/pyerfa-2.0.1.5.tar.gz", hash = "sha256:17d6b24fe4846c65d5e7d8c362dcb08199dc63b30a236aedd73875cc83e1f6c0", size = 818430, upload-time = "2024-11-11T15:22:30.852Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7d/d9/3448a57cb5bd19950de6d6ab08bd8fbb3df60baa71726de91d73d76c481b/pyerfa-2.0.1.5-cp39-abi3-macosx_10_9_x86_64.whl", hash = "sha256:b282d7c60c4c47cf629c484c17ac504fcb04abd7b3f4dfcf53ee042afc3a5944", size = 341818, upload-time = "2024-11-11T15:22:16.467Z" }, + { url = "https://files.pythonhosted.org/packages/11/4a/31a363370478b63c6289a34743f2ba2d3ae1bd8223e004d18ab28fb92385/pyerfa-2.0.1.5-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:be1aeb70390dd03a34faf96749d5cabc58437410b4aab7213c512323932427df", size = 329370, upload-time = "2024-11-11T15:22:17.829Z" }, + { url = "https://files.pythonhosted.org/packages/cb/96/b6210fc624123c8ae13e1eecb68fb75e3f3adff216d95eee1c7b05843e3e/pyerfa-2.0.1.5-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b0603e8e1b839327d586c8a627cdc634b795e18b007d84f0cda5500a0908254e", size = 692794, upload-time = "2024-11-11T15:22:19.429Z" }, + { url = "https://files.pythonhosted.org/packages/e5/e0/050018d855d26d3c0b4a7d1b2ed692be758ce276d8289e2a2b44ba1014a5/pyerfa-2.0.1.5-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0e43c7194e3242083f2350b46c09fd4bf8ba1bcc0ebd1460b98fc47fe2389906", size = 738711, upload-time = "2024-11-11T15:22:20.661Z" }, + { url = "https://files.pythonhosted.org/packages/b9/f5/ff91ee77308793ae32fa1e1de95e9edd4551456dd888b4e87c5938657ca5/pyerfa-2.0.1.5-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:07b80cd70701f5d066b1ac8cce406682cfcd667a1186ec7d7ade597239a6021d", size = 722966, upload-time = "2024-11-11T15:22:21.905Z" }, + { url = "https://files.pythonhosted.org/packages/2c/56/b22b35c8551d2228ff8d445e63787112927ca13f6dc9e2c04f69d742c95b/pyerfa-2.0.1.5-cp39-abi3-win32.whl", hash = "sha256:d30b9b0df588ed5467e529d851ea324a67239096dd44703125072fd11b351ea2", size = 339955, upload-time = "2024-11-11T15:22:23.087Z" }, + { url = "https://files.pythonhosted.org/packages/b4/11/97233cf23ad5411ac6f13b1d6ee3888f90ace4f974d9bf9db887aa428912/pyerfa-2.0.1.5-cp39-abi3-win_amd64.whl", hash = "sha256:66292d437dcf75925b694977aa06eb697126e7b86553e620371ed3e48b5e0ad0", size = 349410, upload-time = "2024-11-11T15:22:24.817Z" }, +] + +[[package]] +name = "pygments" +version = "2.21.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/49/2e/ced460408999b33da6b31b0021b0f37d329e202d4169aeb164493778f25b/pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c", size = 5005329, upload-time = "2026-08-17T08:02:48.824Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" }, +] + +[[package]] +name = "pytest" +version = "9.2.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "iniconfig" }, + { name = "packaging" }, + { name = "pluggy" }, + { name = "pygments" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/79/42/bb4641652e58dedeac2ec51abc1f8cae4fee4ec63899a0999016229a0f2a/pytest-9.2.0.tar.gz", hash = "sha256:97c4f3b1f3c7414aa36465e09b8220f1d03627993bd51b1282e193753c80557b", size = 1797555, upload-time = "2026-10-27T21:30:20.728Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/51/39/1f5d8c8877a0fa327db959c19341d4be61660de1ab6b7391f9eb805bcd67/pytest-9.2.0-py3-none-any.whl", hash = "sha256:07acdcf88ec174f907dc01af70bf52d49b014bbab03faeeade31c96b18c2e588", size = 411776, upload-time = "2026-10-27T21:30:19.131Z" }, +] + +[[package]] +name = "pyyaml" +version = "6.0.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" }, + { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" }, + { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" }, + { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" }, + { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" }, + { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" }, + { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" }, + { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" }, + { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" }, + { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" }, + { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" }, + { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" }, + { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" }, + { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" }, + { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" }, + { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" }, + { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" }, + { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" }, + { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" }, + { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, + { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" }, + { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" }, + { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" }, + { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" }, + { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" }, + { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" }, + { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" }, + { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" }, + { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" }, + { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" }, + { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" }, + { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" }, + { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" }, + { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" }, + { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" }, + { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" }, + { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" }, + { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" }, +] + +[[package]] +name = "ruff" +version = "0.17.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/84/0e/3d154514b5bad104f7e1c13169c2d09aa9959fccdc06eb47610ccdfa83ed/ruff-0.17.4.tar.gz", hash = "sha256:f32d178b50e826e00f6c6c1be3f56333068acb9b67fe167143527fa9b81e890d", size = 5357750, upload-time = "2026-11-05T18:52:17.638Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e0/61/c83c78bbb6108f6c6270a106cf12b54175f4f42da088b9bb880f18e31289/ruff-0.17.4-py3-none-linux_armv6l.whl", hash = "sha256:2b08c4ff98dc234f4a3871a3105353b922fa875ea1073ca31001eb8c06bb4d89", size = 10252195, upload-time = "2026-11-05T18:51:36.594Z" }, + { url = "https://files.pythonhosted.org/packages/0a/12/dd158708378866e8b53e145a465dbc51a7cccb9fa197a74d67eaedde7234/ruff-0.17.4-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:13e781c3c5f663e7fba737eaaeb70dd943dd55171daf316afb25cd5268cfe0c7", size = 10266044, upload-time = "2026-11-05T18:51:39.502Z" }, + { url = "https://files.pythonhosted.org/packages/28/32/89a94a8eb11fd505a381ae6f04e190d038d9958695209dc1786ce5cfcda3/ruff-0.17.4-py3-none-macosx_11_0_arm64.whl", hash = "sha256:7ed2f416349944f908f9574215994602242b0836844eba48eec61473033afca0", size = 9432227, upload-time = "2026-11-05T18:51:41.968Z" }, + { url = "https://files.pythonhosted.org/packages/58/de/a392dc38b215798ae72e639d228b7f6c02d826a95d1c0ad7c4c0ee49ef5b/ruff-0.17.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8ea6e0017c785f7282092b11e46338e4ebed1b9e575ebf2e55a8a1eda968241a", size = 10136900, upload-time = "2026-11-05T18:51:44.562Z" }, + { url = "https://files.pythonhosted.org/packages/b7/8f/a880f60f42005f6ffdf58f77af34c7ee327000b5607f48a2f6a69d8b242c/ruff-0.17.4-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7e061dcc0933c7031a616ac8d66ac540309b2aa21ab558101a8f53e9ac7a1185", size = 10051245, upload-time = "2026-11-05T18:51:46.7Z" }, + { url = "https://files.pythonhosted.org/packages/09/55/98844264108af7d5ec27ca3a9cd5a989094ca657a14599c4b69a537a0e9a/ruff-0.17.4-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f99e95a1515161138be3cbd1b06c06e739d8feb38ade35564556999fffc3686e", size = 10704341, upload-time = "2026-11-05T18:51:49.228Z" }, + { url = "https://files.pythonhosted.org/packages/28/a2/5edf97659c3ac7c73f978003bd314936f671037fdac6b978e9de3e4b2b65/ruff-0.17.4-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f28cf0dd37cb172fa5a8d2e92e6ada3a9dbd0609f094ed24039929eef0b7524", size = 11394465, upload-time = "2026-11-05T18:51:51.534Z" }, + { url = "https://files.pythonhosted.org/packages/f2/8f/51371ae856b2bef4d15a044a574695fbc0f6ae63aafa42a2a22428070fb6/ruff-0.17.4-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6b21c771b296888e8a35c6f48555f4b44e4483f61675d6ed51810a5203469ce6", size = 10988262, upload-time = "2026-11-05T18:51:53.91Z" }, + { url = "https://files.pythonhosted.org/packages/af/1b/62874f14c7873f27c7887d2b1ea41de990e14ba9518801ffe8eacb5d51a6/ruff-0.17.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2cd025509b2e15721b426fc70fd946d71f43b3db3b08e946dfec2d696d911690", size = 10572829, upload-time = "2026-11-05T18:51:56.129Z" }, + { url = "https://files.pythonhosted.org/packages/98/30/860b9dae67432b16b88558a9cb2d3194825fa62838f8b9cc49f5d9022095/ruff-0.17.4-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:49b77f7b3921669466882a4881168801bdb06ec2cd83fb936049016cf5fdece1", size = 10617545, upload-time = "2026-11-05T18:51:58.172Z" }, + { url = "https://files.pythonhosted.org/packages/0f/08/781a4b41a1c83fd6e30fea610d6502a6f94e49cf94693fd37bdcbc6bfe11/ruff-0.17.4-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:e3b84eb74f260d1c2dbd236fd9d4c011d4fdd0a52bdf8aea57a10e3a1b71fca5", size = 10111955, upload-time = "2026-11-05T18:52:00.59Z" }, + { url = "https://files.pythonhosted.org/packages/3c/e9/94b1c7b677120f30839254518924f73a8157e9bcfa200edcd5796fecdb99/ruff-0.17.4-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:20e43d7a08e712e33067ba887e6574546c79bd4831596ce8f16803ac7ff9ad90", size = 10058355, upload-time = "2026-11-05T18:52:03.61Z" }, + { url = "https://files.pythonhosted.org/packages/27/5f/a825910b9f309336dc33cb8c0774126662c1d2f765699b3e0a1bd538d01f/ruff-0.17.4-py3-none-musllinux_1_2_i686.whl", hash = "sha256:0d1f4848fd2ec0499be4046db9b7dfcc952666885f00233cc7033515282556a8", size = 10415932, upload-time = "2026-11-05T18:52:06.264Z" }, + { url = "https://files.pythonhosted.org/packages/8b/b8/0796468423413ea4df1a6e2442ae26cf49b8f7dda0eecf246e0d5d0dde54/ruff-0.17.4-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:6007e7f3a0e55b0fbdb947af69cf24c21b4928df6be8ef3e767c69b5ccccf496", size = 10826033, upload-time = "2026-11-05T18:52:08.675Z" }, + { url = "https://files.pythonhosted.org/packages/b9/ab/d8e407669ffe5014429baf780c2df47e001968a6e4c17f615e2e7b13a9ba/ruff-0.17.4-py3-none-win32.whl", hash = "sha256:3971a78cba76298b284c8321e6d40d93045ed348bec5c369d85099efc97fb7cf", size = 9931993, upload-time = "2026-11-05T18:52:11.169Z" }, + { url = "https://files.pythonhosted.org/packages/bd/15/42af8a72d8946e3c9efd2bbf6641e462b6832783b0d043d63ef5b280ba7f/ruff-0.17.4-py3-none-win_amd64.whl", hash = "sha256:67c5a894fc054cf41f75f7afa24815de5a74329d97634126c2a1015740ff4e8c", size = 10292922, upload-time = "2026-11-05T18:52:13.436Z" }, + { url = "https://files.pythonhosted.org/packages/68/9e/f1dbffcfb8ff25dadbc21f87a8b73c3848abe4abada9d4b08ccef8bec40c/ruff-0.17.4-py3-none-win_arm64.whl", hash = "sha256:181ae38a9a8fb94925bf7d0794327b48d7fd7f4b50cfd84c0e999cc09ef8d131", size = 9889396, upload-time = "2026-11-05T18:52:15.549Z" }, +] + +[[package]] +name = "scipy" +version = "1.18.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "numpy" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7e/74/66de6258867beb2ef08f35f9f2ac017a52cacd5081714d239ff1a442d458/scipy-1.18.1.tar.gz", hash = "sha256:52c4b7422442aba924d03ad4019852b08a92e64ea187b933135687bfe2747307", size = 30781235, upload-time = "2026-08-21T23:28:50.599Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/18/f7/240c110c08693826b4513a52f5717d62ec7c7af72f2920821247c03b17b3/scipy-1.18.1-cp312-cp312-macosx_10_15_x86_64.whl", hash = "sha256:457fd7a2a8edeb044ab6ffbc0aa03ff6cd18491356e5e0c834d76ce621b916d1", size = 31111061, upload-time = "2026-08-21T23:23:44.522Z" }, + { url = "https://files.pythonhosted.org/packages/05/4a/78c6285577c375e7cf27277ea8ee6961224327f1e1a0c44af5f17f23635c/scipy-1.18.1-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:e708533e8b2ae2497d65346538a7dcc92814410b25b81432eac66de0f2af8265", size = 28733332, upload-time = "2026-08-21T23:23:50.015Z" }, + { url = "https://files.pythonhosted.org/packages/a5/f6/a5b82f8abbe14d134691b8b903696f701d25a081353a29dc655c364d9e62/scipy-1.18.1-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:7bbf207c4453ce1ad2e00b17313852b33310b83090c2311bdaf97f93c0380d12", size = 20475078, upload-time = "2026-08-21T23:23:54.138Z" }, + { url = "https://files.pythonhosted.org/packages/23/22/0858a0bbd6b3e825ceb8cd9baf9eaf3b2f2b1d77727eb6be40500bcdc92f/scipy-1.18.1-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:78c0665edead396b1abb4897c41a5c1d9bf090c8a637a4c20a61678e0a264e66", size = 23108904, upload-time = "2026-08-21T23:23:57.824Z" }, + { url = "https://files.pythonhosted.org/packages/75/9a/2e71719f31eaefe0e3a1706c4a1ded94e664bfd95ffca2b219a671faee01/scipy-1.18.1-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3c085faa2cfa879c5141df483f836f4d691045a078224a670fa570fa01612d89", size = 34025113, upload-time = "2026-08-21T23:24:02.209Z" }, + { url = "https://files.pythonhosted.org/packages/df/64/ff35eb9e54894cf471ff4716abd3c81eb0a0626869217ce3e6ba4ccf17d7/scipy-1.18.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f55fa87b6c612ecd6b058f167c53231b1d14e412efe361d3d6e38b3631c73218", size = 35344199, upload-time = "2026-08-21T23:24:07.844Z" }, + { url = "https://files.pythonhosted.org/packages/d3/af/c5538be1792f7034c12c7db6ee67cace58253c7b87b122d68253eaf5de89/scipy-1.18.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:c35d74ce0e193ff740c2f2be2ac913ddc232fe6c1ff40b26cfecb9c670c63314", size = 35639587, upload-time = "2026-08-21T23:24:13.05Z" }, + { url = "https://files.pythonhosted.org/packages/91/4c/075e4f66471bac101141ac739e9e135549be1bae584571bd03a530c056e1/scipy-1.18.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:d2924a03db38dc2e848bca2fe9f077dafb891480b91a00a0963a8cf86dfc31c1", size = 37480330, upload-time = "2026-08-21T23:24:19.608Z" }, + { url = "https://files.pythonhosted.org/packages/39/e7/979fd14e75008623df31ba70d6bb144700f68feadcea042021c06a05bf82/scipy-1.18.1-cp312-cp312-win_amd64.whl", hash = "sha256:5e4d44984abc0020154ea81b247adeddcc3ac5527b975ff798bd1ba0adc513c2", size = 36658278, upload-time = "2026-08-21T23:24:25.463Z" }, + { url = "https://files.pythonhosted.org/packages/c7/0b/e1525354ff9d7d5feb6d1b31af6d14072e5c91e9607b421fa1ec889660b3/scipy-1.18.1-cp312-cp312-win_arm64.whl", hash = "sha256:d65d448389b8436493abcf629cc94ad0cf32aecaf06e1acca1de53cc795f2f12", size = 24400588, upload-time = "2026-08-21T23:24:30.579Z" }, + { url = "https://files.pythonhosted.org/packages/b6/55/4540ee0f9c42a9ad7109d0d1a8cc70de54c3572b01c6693a2b1c70e90ceb/scipy-1.18.1-cp313-cp313-macosx_10_15_x86_64.whl", hash = "sha256:3ab3523da44749156e1f68b464dc56af11ae4cbc5c739a49d05f32b982eca9f3", size = 31089958, upload-time = "2026-08-21T23:24:35.8Z" }, + { url = "https://files.pythonhosted.org/packages/2a/f5/769f36d14922b8071a43e95d24d18b6bdafad10d7f5cf647867e1ac052bc/scipy-1.18.1-cp313-cp313-macosx_12_0_arm64.whl", hash = "sha256:e6fb6a55cc0ba97b59a1f288fb86dc6fce8bdfc0fffcbfd015e3a954bf2a2d93", size = 28715106, upload-time = "2026-08-21T23:24:40.775Z" }, + { url = "https://files.pythonhosted.org/packages/9a/d7/21d890274f75ea37a8209d5519e72da3da90302e3b9fb8397a0918386a62/scipy-1.18.1-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:ea324d9dd34c38bfb9bec8ca4d1b407db97dbb74029f566b8e322b1b6fe56fe6", size = 20456846, upload-time = "2026-08-21T23:24:45.066Z" }, + { url = "https://files.pythonhosted.org/packages/ec/01/798430ecea2e78ec7c02663d5f71c007bb6abeca931080debd40d7fa55ea/scipy-1.18.1-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:75b00eb8fb802090aa903f4ea1c7f5a584779f967361e68b7e98e531cc2d7174", size = 23087986, upload-time = "2026-08-21T23:24:49.539Z" }, + { url = "https://files.pythonhosted.org/packages/e6/5f/4634e9d35c68496e4e34cb6946eafab044458e6cedab42b40b6588e475b6/scipy-1.18.1-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d416b16cccfd70fbf62400e84d0bb2f4e6af519a45557f1692c749b37f14b315", size = 33998146, upload-time = "2026-08-21T23:24:54.714Z" }, + { url = "https://files.pythonhosted.org/packages/41/48/6450ed9243315322bbc19ac57b9b70d66a20bf1d38d124c96bc4bf6af9ea/scipy-1.18.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fdaf5ea890a6183d0565f51a61799d67081bd5b1cf03c5f4b3fd3732108625c9", size = 35312578, upload-time = "2026-08-21T23:25:00.44Z" }, + { url = "https://files.pythonhosted.org/packages/00/bd/bf5a4be6a3525676499f6dff307991739ff6fdcad1481b1aeb6745339f58/scipy-1.18.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:c825cef2f49e46753726a7181a8e199804a912b29519ada542c6ebc654951899", size = 35612621, upload-time = "2026-08-21T23:25:06.144Z" }, + { url = "https://files.pythonhosted.org/packages/bd/4e/3c45c33e00a77996c4b1cb707929f833ba7b1d522ee29f882512c330676d/scipy-1.18.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e3b417bf8c2c7c16e8f58ad91db17783ec911ac16e7b50eb6eab6e809b4f5b07", size = 37457323, upload-time = "2026-08-21T23:25:12.483Z" }, + { url = "https://files.pythonhosted.org/packages/93/0e/e0348fbc0dbab65c114cf78957e7dfeb49f8e8b556b4d930cc12ff195e18/scipy-1.18.1-cp313-cp313-win_amd64.whl", hash = "sha256:559ed65f60c1af5a03f3912605a1b5114f522c7c32fb23c3376ae8f03219fe28", size = 36622841, upload-time = "2026-08-21T23:25:18.722Z" }, + { url = "https://files.pythonhosted.org/packages/50/a8/6a77f5f267c555108f0a864b6db714363dab567a8266422a79a385f9232b/scipy-1.18.1-cp313-cp313-win_arm64.whl", hash = "sha256:cd479fc04dd9401e3b4f49e76518768ef99c4f517a98c284eb091fd725719adf", size = 24399315, upload-time = "2026-08-21T23:25:23.458Z" }, + { url = "https://files.pythonhosted.org/packages/06/d5/d8eb4e280ddb56a4ab2c6f02ee49b56b23f6e977cf0802fd6d68dbef14f5/scipy-1.18.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:83de5453a7799afc9048b4616bd085cef126e36412f0ea2f6370c36a2a3a51e7", size = 31090936, upload-time = "2026-08-21T23:25:28.686Z" }, + { url = "https://files.pythonhosted.org/packages/2a/49/59ea385dc3a62ff498ddf3cfff7c2b41b0f9f9d3c4122b3f1dcb6d6327fe/scipy-1.18.1-cp314-cp314-macosx_12_0_arm64.whl", hash = "sha256:9554bcc6d715ee87a633a3cc8e7703c6628b100dd29cb8a2efc4c0533c7ff729", size = 28725221, upload-time = "2026-08-21T23:25:33.244Z" }, + { url = "https://files.pythonhosted.org/packages/70/e8/6b0c288c50942d78193696c9f15f9a0874f5178aa0ddf40f83d9924b3e8d/scipy-1.18.1-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:011413b7426b75012840e35649e00fe0a2c3bae89fed433876e3a99251572efc", size = 20466839, upload-time = "2026-08-21T23:25:37.516Z" }, + { url = "https://files.pythonhosted.org/packages/4b/e0/54fd3793c729e3b936782f181b59cbb1205bf250ab605a16cb1ba61cdd5e/scipy-1.18.1-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:88f0e784020649f88ea48c9f5ddfa403bf9205820667c0914740b392035afb82", size = 23089121, upload-time = "2026-08-21T23:25:42.019Z" }, + { url = "https://files.pythonhosted.org/packages/0b/56/030af62bea3cf878e0028515dff78c123b01633606a879b63f42d2db99cc/scipy-1.18.1-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2d3ab0e8c69a17dd3559eab8cbb88f258e285c94d572c2719033f90f83290c89", size = 34053851, upload-time = "2026-08-21T23:25:47.998Z" }, + { url = "https://files.pythonhosted.org/packages/6b/89/2a844506d49651e9aa1af6ef95b6bd8031cb1d5a4375edec6155037e04cf/scipy-1.18.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ac0333bdf38309aa3dcbe7e3fa7ea29e7a2c37c6ea306a757b700ded8e4596ad", size = 35329183, upload-time = "2026-08-21T23:25:53.522Z" }, + { url = "https://files.pythonhosted.org/packages/eb/56/c7370c3640e92ac9613cbf26cb3f729f9b12ddf1727b55b94b53b24d6f48/scipy-1.18.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:911de823097db8b63f034299d12662db93344e6ffa0b881cbb57748974b70168", size = 35672551, upload-time = "2026-08-21T23:25:59.387Z" }, + { url = "https://files.pythonhosted.org/packages/24/16/ec8536f351421f8bf60a1120930638f83790f4710b8230446aca3d6159d4/scipy-1.18.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:95298364e251be3e60249facbeeca03631d3bb7584f85879516ec55ac717b81f", size = 37469416, upload-time = "2026-08-21T23:26:05.432Z" }, + { url = "https://files.pythonhosted.org/packages/52/94/d73da0d28f16c45bb9b0a5691b91610b0275c5ef0eb5e43c87cf2dc1bf31/scipy-1.18.1-cp314-cp314-win_amd64.whl", hash = "sha256:78a0d7c918e74a232394117160e7e3db503377572a45bcef8826e4ab8a35feba", size = 37362755, upload-time = "2026-08-21T23:26:11.366Z" }, + { url = "https://files.pythonhosted.org/packages/89/25/e996e4dc74e10e227b1e14db5eaf6608bb6dd33884a64851c38f18dd4249/scipy-1.18.1-cp314-cp314-win_arm64.whl", hash = "sha256:cbf38d043c1aa4ab306e1ada6ab6eddacc3322a20b7af1b30bc93254b366fe09", size = 25036090, upload-time = "2026-08-21T23:26:15.887Z" }, + { url = "https://files.pythonhosted.org/packages/fa/c9/c00213f92309d753b48903e6a451b87eb52ff5b7a16e789d1568bbf221c4/scipy-1.18.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:0fcb3c93519f27bb4f0c4b0f7802cdcaca7fcf93267b75edda2e9f4e8a55cbd7", size = 31485550, upload-time = "2026-08-21T23:26:20.776Z" }, + { url = "https://files.pythonhosted.org/packages/74/b2/e3067c487982d4eeab2938928529410370c06fea84a4d3f4925e7d96647d/scipy-1.18.1-cp314-cp314t-macosx_12_0_arm64.whl", hash = "sha256:ddef79fb382df40104a19bb7151b3b23e57c1778fcf857c71ceecd9bd264513f", size = 29174642, upload-time = "2026-08-21T23:26:25.395Z" }, + { url = "https://files.pythonhosted.org/packages/d5/ab/374c9fe2d1ec014e576c781a4b5d8e1ba340e8f6b4638c16f711d2b194f0/scipy-1.18.1-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:0e82073ecc7acc6436fac4b31674109c7e1d3e596789767eda01258a8c9e8123", size = 20916357, upload-time = "2026-08-21T23:26:30.112Z" }, + { url = "https://files.pythonhosted.org/packages/90/38/223915c88a17317cafbf8ca2a42b11c265a9fb1e804aa665544132b5fe8a/scipy-1.18.1-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:8bcf3c1ba5d6456e2effd30fcbd3459b044d683fcdac79a2e6830f0bdf7de487", size = 23482611, upload-time = "2026-08-21T23:26:34.846Z" }, + { url = "https://files.pythonhosted.org/packages/c4/d1/db0948da8ca57a80b36520ef0a768b967d99f3af65f4b6f1bf6362ad4dd4/scipy-1.18.1-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:cfbf154f2ba187f2ed6cce2639efff7d105f1140573642c0161615b6d91d6a87", size = 34143202, upload-time = "2026-08-21T23:26:40.4Z" }, + { url = "https://files.pythonhosted.org/packages/87/53/39d046cc7574ed6acacb6bd5723e220107ece80bff12faaf3efc4ddeede4/scipy-1.18.1-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a1d33a7836f7ddc1993427966a0823468ec41bcbdb1a9f9942d1d7e57f803ba3", size = 35380876, upload-time = "2026-08-21T23:26:46.1Z" }, + { url = "https://files.pythonhosted.org/packages/f9/da/32e0e799d875a85ca57d9bde6c78148afcc0e38276df683d95854eadc8c3/scipy-1.18.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7f4b8bc363b6d65ee2152bec57568e3c52639bb34c46057b09857a307ed5e21d", size = 35770885, upload-time = "2026-08-21T23:26:51.533Z" }, + { url = "https://files.pythonhosted.org/packages/88/2e/f97a666d362fee68b18f41c9c30ed502ca5c98b549749bfcb52a8b74d1eb/scipy-1.18.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:11c423f1049c5755ad4409af52a9ada1cff96fe9b50795d4af3619f292901239", size = 37525424, upload-time = "2026-08-21T23:26:56.751Z" }, + { url = "https://files.pythonhosted.org/packages/ca/d5/a9e765a84654ebba8479a1fd1b059ced1af72b168a3b2a3a46540ea38d20/scipy-1.18.1-cp314-cp314t-win_amd64.whl", hash = "sha256:c24acac1e18912761c4700239bbc1fd32f615af690f1584d49b35859be51324d", size = 37416961, upload-time = "2026-08-21T23:27:01.546Z" }, + { url = "https://files.pythonhosted.org/packages/ee/16/e79e0d1c63ef698879d85439d37e9fb434e3b804e506a6991038d086ebd9/scipy-1.18.1-cp314-cp314t-win_arm64.whl", hash = "sha256:9f2897bf7737392ad0d5213ea7b6add72a4edf5679b3153106aeb88b6507b3b9", size = 25331848, upload-time = "2026-08-21T23:27:05.884Z" }, +] + +[[package]] +name = "soupsieve" +version = "4.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/95/48/21a393ff731b8f928fa4f8176f9a7ceba2252ee60a5149f25b45c292aa5c/soupsieve-4.1.tar.gz", hash = "sha256:ca9abf7126667010d8f6e9b39bfc1bc3b23c8aed9bcb0f54a754dde969bb8aab", size = 161955, upload-time = "2026-11-10T01:59:50.399Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/88/73/6a2087c72975cfc07394623bca8d17654342ea4055ae368deafe5a81a542/soupsieve-4.1-py3-none-any.whl", hash = "sha256:e4d667b3974ce6e038e7390486b8093369854a1d345ffdd4c121dfc4a782e809", size = 52302, upload-time = "2026-11-10T01:59:48.571Z" }, +] + +[[package]] +name = "types-beautifulsoup4" +version = "4.12.0.20250516" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "types-html5lib" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6d/d1/32b410f6d65eda94d3dfb0b3d0ca151f12cb1dc4cef731dcf7cbfd8716ff/types_beautifulsoup4-4.12.0.20250516.tar.gz", hash = "sha256:aa19dd73b33b70d6296adf92da8ab8a0c945c507e6fb7d5db553415cc77b417e", size = 16628, upload-time = "2025-05-16T03:09:09.93Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7c/79/d84de200a80085b32f12c5820d4fd0addcbe7ba6dce8c1c9d8605e833c8e/types_beautifulsoup4-4.12.0.20250516-py3-none-any.whl", hash = "sha256:5923399d4a1ba9cc8f0096fe334cc732e130269541d66261bb42ab039c0376ee", size = 16879, upload-time = "2025-05-16T03:09:09.051Z" }, +] + +[[package]] +name = "types-html5lib" +version = "1.1.11.20260518" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "types-webencodings" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b8/5a/0c708d1b0d35ad48b6a223c77c4a882fd016b40c25becb082a92e02a9c00/types_html5lib-1.1.11.20260518.tar.gz", hash = "sha256:4f33c087cb1119d65c4c80eca4323c2b501f9eaf8af9616b8b732ed4d8eae8fa", size = 18420, upload-time = "2026-05-18T06:07:23.662Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/4d/d0/b088b9f11eb69637d6826843f06caaff60247156735a25512922d3dc2c13/types_html5lib-1.1.11.20260518-py3-none-any.whl", hash = "sha256:9baa7912224ebb37027c5ccb7e3768e43ea47b1dfdd977e7ddc4b0a4a550584d", size = 24339, upload-time = "2026-05-18T06:07:22.876Z" }, +] + +[[package]] +name = "types-webencodings" +version = "0.6.0.20261104" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/63/b8/722e153333019ac643dfac24be7c8d2fa21cbea791c94c39a1c58f413211/types_webencodings-0.6.0.20261104.tar.gz", hash = "sha256:3021d7ea7011a4a51a43b2dc4c0e4856c8d9b1bb1a1a3d2500ab177224225b08", size = 7818, upload-time = "2026-11-04T08:13:58.651Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cb/3b/93a20758bf4b0a388a97672c7bd8212856bf744f6894fdaa8d2f877815cd/types_webencodings-0.6.0.20261104-py3-none-any.whl", hash = "sha256:a719903a309f35d43a99461e801df94af2def074dec2694423c7a2601ddcc45d", size = 8577, upload-time = "2026-11-04T08:13:57.726Z" }, +] + +[[package]] +name = "typing-extensions" +version = "4.16.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" }, +] diff --git a/scripts/ci/dev_changes.py b/scripts/ci/dev_changes.py new file mode 100644 index 00000000..95c2932b --- /dev/null +++ b/scripts/ci/dev_changes.py @@ -0,0 +1,175 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Classify developer-tool dependencies without installing developer tools.""" + +from __future__ import annotations + +import argparse +import json +import os +import re +import subprocess +from pathlib import Path +from typing import Any + +DEPENDENCIES = ( + "dev/", + "src/cuphoton/core/", + "tests/core/", + "docs/guide/", + "examples/", + ".github/workflows/", + "scripts/ci/", + "scripts/conda/", + "scripts/wheels/", + "conda/", +) +METADATA = { + "pyproject.toml", + "uv.lock", + "setup.py", + "setup.cfg", + "MANIFEST.in", + "Makefile", + ".gitattributes", + ".gitignore", + ".pre-commit-config.yaml", + ".coveragerc", + "pytest.ini", + "tox.ini", + "mypy.ini", + "ruff.toml", + ".ruff.toml", + "tests/conftest.py", +} + + +def affects_dev(path: str) -> bool: + """Unknown paths run the tests; only established unrelated paths skip.""" + if path in METADATA or path.startswith(DEPENDENCIES): + return True + if path.startswith("src/cuphoton/"): + # Package entrypoints can change the lazy developer CLI route. + return "/" not in path.removeprefix("src/cuphoton/") + if path.startswith("tests/"): + return "/" not in path.removeprefix("tests/") + return not ( + path.startswith(("docs/", "licenses/", ".github/ISSUE_TEMPLATE/")) + or path + in { + "README.md", + "README-pypi.md", + "CONTRIBUTING.md", + "CODE_OF_CONDUCT.md", + "SECURITY.md", + "LICENSE", + "THIRD_PARTY_NOTICES.md", + ".github/PULL_REQUEST_TEMPLATE.md", + } + ) + + +def command(*args: str) -> str: + return subprocess.check_output(args, text=True, stderr=subprocess.PIPE) + + +def ensure_commit(sha: str) -> None: + if not re.fullmatch(r"[0-9a-f]{40}", sha): + raise ValueError("Comparison needs a complete commit SHA") + try: + command("git", "cat-file", "-e", f"{sha}^{{commit}}") + except subprocess.CalledProcessError: + command("git", "fetch", "--no-tags", "origin", sha) + + +def comparison( + event: dict[str, Any], event_name: str, ref: str, repository: str +) -> tuple[str, str, bool]: + """Return base, head and whether to compare from their merge base.""" + if event_name == "pull_request": + pr = event["pull_request"] + return pr["base"]["sha"], pr["head"]["sha"], True + if event_name != "push": + raise ValueError(f"Unsupported event: {event_name}") + copied = re.fullmatch(r"refs/heads/pull-request/(\d+)", ref) + if copied: + if repository != "NVIDIA/cuPhoton": + raise ValueError("Unrecognized repository for a vetted PR copy") + pr = json.loads( + command("gh", "api", f"repos/{repository}/pulls/{copied[1]}") + ) + if pr["head"]["sha"] != event["after"]: + raise ValueError("Vetted copy no longer matches the PR head") + return pr["base"]["sha"], event["after"], True + if event["before"] == "0" * 40 or event["after"] == "0" * 40: + raise ValueError("Branch creation or deletion has no complete range") + return event["before"], event["after"], False + + +def changed_paths(base: str, head: str, merge_base: bool) -> list[str]: + ensure_commit(base) + ensure_commit(head) + if merge_base: + base = command("git", "merge-base", base, head).strip() + # Disabling rename detection lists both old and new names. A dependency + # moved out of its directory still invalidates developer tests. + output = command( + "git", "diff", "--name-only", "--no-renames", "-z", base, head + ) + return [path for path in output.split("\0") if path] + + +def classify( + event: dict[str, Any], event_name: str, ref: str, repository: str +) -> dict[str, Any]: + try: + base, head, merge_base = comparison( + event, event_name, ref, repository + ) + paths = changed_paths(base, head, merge_base) + except ( + KeyError, + ValueError, + OSError, + subprocess.CalledProcessError, + ) as exc: + return { + "dev": True, + "reason": f"Uncertain comparison: {type(exc).__name__}", + } + relevant = [path for path in paths if affects_dev(path)] + return { + "dev": bool(relevant), + "base": base, + "head": head, + "merge_base": merge_base, + "paths": relevant, + "reason": "Dependency changed" + if relevant + else "No dependency changed", + } + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--event", type=Path, default=os.getenv("GITHUB_EVENT_PATH") + ) + args = parser.parse_args() + event = json.loads(args.event.read_text()) + result = classify( + event, + os.environ["GITHUB_EVENT_NAME"], + os.environ["GITHUB_REF"], + os.environ["GITHUB_REPOSITORY"], + ) + print(json.dumps(result, sort_keys=True)) + if output := os.getenv("GITHUB_OUTPUT"): + with Path(output).open("a") as stream: + stream.write(f"dev={str(result['dev']).lower()}\n") + + +if __name__ == "__main__": + main() diff --git a/src/cuphoton/core/cli/app.py b/src/cuphoton/core/cli/app.py index e4ee59a0..8f859de9 100644 --- a/src/cuphoton/core/cli/app.py +++ b/src/cuphoton/core/cli/app.py @@ -8,6 +8,7 @@ import argparse import importlib +import importlib.metadata import sys from collections.abc import Mapping, Sequence from contextlib import redirect_stderr, redirect_stdout @@ -541,7 +542,7 @@ def main( environ: Mapping[str, str] | None = None, program_name: str = "cuphoton", ) -> int: - """Route the root executable to one of the six public components.""" + """Route the root executable to a product or installed developer group.""" args = list(sys.argv[1:] if argv is None else argv) output = sys.stdout if out is None else out @@ -558,6 +559,28 @@ def main( routed = args if args[0] == "help" and len(args) > 1: routed = [args[1], "help", *args[2:]] + if routed[0] == "dev": + if not _developer_tools_installed(): + error.write( + "ERROR: Developer tools are not installed. From a cuPhoton " + "checkout, run 'uv sync --project dev --locked', then " + "'uv run --project dev --locked cuphoton dev --help'.\n" + ) + return 2 + try: + developer_cli = importlib.import_module("cuphoton_dev.cli") + return int( + developer_cli.main( + routed[1:], + out=output, + err=error, + environ=environ, + program_name=f"{program_name} dev", + ) + ) + except ImportError as exc: + error.write(f"ERROR: Cannot load developer tools: {exc}\n") + return 1 spec = COMPONENT_REGISTRY.get(routed[0]) if spec is None: error.write(f"ERROR: Unknown component group '{routed[0]}'\n") @@ -601,9 +624,21 @@ def _print_root_help(out: TextIO, program_name: str) -> None: out.write("Available groups:\n") for component in COMPONENTS: out.write(f" {component.group} {component.description}\n") + if _developer_tools_installed(): + out.write(" dev Repository development and documentation tools.\n") out.write(f"\nUse '{program_name} GROUP --help' for group help.\n") +def _developer_tools_installed() -> bool: + """Require explicit installation without importing developer code.""" + + try: + importlib.metadata.distribution("cuphoton-dev") + except importlib.metadata.PackageNotFoundError: + return False + return True + + __all__ = [ "CommandLine", "CLI", diff --git a/src/cuphoton/core/cli/component.py b/src/cuphoton/core/cli/component.py index 3dbbf8dd..0199d7c1 100644 --- a/src/cuphoton/core/cli/component.py +++ b/src/cuphoton/core/cli/component.py @@ -37,7 +37,10 @@ def __post_init__(self) -> None: "contain only lowercase letters and digits" ) import_suffix = self.import_name.removeprefix("cuphoton.") - if ( + developer_tool = ( + self.group == "dev" and self.import_name == "cuphoton_dev" + ) + if not developer_tool and ( not self.import_name.startswith("cuphoton.") or not import_suffix or any( @@ -45,7 +48,8 @@ def __post_init__(self) -> None: ) ): raise ValueError( - "component import_name must be within the cuphoton namespace" + "component import_name must be within the cuphoton namespace " + "or use the dedicated cuphoton_dev specification" ) if self.parser_style not in {"optparse", "argparse"}: raise ValueError(f"unknown parser style: {self.parser_style!r}") From 324db2ed810fd1ffb93f9bea5382b49a1eb8763d Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Wed, 11 Nov 2026 19:03:39 -0800 Subject: [PATCH 2/9] Document the generated Pages archive commit policy Signed-off-by: Trent Nelson --- CONTRIBUTING.md | 6 ++++++ dev/AGENTS.md | 4 +++- dev/README.md | 4 ++++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0cc2372d..306c6a3f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -259,6 +259,12 @@ git commit -sS -m "Short imperative summary" - Write commit titles in imperative mood. - Target the `main` branch. +These commit requirements apply to source contributions. The generated +`gh-pages` documentation archive uses GitHub Actions bot commits, exempt from +source identity, signature and DCO requirements. The +[publication runbook](dev/README.md#site-layout-and-ownership) describes its +source and controller provenance. + ## Developer Certificate of Origin By making a contribution to this project, you certify the Developer Certificate diff --git a/dev/AGENTS.md b/dev/AGENTS.md index f6829531..c400e277 100644 --- a/dev/AGENTS.md +++ b/dev/AGENTS.md @@ -27,5 +27,7 @@ Scope: the independent `dev/` project and its documentation publishing workflows Exercise real main and release renders, navigation, search, themes and bookmark redirects when changing transformations or publication behavior. Inspect deployed URLs and hashes before reporting a rollout complete. -- Follow the repository's Apache-2.0 SPDX/copyright, signed-commit and DCO rules. +- Follow the repository's Apache-2.0 SPDX/copyright, signed-commit and DCO rules + for source changes. Generated `gh-pages` output uses GitHub Actions bot + commits and is exempt from source identity, signature and DCO requirements. Keep local environments, output trees, review notes and credentials untracked. diff --git a/dev/README.md b/dev/README.md index cb6fde34..7d8ddeb7 100644 --- a/dev/README.md +++ b/dev/README.md @@ -112,6 +112,10 @@ release links, install examples, labels, search data and canonical URLs. The `gh-pages` branch retains complete validated output. Main publications replace only `main/`; release publications retain existing release bytes. Catalogs and redirects are generated, not hand-maintained. +The publisher records this generated output with GitHub Actions bot commits. +These archive commits are exempt from source-contribution identity, signature +and DCO requirements; each snapshot records its signed source and controller +revisions. Source changes continue to follow the contributor signing rules. ## Publish, bootstrap and recover From e8bb899cedb4b8439716931ec99190bcc57bdeda Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Wed, 11 Nov 2026 21:34:08 -0800 Subject: [PATCH 3/9] Guard documentation publication and preserve recovery details Recheck remote release tags immediately before publication so a tag changed during rendering cannot publish stale output. Use explicit UTF-8 and resolve directory links correctly when validating snapshots. Keep request and run metadata in JSON when a publication fails or stops being observable, so callers can recover without blind redispatches. Clarify that snapshot receipts record commit SHAs. Signed-off-by: Trent Nelson --- dev/README.md | 9 +- dev/src/cuphoton_dev/archive.py | 23 +++-- dev/src/cuphoton_dev/build.py | 6 +- dev/src/cuphoton_dev/cli.py | 20 ++-- dev/src/cuphoton_dev/github.py | 67 ++++++++++--- dev/src/cuphoton_dev/publisher.py | 38 +++++++- dev/src/cuphoton_dev/renderers.py | 1 + dev/src/cuphoton_dev/transforms.py | 48 +++++++--- dev/tests/test_cli.py | 134 ++++++++++++++++++++++++++ dev/tests/test_prepare.py | 69 ++++++++++++++ dev/tests/test_publisher.py | 8 +- dev/tests/test_transforms.py | 145 ++++++++++++++++++++++++++++- 12 files changed, 518 insertions(+), 50 deletions(-) diff --git a/dev/README.md b/dev/README.md index 7d8ddeb7..ec23f3e1 100644 --- a/dev/README.md +++ b/dev/README.md @@ -114,8 +114,8 @@ replace only `main/`; release publications retain existing release bytes. Catalogs and redirects are generated, not hand-maintained. The publisher records this generated output with GitHub Actions bot commits. These archive commits are exempt from source-contribution identity, signature -and DCO requirements; each snapshot records its signed source and controller -revisions. Source changes continue to follow the contributor signing rules. +and DCO requirements; each snapshot records the source and controller commit +SHAs. Source changes continue to follow the contributor signing rules. ## Publish, bootstrap and recover @@ -123,7 +123,10 @@ Authenticate `gh` with access to dispatch repository Actions. For a normal publication, the CLI dispatches `docs.yml` explicitly on main and reports the exact run URL. It waits for completion and returns a failing exit status when the workflow fails. Use `--json` for machine-readable results or `--no-wait` -to return after dispatch. +to return after dispatch. Failed runs and wait timeouts retain the known +request and workflow fields in JSON output while returning a failing exit +status. An accepted dispatch whose run is not yet discoverable reports its +request ID with null run fields; use that ID before attempting a new dispatch. ```sh uv run --project dev --locked cuphoton dev docs-publish --ref main --json diff --git a/dev/src/cuphoton_dev/archive.py b/dev/src/cuphoton_dev/archive.py index 1651decb..cf3effe1 100644 --- a/dev/src/cuphoton_dev/archive.py +++ b/dev/src/cuphoton_dev/archive.py @@ -19,7 +19,9 @@ def _json(path: Path, value: Any) -> None: - path.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n") + path.write_text( + json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8" + ) def _release_key(version: str) -> tuple[int, ...]: @@ -135,7 +137,7 @@ def _generate(archive: Path, catalog: dict[str, Any]) -> None: for alias, target in catalog["aliases"].items(): file = archive / alias file.parent.mkdir(parents=True, exist_ok=True) - file.write_text(redirect_html(target)) + file.write_text(redirect_html(target), encoding="utf-8") items = "".join( f'
  • ' f"{html.escape(entry['version'])}" @@ -149,7 +151,8 @@ def _generate(archive: Path, catalog: dict[str, Any]) -> None: "cuPhoton documentation versions" "

    cuPhoton documentation versions

      " + items - + "
    \n" + + "\n", + encoding="utf-8", ) (archive / ".nojekyll").touch() @@ -180,7 +183,9 @@ def assemble( receipts = _snapshots(archive) legacy_pages: set[str] = set() if (archive / "versions.json").is_file(): - previous_catalog = json.loads((archive / "versions.json").read_text()) + previous_catalog = json.loads( + (archive / "versions.json").read_text(encoding="utf-8") + ) legacy_pages.update(previous_catalog["legacy_pages"]) previous = receipts.get(version) reuse = False @@ -242,7 +247,9 @@ def check_archive(path: Path) -> dict[str, Any]: entry.is_file() and entry.stat().st_nlink != 1 ): raise ValueError(f"Archive contains a link: {entry}") - catalog: dict[str, Any] = json.loads((path / "versions.json").read_text()) + catalog: dict[str, Any] = json.loads( + (path / "versions.json").read_text(encoding="utf-8") + ) if catalog.get("schema") != 1: raise ValueError("Unsupported documentation catalog schema") receipts = _snapshots(path) @@ -254,9 +261,9 @@ def check_archive(path: Path) -> dict[str, Any]: raise ValueError("Catalog does not match retained snapshots") for alias, target in catalog["aliases"].items(): redirect = path / alias - if not redirect.is_file() or redirect.read_text() != redirect_html( - target - ): + if not redirect.is_file() or redirect.read_text( + encoding="utf-8" + ) != redirect_html(target): raise ValueError(f"Invalid legacy redirect: {alias}") resolved = (redirect.parent / target).resolve() if ( diff --git a/dev/src/cuphoton_dev/build.py b/dev/src/cuphoton_dev/build.py index 4ffe4945..e321444a 100644 --- a/dev/src/cuphoton_dev/build.py +++ b/dev/src/cuphoton_dev/build.py @@ -34,6 +34,7 @@ def run( cwd=cwd, env=env, text=True, + encoding="utf-8", stdout=subprocess.PIPE, stderr=subprocess.STDOUT, ) as process: @@ -49,6 +50,7 @@ def run( cwd=cwd, env=env, text=True, + encoding="utf-8", capture_output=True, ) if result.returncode: @@ -147,7 +149,9 @@ def docs_build( raise ValueError( f"Documentation is unavailable at {ref} ({source_sha})" ) - workflow = (checkout / ".github/workflows/docs.yml").read_text() + workflow = (checkout / ".github/workflows/docs.yml").read_text( + encoding="utf-8" + ) pin = re.search(r"releases/download/v([\d.]+)/quarto", workflow) if not pin: raise ValueError( diff --git a/dev/src/cuphoton_dev/cli.py b/dev/src/cuphoton_dev/cli.py index 25aa883b..0c2a7f3a 100644 --- a/dev/src/cuphoton_dev/cli.py +++ b/dev/src/cuphoton_dev/cli.py @@ -131,18 +131,24 @@ class NoWaitArg(BoolInvariant): ) def run(self) -> None: + from .github import PublicationError from .publisher import docs_publish if (self.ref is None) == (not self.missing): raise ValueError("supply exactly one of --ref or --missing") - self.emit( - docs_publish( - ref=self.ref, - missing=self.missing, - wait=not self.no_wait, - repository=self.repository, + try: + self.emit( + docs_publish( + ref=self.ref, + missing=self.missing, + wait=not self.no_wait, + repository=self.repository, + ) ) - ) + except PublicationError as exc: + if self.json: + self.emit(exc.result) + raise def main( diff --git a/dev/src/cuphoton_dev/github.py b/dev/src/cuphoton_dev/github.py index e3999295..cd91023b 100644 --- a/dev/src/cuphoton_dev/github.py +++ b/dev/src/cuphoton_dev/github.py @@ -20,6 +20,14 @@ SITE = "https://nvidia.github.io/cuPhoton/" +class PublicationError(RuntimeError): + """Publication failure retaining the known request and workflow state.""" + + def __init__(self, message: str, result: dict[str, Any]) -> None: + super().__init__(message) + self.result = {**result, "error": message} + + def api( path: str, *, data: dict[str, Any] | None = None, missing_ok: bool = False ) -> Any: @@ -30,6 +38,7 @@ def api( args, input=json.dumps(data) if data is not None else None, text=True, + encoding="utf-8", capture_output=True, ) if result.returncode: @@ -127,8 +136,22 @@ def wait_for_run( repository: str, run_id: int, *, wait: bool, request_id: str ) -> dict[str, Any]: deadline = time.monotonic() + 7200 + result: dict[str, Any] = { + "request_id": request_id, + "run_id": run_id, + "url": None, + "status": "unknown", + "conclusion": None, + "controller_sha": None, + } while True: - run = api(f"repos/{repository}/actions/runs/{run_id}") + try: + run = api(f"repos/{repository}/actions/runs/{run_id}") + except (RuntimeError, OSError, ValueError) as exc: + raise PublicationError( + f"Cannot read documentation publication run {run_id}: {exc}", + result, + ) from exc result = { "request_id": request_id, "run_id": run_id, @@ -139,16 +162,18 @@ def wait_for_run( } if run["status"] == "completed": if run["conclusion"] != "success": - raise RuntimeError( + raise PublicationError( f"Documentation publication {run['conclusion']}: " - f"{run['html_url']}" + f"{run['html_url']}", + result, ) return result if not wait: return result if time.monotonic() >= deadline: - raise RuntimeError( - f"Publication still running; inspect {run['html_url']}" + raise PublicationError( + f"Publication still running; inspect {run['html_url']}", + result, ) time.sleep(5) @@ -188,25 +213,43 @@ def docs_publish( if run_id is None: # Older API deployments return 204. Correlate our unique request # instead of selecting another caller's latest run. + accepted = { + "request_id": request_id, + "run_id": None, + "url": None, + "status": "dispatch_accepted", + "conclusion": None, + "controller_sha": None, + } deadline = time.monotonic() + 180 while run_id is None: - runs = api( - f"repos/{repository}/actions/workflows/docs.yml/runs" - "?event=workflow_dispatch&branch=main&per_page=100" - ) + try: + runs = api( + f"repos/{repository}/actions/workflows/docs.yml/runs" + "?event=workflow_dispatch&branch=main&per_page=100" + ) + except (RuntimeError, OSError, ValueError) as exc: + raise PublicationError( + f"Dispatch accepted; cannot find request {request_id}: " + f"{exc}. Do not redispatch blindly.", + accepted, + ) from exc matches = [ r for r in runs["workflow_runs"] if request_id in r["display_title"] ] if len(matches) > 1: - raise RuntimeError(f"Ambiguous workflow request {request_id}") + raise PublicationError( + f"Ambiguous workflow request {request_id}", accepted + ) if matches: run_id = matches[0]["id"] elif time.monotonic() >= deadline: - raise RuntimeError( + raise PublicationError( f"Dispatch accepted; run not found for {request_id}. " - "Do not redispatch blindly." + "Do not redispatch blindly.", + accepted, ) else: time.sleep(3) diff --git a/dev/src/cuphoton_dev/publisher.py b/dev/src/cuphoton_dev/publisher.py index 6acbf830..353980ff 100644 --- a/dev/src/cuphoton_dev/publisher.py +++ b/dev/src/cuphoton_dev/publisher.py @@ -41,12 +41,36 @@ def is_ancestor(repo: Path, older: str, newer: str) -> bool: ["git", "-C", str(repo), "merge-base", "--is-ancestor", older, newer], capture_output=True, text=True, + encoding="utf-8", ) if result.returncode not in (0, 1): raise RuntimeError(f"Cannot establish main ancestry: {result.stderr}") return result.returncode == 0 +def remote_tag_commit(tag: str) -> str: + """Read the canonical tag, peeling annotated tags to their target.""" + if not FINAL_TAG.fullmatch(tag): + raise ValueError(f"Expected a full release tag: {tag}") + ref = f"refs/tags/{tag}" + rows = run( + [ + "git", + "ls-remote", + "--tags", + f"https://github.com/{REPOSITORY}.git", + ref, + ref + "^{}", + ] + ) + refs = { + name: sha for sha, name in (row.split() for row in rows.splitlines()) + } + if ref not in refs: + raise ValueError(f"Release tag is missing from the remote: {tag}") + return refs.get(ref + "^{}", refs[ref]) + + def clone_archive(destination: Path) -> None: remote = f"https://github.com/{REPOSITORY}.git" existing = run( @@ -127,11 +151,14 @@ def prepare( and "main" not in targets ): targets.insert(0, "main") + release_sources: dict[str, str] = {} for target in targets: source_ref = ( controller if target == "main" else f"refs/tags/{target}" ) source_sha = resolve(repo, source_ref) + if target != "main": + release_sources[target] = source_sha prior = retained / target receipt = check_snapshot(prior) if prior.exists() else None if ( @@ -188,7 +215,8 @@ def prepare( ) catalog = check_archive(retained) git(retained, "add", "--all") - if git(retained, "status", "--porcelain"): + changed = bool(git(retained, "status", "--porcelain")) + if changed: git( retained, "-c", @@ -201,6 +229,14 @@ def prepare( "-m", "Retain validated documentation and refresh version routes", ) + # Tags can move independently of Release eligibility. Re-read them + # after rendering and before pushing or deploying retained output. + for release_tag, source_sha in release_sources.items(): + if remote_tag_commit(release_tag) != source_sha: + raise ValueError( + f"Release tag moved during publication: {release_tag}" + ) + if changed: # Scope credentials to this push. No credential is written # to repository files, command arguments, logs or rendered output. git( diff --git a/dev/src/cuphoton_dev/renderers.py b/dev/src/cuphoton_dev/renderers.py index e28e5b2e..ea723c04 100644 --- a/dev/src/cuphoton_dev/renderers.py +++ b/dev/src/cuphoton_dev/renderers.py @@ -34,6 +34,7 @@ def _version(executable: Path) -> str | None: [str(executable), "--version"], capture_output=True, text=True, + encoding="utf-8", timeout=30, ) except (OSError, subprocess.TimeoutExpired): diff --git a/dev/src/cuphoton_dev/transforms.py b/dev/src/cuphoton_dev/transforms.py index acdebb99..9f7cdff5 100644 --- a/dev/src/cuphoton_dev/transforms.py +++ b/dev/src/cuphoton_dev/transforms.py @@ -47,7 +47,9 @@ def validate_version(version: str) -> None: def _write_json(path: Path, value: Any) -> None: - path.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n") + path.write_text( + json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8" + ) def file_hashes(path: Path) -> dict[str, str]: @@ -182,7 +184,7 @@ def postprocess( converted = {"clone": 0, "install": 0, "reference": 0} for file in sorted(output.rglob("*.html")): relative = file.relative_to(output).as_posix() - soup = BeautifulSoup(file.read_text(), "html.parser") + soup = BeautifulSoup(file.read_text(encoding="utf-8"), "html.parser") if soup.head is None or soup.body is None: raise ValueError(f"Missing HTML head/body: {relative}") for node in soup.find_all(True): @@ -293,7 +295,7 @@ def postprocess( pages[relative] = sorted( {str(tag["id"]) for tag in soup.find_all(id=True)} ) - file.write_text(str(soup)) + file.write_text(str(soup), encoding="utf-8") if version != "main" and converted != { "clone": 1, "install": 1, @@ -302,11 +304,13 @@ def postprocess( raise ValueError(f"Release conversion contracts changed: {converted}") search_path = output / "search.json" search = _transform_json( - json.loads(search_path.read_text()), version, site_url + json.loads(search_path.read_text(encoding="utf-8")), version, site_url ) _write_json(search_path, search) if version != "main": - _assert_release_text(search_path.read_text(), "search.json") + _assert_release_text( + search_path.read_text(encoding="utf-8"), "search.json" + ) sitemap_path = output / "sitemap.xml" tree = ET.parse(sitemap_path) for location in tree.iter(): @@ -345,23 +349,37 @@ def _local_target( return None if not url.path.startswith(prefix): raise ValueError(f"Link escapes selected version: {value}") - return unquote(url.path[len(prefix) :]) or "index.html" - if url.path.startswith("/"): + target = unquote(url.path[len(prefix) :]) + elif url.path.startswith("/"): if not url.path.startswith(prefix): raise ValueError(f"Link escapes selected version: {value}") - return unquote(url.path[len(prefix) :]) or "index.html" - if not url.path: + target = unquote(url.path[len(prefix) :]) + elif not url.path: return relative - target = posixpath.normpath( - posixpath.join(posixpath.dirname(relative), unquote(url.path)) + else: + target = posixpath.join( + posixpath.dirname(relative), unquote(url.path) + ) + # Keep directory URL semantics before normpath removes the trailing slash. + directory = ( + not target + or target.endswith(("/", "/.", "/..")) + or target in {".", ".."} ) - return target + "index.html" if target.endswith("/") else target + target = posixpath.normpath(target) + if target == ".." or target.startswith(("../", "/")): + raise ValueError(f"Link escapes selected version: {value}") + if directory: + return posixpath.normpath(posixpath.join(target, "index.html")) + return target def check_snapshot(path: Path) -> dict[str, Any]: """Check receipt integrity and the browser-facing version boundary.""" path = Path(path) - receipt: dict[str, Any] = json.loads((path / RECEIPT).read_text()) + receipt: dict[str, Any] = json.loads( + (path / RECEIPT).read_text(encoding="utf-8") + ) if receipt.get("schema") != 1: raise ValueError("Unsupported documentation receipt schema") validate_version(receipt["version"]) @@ -374,7 +392,7 @@ def check_snapshot(path: Path) -> dict[str, Any]: if set(inventory) != {f for f in actual if f.endswith(".html")}: raise ValueError("Snapshot HTML inventory is incomplete") for relative, anchors in inventory.items(): - text = (path / relative).read_text() + text = (path / relative).read_text(encoding="utf-8") soup = BeautifulSoup(text, "html.parser") canonical = soup.select('link[rel="canonical"]') expected = receipt["site_url"] + receipt["version"] + "/" + relative @@ -411,7 +429,7 @@ def check_snapshot(path: Path) -> dict[str, Any]: raise ValueError( f"Missing local bookmark in {relative}: {value}" ) - search_text = (path / "search.json").read_text() + search_text = (path / "search.json").read_text(encoding="utf-8") if receipt["version"] != "main": _assert_release_text(search_text, "search.json") for record in json.loads(search_text): diff --git a/dev/tests/test_cli.py b/dev/tests/test_cli.py index d25bc6e0..44d4bb82 100644 --- a/dev/tests/test_cli.py +++ b/dev/tests/test_cli.py @@ -196,6 +196,140 @@ def publish(**kwargs: object) -> None: assert "https://example.org/run/123" in err.getvalue() +@pytest.mark.parametrize( + "conclusion", ["failure", "cancelled", "timed_out", None] +) +def test_tracked_publication_failure_keeps_json_and_nonzero_status( + monkeypatch: pytest.MonkeyPatch, conclusion: str | None +) -> None: + from cuphoton_dev import github + + request_id = "" + + def api(path: str, *, data=None, **kwargs): + nonlocal request_id + if data: + request_id = data["inputs"]["request_id"] + return {"workflow_run_id": 123} + assert path.endswith("/123") + return { + "status": "completed" if conclusion else "in_progress", + "conclusion": conclusion, + "head_sha": "a" * 40, + "html_url": "https://example.org/run/123", + } + + monkeypatch.setattr(github, "api", api) + if conclusion is None: + clock = iter([0, 7201]) + monkeypatch.setattr( + github.time, "monotonic", lambda: next(clock, 7201) + ) + out, err = io.StringIO(), io.StringIO() + assert ( + product_cli.main( + ["dev", "docs-publish", "--ref", "main", "--json"], + out=out, + err=err, + ) + == 1 + ) + result = json.loads(out.getvalue()) + assert result["request_id"] == request_id + assert result["run_id"] == 123 + assert result["url"] == "https://example.org/run/123" + assert result["controller_sha"] == "a" * 40 + assert result["conclusion"] == conclusion + assert result["status"] == ("completed" if conclusion else "in_progress") + assert result["error"] in err.getvalue() + assert result["url"] in result["error"] + + +def test_dispatch_discovery_timeout_reports_recovery_request_as_json( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from cuphoton_dev import github + + request_id = "" + + def api(path: str, *, data=None, **kwargs): + nonlocal request_id + if data: + request_id = data["inputs"]["request_id"] + return None + assert "workflow_dispatch" in path + return {"workflow_runs": []} + + clock = iter([0, 181]) + monkeypatch.setattr(github, "api", api) + monkeypatch.setattr(github.time, "monotonic", lambda: next(clock, 181)) + out, err = io.StringIO(), io.StringIO() + assert ( + product_cli.main( + ["dev", "docs-publish", "--ref", "main", "--json"], + out=out, + err=err, + ) + == 1 + ) + result = json.loads(out.getvalue()) + assert request_id and result["request_id"] == request_id + assert result["status"] == "dispatch_accepted" + assert result["run_id"] is None + assert result["url"] is None + assert request_id in result["error"] + assert result["error"] in err.getvalue() + + +@pytest.mark.parametrize("known_run", [False, True]) +def test_api_failure_after_dispatch_retains_last_known_json_state( + monkeypatch: pytest.MonkeyPatch, known_run: bool +) -> None: + from cuphoton_dev import github + + request_id = "" + polls = 0 + + def api(path: str, *, data=None, **kwargs): + nonlocal request_id, polls + if data: + request_id = data["inputs"]["request_id"] + return {"workflow_run_id": 123} if known_run else None + polls += 1 + if known_run and polls == 1: + return { + "status": "in_progress", + "conclusion": None, + "head_sha": "a" * 40, + "html_url": "https://example.org/run/123", + } + raise RuntimeError("temporary API outage") + + monkeypatch.setattr(github, "api", api) + monkeypatch.setattr(github.time, "sleep", lambda _: None) + out, err = io.StringIO(), io.StringIO() + assert ( + product_cli.main( + ["dev", "docs-publish", "--ref", "main", "--json"], + out=out, + err=err, + ) + == 1 + ) + result = json.loads(out.getvalue()) + assert request_id and result["request_id"] == request_id + assert result["status"] == ( + "in_progress" if known_run else "dispatch_accepted" + ) + assert result["run_id"] == (123 if known_run else None) + assert result["url"] == ( + "https://example.org/run/123" if known_run else None + ) + assert result["controller_sha"] == ("a" * 40 if known_run else None) + assert "temporary API outage" in result["error"] + assert result["error"] in err.getvalue() + + def test_module_entrypoint() -> None: result = subprocess.run( [sys.executable, "-m", "cuphoton_dev", "--help"], diff --git a/dev/tests/test_prepare.py b/dev/tests/test_prepare.py index 1fab3590..8e3b3e46 100644 --- a/dev/tests/test_prepare.py +++ b/dev/tests/test_prepare.py @@ -84,6 +84,11 @@ def build(*, ref, output, repo): monkeypatch.setattr(publisher, "docs_build", build) monkeypatch.setattr(publisher, "releases", lambda: [release()]) monkeypatch.setattr(publisher, "has_guide", lambda tag: True) + monkeypatch.setattr( + publisher, + "remote_tag_commit", + lambda tag: git(source, "rev-parse", f"refs/tags/{tag}^{{commit}}"), + ) return SimpleNamespace( source=source, remote=remote, @@ -188,3 +193,67 @@ def broken_push(repo, *args): git(publication.remote, "rev-parse", "gh-pages") == original["archive_sha"] ) + + +@pytest.mark.parametrize("annotated", [False, True]) +def test_remote_tag_commit_prefers_peeled_annotated_target( + tmp_path, monkeypatch, annotated +): + git(tmp_path, "init", "-q") + git(tmp_path, "config", "user.name", "Test") + git(tmp_path, "config", "user.email", "test@example.com") + git(tmp_path, "config", "commit.gpgsign", "false") + (tmp_path / "source.txt").write_text("release source\n") + git(tmp_path, "add", ".") + git(tmp_path, "commit", "-qm", "release source") + sha = git(tmp_path, "rev-parse", "HEAD") + if annotated: + git(tmp_path, "tag", "-a", "v0.2.0", "-m", "release") + assert git(tmp_path, "rev-parse", "v0.2.0") != sha + else: + git(tmp_path, "tag", "v0.2.0") + actual_run = publisher.run + calls = [] + + def local_remote(args): + calls.append(args) + assert args[3] == "https://github.com/NVIDIA/cuPhoton.git" + return actual_run([*args[:3], str(tmp_path), *args[4:]]) + + monkeypatch.setattr(publisher, "run", local_remote) + assert publisher.remote_tag_commit("v0.2.0") == sha + assert calls[0][-2:] == ["refs/tags/v0.2.0", "refs/tags/v0.2.0^{}"] + with pytest.raises(ValueError, match="missing from the remote"): + publisher.remote_tag_commit("v0.2.1") + + +@pytest.mark.parametrize("remote_change", ["moved", "missing"]) +def test_remote_tag_change_during_render_cannot_publish( + publication, monkeypatch, remote_change +): + initial = publisher.prepare(tag="main", output=publication.root / "first") + real_build = publisher.docs_build + remote_sha = publication.sha + + def build_then_change_tag(**kwargs): + nonlocal remote_sha + result = real_build(**kwargs) + remote_sha = "f" * 40 if remote_change == "moved" else None + return result + + def current_remote_tag(tag): + if remote_sha is None: + raise ValueError(f"Release tag is missing from the remote: {tag}") + return remote_sha + + monkeypatch.setattr(publisher, "docs_build", build_then_change_tag) + monkeypatch.setattr(publisher, "remote_tag_commit", current_remote_tag) + output = publication.root / "rejected-remote" + with pytest.raises(ValueError, match="moved|missing"): + publisher.prepare(tag="v0.2.0", output=output) + assert not output.exists() + assert ( + git(publication.remote, "rev-parse", "gh-pages") + == initial["archive_sha"] + ) + assert git(publication.source, "rev-parse", "v0.2.0") == publication.sha diff --git a/dev/tests/test_publisher.py b/dev/tests/test_publisher.py index 88dcfa32..dc1174dd 100644 --- a/dev/tests/test_publisher.py +++ b/dev/tests/test_publisher.py @@ -132,11 +132,15 @@ def test_failed_run_propagates_url(monkeypatch): }, ) with pytest.raises( - RuntimeError, match="failure: https://example.test/runs/123" - ): + github.PublicationError, + match="failure: https://example.test/runs/123", + ) as error: github.wait_for_run( github.REPOSITORY, 123, wait=True, request_id="test" ) + assert error.value.result["request_id"] == "test" + assert error.value.result["run_id"] == 123 + assert error.value.result["conclusion"] == "failure" def test_draft_cannot_dispatch(monkeypatch): diff --git a/dev/tests/test_transforms.py b/dev/tests/test_transforms.py index 49c2200c..71567a10 100644 --- a/dev/tests/test_transforms.py +++ b/dev/tests/test_transforms.py @@ -6,6 +6,8 @@ import json import os +import subprocess +import sys from pathlib import Path import pytest @@ -175,7 +177,7 @@ def test_checks_detect_tampering_and_external_asset_escape(tmp_path): .read_text() .replace("", '') ) - with pytest.raises(ValueError, match="Missing local target"): + with pytest.raises(ValueError, match="escapes selected version"): postprocess( path2, version="v0.2.0", @@ -256,3 +258,144 @@ def test_snapshot_rejects_missing_bookmarks(tmp_path, location): controller_sha="b", renderer="test", ) + + +def test_directory_links_resolve_index_pages_and_bookmarks(tmp_path): + path = rendered_guide(tmp_path / "render", extra_page=True) + (path / "nested/example.html").rename(path / "nested/index.html") + for name in ("sitemap.xml", "search.json"): + file = path / name + file.write_text( + file.read_text(encoding="utf-8").replace( + "nested/example.html", "nested/index.html" + ), + encoding="utf-8", + ) + root_links = ( + "./", + "nested/", + "nested/./", + "nested/../", + ".", + "/cuPhoton/nested/", + SITE_URL + "nested/", + ) + index = path / "index.html" + index.write_text( + index.read_text(encoding="utf-8").replace( + "", + "".join(f'
    Directory' for link in root_links) + + "", + ), + encoding="utf-8", + ) + nested = path / "nested/index.html" + nested.write_text( + nested.read_text(encoding="utf-8").replace( + "", + 'RootRoot dot segment' + 'Same directory bookmark', + ), + encoding="utf-8", + ) + search = path / "search.json" + records = json.loads(search.read_text(encoding="utf-8")) + records[-1]["href"] = "nested/?search=1#new-topic" + search.write_text(json.dumps(records), encoding="utf-8") + postprocess( + path, + version="v0.2.0", + source_sha="a", + controller_sha="b", + renderer="test", + ) + assert "nested/index.html" in check_snapshot(path)["pages"] + + +@pytest.mark.parametrize( + "href", + [ + "../", + "/cuPhoton/main/../", + SITE_URL + "main/../", + ], +) +def test_directory_links_cannot_escape_snapshot(tmp_path, href): + path = rendered_guide(tmp_path / "render") + index = path / "index.html" + index.write_text( + index.read_text(encoding="utf-8").replace( + "", f'Outside' + ), + encoding="utf-8", + ) + with pytest.raises(ValueError, match="escapes selected version"): + postprocess( + path, + version="main", + source_sha="a", + controller_sha="b", + renderer="test", + ) + + +def test_utf8_snapshot_and_archive_under_ascii_locale(tmp_path): + path = rendered_guide(tmp_path / "render", extra_page=True) + (path / "nested/example.html").rename(path / "nested/café.html") + for name in ("sitemap.xml", "search.json"): + file = path / name + file.write_text( + file.read_text(encoding="utf-8").replace( + "nested/example.html", "nested/café.html" + ), + encoding="utf-8", + ) + index = path / "index.html" + index.write_text( + index.read_text(encoding="utf-8").replace( + "", '

    μ and café

    ' + ), + encoding="utf-8", + ) + script = r""" +import locale +import sys +from pathlib import Path +from cuphoton_dev.archive import assemble, check_archive +from cuphoton_dev.transforms import postprocess, check_snapshot +assert not sys.flags.utf8_mode +locale.setlocale(locale.LC_CTYPE, "C") +assert locale.getencoding().lower() in {"ascii", "ansi_x3.4-1968"} +source, archive = map(Path, sys.argv[1:]) +postprocess(source, version="v0.2.0", source_sha="a", controller_sha="b", + renderer="test") +assert "caf\u00e9" in check_snapshot(source)["pages"]["index.html"] +text = (source / "index.html").read_text(encoding="utf-8") +assert "\u03bc and caf\u00e9" in text +assemble(archive, source, eligible_releases={"v0.2.0"}) +assemble(archive, source, eligible_releases={"v0.2.0"}) +assert check_archive(archive)["stable"] == "v0.2.0" +redirect = archive / "nested/caf\u00e9.html" +assert "nested/caf\u00e9.html" in redirect.read_text(encoding="utf-8") +""" + completed = subprocess.run( + [ + sys.executable, + "-X", + "utf8=0", + "-c", + script, + str(path), + str(tmp_path / "archive"), + ], + env={ + **os.environ, + # Keep UTF-8 filesystem paths, then switch text IO to ASCII above. + "LC_ALL": "C.UTF-8", + "PYTHONUTF8": "0", + "PYTHONCOERCECLOCALE": "0", + }, + capture_output=True, + text=True, + ) + assert completed.returncode == 0, completed.stderr From 180ca8a92483ee148105950a911485de8d7693fa Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Wed, 11 Nov 2026 21:42:59 -0800 Subject: [PATCH 4/9] Preserve documentation request IDs when dispatch is uncertain Retain the request UUID when workflow submission fails before receiving a confirmation. Report an unknown outcome so callers can locate a possibly accepted run before submitting another request. Signed-off-by: Trent Nelson --- dev/README.md | 2 ++ dev/src/cuphoton_dev/github.py | 28 +++++++++++++++++++------- dev/tests/test_cli.py | 36 ++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 7 deletions(-) diff --git a/dev/README.md b/dev/README.md index ec23f3e1..ead97d42 100644 --- a/dev/README.md +++ b/dev/README.md @@ -127,6 +127,8 @@ to return after dispatch. Failed runs and wait timeouts retain the known request and workflow fields in JSON output while returning a failing exit status. An accepted dispatch whose run is not yet discoverable reports its request ID with null run fields; use that ID before attempting a new dispatch. +If submission fails before confirmation, `dispatch_unknown` preserves the +request ID without claiming acceptance; inspect that request before retrying. ```sh uv run --project dev --locked cuphoton dev docs-publish --ref main --json diff --git a/dev/src/cuphoton_dev/github.py b/dev/src/cuphoton_dev/github.py index cd91023b..b3eda83f 100644 --- a/dev/src/cuphoton_dev/github.py +++ b/dev/src/cuphoton_dev/github.py @@ -202,13 +202,27 @@ def docs_publish( if not has_guide(tag, repository): raise ValueError(f"Documentation is unavailable at {tag}") request_id = uuid.uuid4().hex - response = api( - f"repos/{repository}/actions/workflows/docs.yml/dispatches", - data={ - "ref": "main", - "inputs": {"tag": tag, "request_id": request_id}, - }, - ) + try: + response = api( + f"repos/{repository}/actions/workflows/docs.yml/dispatches", + data={ + "ref": "main", + "inputs": {"tag": tag, "request_id": request_id}, + }, + ) + except (RuntimeError, OSError, ValueError) as exc: + raise PublicationError( + f"Dispatch outcome unknown for request {request_id}: {exc}. " + "Inspect that request before redispatching.", + { + "request_id": request_id, + "run_id": None, + "url": None, + "status": "dispatch_unknown", + "conclusion": None, + "controller_sha": None, + }, + ) from exc run_id = response.get("workflow_run_id") if response else None if run_id is None: # Older API deployments return 204. Correlate our unique request diff --git a/dev/tests/test_cli.py b/dev/tests/test_cli.py index 44d4bb82..457b3903 100644 --- a/dev/tests/test_cli.py +++ b/dev/tests/test_cli.py @@ -330,6 +330,42 @@ def api(path: str, *, data=None, **kwargs): assert result["error"] in err.getvalue() +def test_unconfirmed_dispatch_preserves_request_without_redispatch( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from cuphoton_dev import github + + submitted = [] + + def api(path: str, *, data=None, **kwargs): + assert path.endswith("/dispatches") and data is not None + submitted.append(data["inputs"]["request_id"]) + # The server may create the run before the client loses its response. + raise OSError("connection closed after request was sent") + + monkeypatch.setattr(github, "api", api) + out, err = io.StringIO(), io.StringIO() + assert ( + product_cli.main( + ["dev", "docs-publish", "--ref", "main", "--json"], + out=out, + err=err, + ) + == 1 + ) + result = json.loads(out.getvalue()) + assert len(submitted) == 1 + assert result["request_id"] == submitted[0] + assert result["status"] == "dispatch_unknown" + assert result["run_id"] is None + assert result["url"] is None + assert result["conclusion"] is None + assert result["controller_sha"] is None + assert submitted[0] in result["error"] + assert "Inspect that request before redispatching" in result["error"] + assert result["error"] in err.getvalue() + + def test_module_entrypoint() -> None: result = subprocess.run( [sys.executable, "-m", "cuphoton_dev", "--help"], From 3a88a7d195a67109069500c1bf4440c69274574c Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Thu, 12 Nov 2026 09:11:04 -0800 Subject: [PATCH 5/9] Isolate documentation builds and preserve publication routes Clear inherited Quarto settings before selecting and running the pinned renderer. Normalize qualified release refs, preserve committed-source isolation, and reject tracked mutations during rendering. Keep the root sitemap discoverable and distinguish rejected publication requests from uncertain submissions. Cancel superseded previews in a separate workflow and forward each final release only once. Signed-off-by: Trent Nelson --- .github/workflows/docs-preview.yml | 73 ++++++++++ .github/workflows/docs.yml | 54 +------- .github/workflows/release-docs.yml | 3 +- dev/README.md | 31 ++++- dev/src/cuphoton_dev/archive.py | 47 ++++++- dev/src/cuphoton_dev/build.py | 22 +-- dev/src/cuphoton_dev/cli.py | 5 +- dev/src/cuphoton_dev/github.py | 52 ++++++- dev/src/cuphoton_dev/renderers.py | 11 +- dev/src/cuphoton_dev/transforms.py | 4 +- dev/tests/test_archive.py | 58 +++++++- dev/tests/test_build.py | 211 +++++++++++++++++++++++++++++ dev/tests/test_ci_changes.py | 19 +++ dev/tests/test_cli.py | 52 +++++++ dev/tests/test_prepare.py | 51 +++++++ dev/tests/test_publisher.py | 21 +++ dev/tests/test_release_hook.py | 18 +++ dev/tests/test_renderers.py | 124 ++++++++++++----- dev/tests/test_transforms.py | 59 +++++++- src/cuphoton/core/cli/component.py | 3 +- 20 files changed, 796 insertions(+), 122 deletions(-) create mode 100644 .github/workflows/docs-preview.yml create mode 100644 dev/tests/test_build.py diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml new file mode 100644 index 00000000..8a31340c --- /dev/null +++ b/.github/workflows/docs-preview.yml @@ -0,0 +1,73 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +name: user guide preview +run-name: docs preview PR ${{ github.event.number }} / ${{ github.sha }} + +on: + pull_request: + branches: [main] + paths: + - .github/workflows/docs-preview.yml + - .github/workflows/docs.yml + - .github/workflows/release-docs.yml + - dev/** + - docs/** + - src/** + - examples/** + - pyproject.toml + - uv.lock + - setup.py + +permissions: + contents: read + +# Superseded PR previews can stop without affecting publication or its queue. +concurrency: + group: docs-preview-${{ github.event.number }} + cancel-in-progress: true + +env: + CUPHOTON_XDR_BUILD_EXT: "0" + CUPHOTON_XREP_TORCH_DEVICE: cpu + CUDA_VISIBLE_DEVICES: "" + MPLBACKEND: Agg + UV_HTTP_TIMEOUT: "300" + +jobs: + preview: + name: preview user guide + runs-on: ubuntu-24.04 + timeout-minutes: 30 + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + persist-credentials: false + fetch-depth: 0 + - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6 + with: + version: "0.12.1" + enable-cache: true + - name: Install developer tools + run: uv sync --project dev --locked --python 3.12 + - name: Install Quarto + run: | + curl --fail --location --retry 3 --output "$RUNNER_TEMP/quarto.deb" \ + https://github.com/quarto-dev/quarto-cli/releases/download/v1.9.36/quarto-1.9.36-linux-amd64.deb + printf '%s %s\n' \ + 8c47762e78fe58642246a94d18f67eb332c1778b711e5bef991ef3c15490d83a \ + "$RUNNER_TEMP/quarto.deb" | sha256sum --check + sudo dpkg --install "$RUNNER_TEMP/quarto.deb" + - name: Render exact PR source in isolation + run: >- + uv run --project dev --locked cuphoton dev docs-build + --ref "$GITHUB_SHA" --repo . --output "$RUNNER_TEMP/preview" + - name: Check the rendered preview + run: uv run --project dev --locked cuphoton dev docs-check "$RUNNER_TEMP/preview" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: docs-preview-${{ github.sha }} + path: ${{ runner.temp }}/preview + if-no-files-found: error + retention-days: 14 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index bba32885..9398591b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -18,18 +18,6 @@ on: - pyproject.toml - uv.lock - setup.py - pull_request: - branches: [main] - paths: - - .github/workflows/docs.yml - - .github/workflows/release-docs.yml - - dev/** - - docs/** - - src/** - - examples/** - - pyproject.toml - - uv.lock - - setup.py workflow_dispatch: inputs: # Existing release tags retain their hook. Preserve this name and type. @@ -48,7 +36,7 @@ permissions: # Keep the lock from archive read through deployment. Queue every publication; # a newer main run must not cancel a pending release or an active deployment. concurrency: - group: ${{ github.event_name == 'pull_request' && format('docs-preview-{0}', github.event.number) || 'cuphoton-docs-publication' }} + group: cuphoton-docs-publication queue: max cancel-in-progress: false @@ -60,49 +48,11 @@ env: UV_HTTP_TIMEOUT: "300" jobs: - preview: - name: preview user guide - if: github.event_name == 'pull_request' - runs-on: ubuntu-24.04 - timeout-minutes: 30 - steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 - with: - persist-credentials: false - fetch-depth: 0 - - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6 - with: - version: "0.12.1" - enable-cache: true - - name: Install developer tools - run: uv sync --project dev --locked --python 3.12 - - name: Install Quarto - run: | - curl --fail --location --retry 3 --output "$RUNNER_TEMP/quarto.deb" \ - https://github.com/quarto-dev/quarto-cli/releases/download/v1.9.36/quarto-1.9.36-linux-amd64.deb - printf '%s %s\n' \ - 8c47762e78fe58642246a94d18f67eb332c1778b711e5bef991ef3c15490d83a \ - "$RUNNER_TEMP/quarto.deb" | sha256sum --check - sudo dpkg --install "$RUNNER_TEMP/quarto.deb" - - name: Render exact PR source in isolation - run: >- - uv run --project dev --locked cuphoton dev docs-build - --ref "$GITHUB_SHA" --repo . --output "$RUNNER_TEMP/preview" - - name: Check the rendered preview - run: uv run --project dev --locked cuphoton dev docs-check "$RUNNER_TEMP/preview" - - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 - with: - name: docs-preview-${{ github.sha }} - path: ${{ runner.temp }}/preview - if-no-files-found: error - retention-days: 14 - publish: name: publish user guide if: >- github.repository == 'NVIDIA/cuPhoton' && - github.ref == 'refs/heads/main' && - github.event_name != 'pull_request' + github.ref == 'refs/heads/main' runs-on: ubuntu-24.04 timeout-minutes: 90 permissions: diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml index eadbb812..dc740df0 100644 --- a/.github/workflows/release-docs.yml +++ b/.github/workflows/release-docs.yml @@ -8,7 +8,8 @@ name: release documentation on: release: - types: [published, released] + # Covers initial final publication and promotion from prerelease. + types: [released] permissions: actions: write diff --git a/dev/README.md b/dev/README.md index ead97d42..ef8ea3a1 100644 --- a/dev/README.md +++ b/dev/README.md @@ -76,8 +76,14 @@ isolated source checkout and uses the target's locked Python dependencies. CPU examples execute from that checkout. The output includes build provenance and hashes; authored source remains unchanged. +Use `--ref HEAD` to preview the committed changes on your current branch. +Any ref other than a final release tag renders under the `main` label. +Uncommitted changes are excluded. Final tags accept the bare `vX.Y.Z` spelling +and the equivalent `tags/vX.Y.Z` and `refs/tags/vX.Y.Z` forms. + ```sh uv run --project dev --locked cuphoton dev docs-build --ref main --output /tmp/cuphoton-main +uv run --project dev --locked cuphoton dev docs-build --ref HEAD --output /tmp/cuphoton-preview uv run --project dev --locked cuphoton dev docs-build --ref v0.2.0 --output /tmp/cuphoton-v0.2.0 uv run --project dev --locked cuphoton dev docs-check /tmp/cuphoton-v0.2.0 --json uv run --project dev --locked cuphoton dev docs-status --json @@ -129,6 +135,21 @@ status. An accepted dispatch whose run is not yet discoverable reports its request ID with null run fields; use that ID before attempting a new dispatch. If submission fails before confirmation, `dispatch_unknown` preserves the request ID without claiming acceptance; inspect that request before retrying. +Definite HTTP client errors report `dispatch_rejected`; correct the reported +error before retrying. Timeouts, rate limits and server or transport failures +retain the unknown outcome. + +For an accepted or uncertain dispatch, replace `REQUEST_ID` with its returned +identifier to find the run: + +```sh +gh run list --repo NVIDIA/cuPhoton --workflow docs.yml --event workflow_dispatch \ + --limit 100 --json databaseId,displayTitle,url \ + --jq '.[] | select(.displayTitle | contains("REQUEST_ID"))' +``` + +If the run is older than those results, increase `--limit`. An absent match +does not confirm rejection; allow time for an accepted run to appear. ```sh uv run --project dev --locked cuphoton dev docs-publish --ref main --json @@ -150,6 +171,10 @@ after retaining the assembled site, retry the workflow or repeat the same CLI command. Matching release snapshots are reused, so duplicate requests are safe. Use `--missing` for deliberate reconciliation of eligible missing releases. +PR builds run in `docs-preview.yml` with read-only permissions and cancel +superseded previews. `docs.yml` queues every publication without cancellation +and holds the publication lock through Pages deployment. + If validation rejects a retained snapshot or tag identity, inspect the failing run and provenance before retrying. Do not repair this by moving a release tag, copying current-main chapters, or editing generated catalog entries. A change @@ -169,9 +194,9 @@ Before cutting a release, verify that its branch contains For the existing `0.2.x` branch, add only this hook before its next tag; no developer package or documentation-content backport is needed. -The hook responds to `published` and `released`, including promotion of a -prerelease to a final Release. It accepts only the canonical repository and a -published final semantic-version tag, then dispatches `docs.yml` with +The hook responds to `released`, which covers initial final publication and +promotion of a prerelease to a final Release. It accepts only the canonical +repository and a published final semantic-version tag, then dispatches `docs.yml` with `ref: main` and the string `tag` input. The receiving publisher independently checks eligibility and the exact tag. Keep that workflow filename and input compatible with hooks already stored in historical tags. diff --git a/dev/src/cuphoton_dev/archive.py b/dev/src/cuphoton_dev/archive.py index cf3effe1..b21fd759 100644 --- a/dev/src/cuphoton_dev/archive.py +++ b/dev/src/cuphoton_dev/archive.py @@ -14,8 +14,9 @@ from collections.abc import Callable from pathlib import Path, PurePosixPath from typing import Any +from xml.etree import ElementTree as ET -from cuphoton_dev.transforms import RELEASE, check_snapshot +from cuphoton_dev.transforms import RELEASE, SITEMAP_NAMESPACE, check_snapshot def _json(path: Path, value: Any) -> None: @@ -132,7 +133,7 @@ def _catalog( } -def _generate(archive: Path, catalog: dict[str, Any]) -> None: +def _generate(archive: Path, catalog: dict[str, Any], site_url: str) -> None: _json(archive / "versions.json", catalog) for alias, target in catalog["aliases"].items(): file = archive / alias @@ -155,6 +156,17 @@ def _generate(archive: Path, catalog: dict[str, Any]) -> None: encoding="utf-8", ) (archive / ".nojekyll").touch() + # Keep the former root sitemap discoverable after the versioned cutover. + index = ET.Element(f"{{{SITEMAP_NAMESPACE}}}sitemapindex") + for entry in catalog["versions"]: + sitemap = ET.SubElement(index, f"{{{SITEMAP_NAMESPACE}}}sitemap") + location = ET.SubElement(sitemap, f"{{{SITEMAP_NAMESPACE}}}loc") + location.text = site_url + entry["path"] + "sitemap.xml" + ET.register_namespace("", SITEMAP_NAMESPACE) + ET.indent(index) + ET.ElementTree(index).write( + archive / "sitemap.xml", encoding="utf-8", xml_declaration=True + ) def assemble( @@ -224,7 +236,7 @@ def assemble( shutil.copytree(snapshot, destination) retained = _snapshots(staged) catalog = _catalog(retained, eligible_releases, legacy_pages) - _generate(staged, catalog) + _generate(staged, catalog, incoming["site_url"]) check_archive(staged) # All validation has completed before the first mutation. Preserve Git # metadata and copy ordinary files, which native Pages accepts. @@ -233,7 +245,7 @@ def assemble( if destination.exists(): shutil.rmtree(destination) shutil.copytree(staged / version, destination) - _generate(archive, catalog) + _generate(archive, catalog, incoming["site_url"]) return catalog @@ -259,6 +271,33 @@ def check_archive(path: Path) -> dict[str, Any]: expected = _catalog(receipts, eligible, set(catalog["legacy_pages"])) if catalog != expected: raise ValueError("Catalog does not match retained snapshots") + try: + index = ET.parse(path / "sitemap.xml").getroot() + except (FileNotFoundError, ET.ParseError) as exc: + raise ValueError( + "Archive sitemap index is missing or malformed" + ) from exc + if index.tag != f"{{{SITEMAP_NAMESPACE}}}sitemapindex" or any( + entry.tag != f"{{{SITEMAP_NAMESPACE}}}sitemap" for entry in index + ): + raise ValueError("Archive sitemap index has an invalid namespace") + locations = [] + for sitemap_entry in index: + location = sitemap_entry.findall(f"{{{SITEMAP_NAMESPACE}}}loc") + if len(location) != 1: + raise ValueError("Archive sitemap entry needs one location") + locations.append(location[0].text) + expected_locations = { + receipt["site_url"] + version + "/sitemap.xml" + for version, receipt in receipts.items() + } + if ( + len(locations) != len(expected_locations) + or set(locations) != expected_locations + ): + raise ValueError( + "Archive sitemap index differs from retained snapshots" + ) for alias, target in catalog["aliases"].items(): redirect = path / alias if not redirect.is_file() or redirect.read_text( diff --git a/dev/src/cuphoton_dev/build.py b/dev/src/cuphoton_dev/build.py index e321444a..46434a7e 100644 --- a/dev/src/cuphoton_dev/build.py +++ b/dev/src/cuphoton_dev/build.py @@ -17,7 +17,9 @@ from cuphoton_dev.renderers import renderer_for -FINAL_TAG = re.compile(r"v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\Z") +FINAL_TAG = re.compile( + r"v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\Z" +) def run( @@ -72,7 +74,7 @@ def resolve(repo: Path, ref: str) -> str: def render_environment(checkout: Path) -> dict[str, str]: - """Do not inherit the controller's Python or uv project selection.""" + """Isolate Python, uv and Quarto from the controller's configuration.""" env = dict(os.environ) for key in ( "PYTHONPATH", @@ -82,7 +84,6 @@ def render_environment(checkout: Path) -> dict[str, str]: "UV_PROJECT_ENVIRONMENT", "UV_PROJECT", "UV_WORKING_DIR", - "QUARTO_PROFILE", "JUPYTER_PATH", "JUPYTER_CONFIG_DIR", "JUPYTER_DATA_DIR", @@ -93,7 +94,7 @@ def render_environment(checkout: Path) -> dict[str, str]: ): env.pop(key, None) for key in tuple(env): - if key.startswith("SETUPTOOLS_SCM_"): + if key.startswith(("SETUPTOOLS_SCM_", "QUARTO_")): env.pop(key) env.update( UV_PROJECT_ENVIRONMENT=str(checkout / ".venv"), @@ -126,7 +127,12 @@ def docs_build( if output.exists(): raise ValueError(f"Output already exists: {output}") source_sha = resolve(repo, ref) - version = ref if FINAL_TAG.fullmatch(ref) else "main" + tag = ( + ref.removeprefix("refs/tags/") + if ref.startswith("refs/tags/") + else ref.removeprefix("tags/") + ) + version = tag if FINAL_TAG.fullmatch(tag) else "main" controller_repo = Path(__file__).resolve().parents[3] controller_sha = resolve(controller_repo, "HEAD") output.parent.mkdir(parents=True, exist_ok=True) @@ -152,14 +158,14 @@ def docs_build( workflow = (checkout / ".github/workflows/docs.yml").read_text( encoding="utf-8" ) - pin = re.search(r"releases/download/v([\d.]+)/quarto", workflow) + pin = re.search(r"releases/download/v([0-9.]+)/quarto", workflow) if not pin: raise ValueError( "Target has no recognized pinned Quarto renderer" ) renderer = pin[1] - quarto = renderer_for(renderer, Path(temporary)) env = render_environment(checkout) + quarto = renderer_for(renderer, Path(temporary), env=env) # Allow a site-specific environment provisioning wrapper. uv = os.environ.get("CUPHOTON_DOCS_UV", "uv") run( @@ -207,7 +213,7 @@ def docs_build( env=env, capture=False, ) - git(checkout, "diff", "--exit-code") + git(checkout, "diff", "--exit-code", "HEAD") rendered = guide / "_book" receipt = postprocess( rendered, diff --git a/dev/src/cuphoton_dev/cli.py b/dev/src/cuphoton_dev/cli.py index 0c2a7f3a..fbc709be 100644 --- a/dev/src/cuphoton_dev/cli.py +++ b/dev/src/cuphoton_dev/cli.py @@ -60,7 +60,10 @@ class DocsBuildCommand(_DocsCommand): class RefArg(StringInvariant): _arg = "--ref" _required = True - _help = "Main revision or full release tag to render." + _help = ( + "Committed Git ref to render. Final tags use their release " + "label; other refs, including HEAD, render as main." + ) class OutputDirArg(PathValueInvariant): _arg = "--output" diff --git a/dev/src/cuphoton_dev/github.py b/dev/src/cuphoton_dev/github.py index b3eda83f..ec670cab 100644 --- a/dev/src/cuphoton_dev/github.py +++ b/dev/src/cuphoton_dev/github.py @@ -6,6 +6,7 @@ from __future__ import annotations import json +import re import subprocess import time import uuid @@ -28,10 +29,25 @@ def __init__(self, message: str, result: dict[str, Any]) -> None: self.result = {**result, "error": message} +class GitHubRequestError(RuntimeError): + """Failed GitHub request, retaining an HTTP status when one arrived.""" + + def __init__(self, message: str, status_code: int | None) -> None: + super().__init__(message) + self.status_code = status_code + + def api( path: str, *, data: dict[str, Any] | None = None, missing_ok: bool = False ) -> Any: - args = ["gh", "api", "-H", "X-GitHub-Api-Version: 2026-03-10", path] + args = [ + "gh", + "api", + "--include", + "-H", + "X-GitHub-Api-Version: 2026-03-10", + path, + ] if data is not None: args.extend(["--method", "POST", "--input", "-"]) result = subprocess.run( @@ -41,11 +57,19 @@ def api( encoding="utf-8", capture_output=True, ) + # --include exposes the response status independently of gh's error prose. + response = result.stdout + status = re.match(r"HTTP/\S+ ([0-9]{3})[^\n]*\n", response) + status_code = int(status[1]) if status else None + if status: + _, _, response = response.partition("\n\n") if result.returncode: - if missing_ok and "HTTP 404" in result.stderr: + if missing_ok and status_code == 404: return None - raise RuntimeError(f"GitHub request failed: {result.stderr.strip()}") - return json.loads(result.stdout) if result.stdout.strip() else None + raise GitHubRequestError( + f"GitHub request failed: {result.stderr.strip()}", status_code + ) + return json.loads(response) if response.strip() else None def releases(repository: str = REPOSITORY) -> list[dict[str, Any]]: @@ -211,14 +235,28 @@ def docs_publish( }, ) except (RuntimeError, OSError, ValueError) as exc: + rejected = ( + isinstance(exc, GitHubRequestError) + and exc.status_code is not None + and 400 <= exc.status_code < 500 + and exc.status_code not in {408, 429} + ) + message = ( + f"GitHub rejected dispatch request {request_id}: {exc}. " + "Correct the reported error before retrying." + if rejected + else f"Dispatch outcome unknown for request {request_id}: {exc}. " + "Inspect that request before redispatching." + ) raise PublicationError( - f"Dispatch outcome unknown for request {request_id}: {exc}. " - "Inspect that request before redispatching.", + message, { "request_id": request_id, "run_id": None, "url": None, - "status": "dispatch_unknown", + "status": "dispatch_rejected" + if rejected + else "dispatch_unknown", "conclusion": None, "controller_sha": None, }, diff --git a/dev/src/cuphoton_dev/renderers.py b/dev/src/cuphoton_dev/renderers.py index ea723c04..425d6467 100644 --- a/dev/src/cuphoton_dev/renderers.py +++ b/dev/src/cuphoton_dev/renderers.py @@ -28,13 +28,14 @@ } -def _version(executable: Path) -> str | None: +def _version(executable: Path, *, env: dict[str, str]) -> str | None: try: result = subprocess.run( [str(executable), "--version"], capture_output=True, text=True, encoding="utf-8", + env=env, timeout=30, ) except (OSError, subprocess.TimeoutExpired): @@ -42,7 +43,7 @@ def _version(executable: Path) -> str | None: return result.stdout.strip() if result.returncode == 0 else None -def renderer_for(version: str, scratch: Path) -> Path: +def renderer_for(version: str, scratch: Path, *, env: dict[str, str]) -> Path: """Reuse a matching renderer or extract a verified one beneath scratch. The caller owns scratch and its lifetime. No global installation or @@ -53,8 +54,8 @@ def renderer_for(version: str, scratch: Path) -> Path: f"Unsupported Quarto {version}; add its verified release hashes " "to the main controller's renderer table" ) - installed = shutil.which("quarto") - if installed and _version(Path(installed)) == version: + installed = shutil.which("quarto", path=env.get("PATH", "")) + if installed and _version(Path(installed), env=env) == version: return Path(installed).resolve() machine = platform.machine().lower() architecture = { @@ -85,7 +86,7 @@ def renderer_for(version: str, scratch: Path) -> Path: with tarfile.open(archive, "r:gz") as package: package.extractall(destination, filter="data") executable = destination / f"quarto-{version}" / "bin/quarto" - if _version(executable) != version: + if _version(executable, env=env) != version: raise ValueError( f"Extracted Quarto does not report version {version}" ) diff --git a/dev/src/cuphoton_dev/transforms.py b/dev/src/cuphoton_dev/transforms.py index 9f7cdff5..0c9f5fb4 100644 --- a/dev/src/cuphoton_dev/transforms.py +++ b/dev/src/cuphoton_dev/transforms.py @@ -19,8 +19,9 @@ from bs4 import BeautifulSoup, NavigableString SITE_URL = "https://nvidia.github.io/cuPhoton/" -RELEASE = re.compile(r"v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\Z") +RELEASE = re.compile(r"v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\Z") RECEIPT = "build.json" +SITEMAP_NAMESPACE = "http://www.sitemaps.org/schemas/sitemap/0.9" _INSTALL = ( "This clones the development branch, which this guide describes. " "To use a published version instead, pick its tag from Releases, " @@ -316,6 +317,7 @@ def postprocess( for location in tree.iter(): if location.tag.rsplit("}", 1)[-1] == "loc" and location.text: location.text = _owned_url(location.text, version, site_url) + ET.register_namespace("", SITEMAP_NAMESPACE) tree.write(sitemap_path, encoding="utf-8", xml_declaration=True) asset_dir = output / "_version" asset_dir.mkdir(exist_ok=True) diff --git a/dev/tests/test_archive.py b/dev/tests/test_archive.py index 08318a56..0e563302 100644 --- a/dev/tests/test_archive.py +++ b/dev/tests/test_archive.py @@ -3,11 +3,12 @@ # SPDX-License-Identifier: Apache-2.0 import json +from xml.etree import ElementTree as ET import pytest from cuphoton_dev.archive import assemble, check_archive, redirect_html -from cuphoton_dev.transforms import file_hashes +from cuphoton_dev.transforms import SITE_URL, SITEMAP_NAMESPACE, file_hashes from .test_transforms import snapshot @@ -126,3 +127,58 @@ def test_removed_main_chapter_keeps_legacy_redirect(tmp_path): ) assert catalog["aliases"]["nested/example.html"] == "../main/index.html" assert check_archive(archive) == catalog + + +def test_root_sitemap_retains_snapshots_when_release_loses_eligibility( + tmp_path, +): + archive = tmp_path / "site" + main = snapshot(tmp_path / "main") + release = snapshot(tmp_path / "release", "v0.2.0") + assemble(archive, main, eligible_releases=set()) + namespace = {"s": SITEMAP_NAMESPACE} + index = ET.parse(archive / "sitemap.xml").getroot() + assert index.tag == f"{{{SITEMAP_NAMESPACE}}}sitemapindex" + assert [ + loc.text for loc in index.findall("s:sitemap/s:loc", namespace) + ] == [SITE_URL + "main/sitemap.xml"] + assemble(archive, release, eligible_releases={"v0.2.0"}) + release_hashes = file_hashes(archive / "v0.2.0") + catalog = assemble(archive, main, eligible_releases=set()) + assert catalog["stable"] is None + assert catalog["preferred"] == "main" + index = ET.parse(archive / "sitemap.xml").getroot() + assert { + loc.text for loc in index.findall("s:sitemap/s:loc", namespace) + } == { + SITE_URL + "main/sitemap.xml", + SITE_URL + "v0.2.0/sitemap.xml", + } + assert file_hashes(archive / "v0.2.0") == release_hashes + assert check_archive(archive) == catalog + + +@pytest.mark.parametrize( + "corruption", ["missing", "namespace", "target", "entry", "duplicate"] +) +def test_archive_rejects_invalid_root_sitemap(tmp_path, corruption): + archive = tmp_path / "site" + main = snapshot(tmp_path / "main") + assemble(archive, main, eligible_releases=set()) + sitemap = archive / "sitemap.xml" + if corruption == "missing": + sitemap.unlink() + else: + tree = ET.parse(sitemap) + index = tree.getroot() + if corruption == "namespace": + index.tag = "{https://example.invalid/namespace}sitemapindex" + elif corruption == "target": + index[0][0].text = SITE_URL + "v0.0.1/sitemap.xml" + elif corruption == "entry": + index.remove(index[0]) + else: + index.append(index[0]) + tree.write(sitemap, encoding="utf-8", xml_declaration=True) + with pytest.raises(ValueError, match="sitemap"): + check_archive(archive) diff --git a/dev/tests/test_build.py b/dev/tests/test_build.py new file mode 100644 index 00000000..51272d99 --- /dev/null +++ b/dev/tests/test_build.py @@ -0,0 +1,211 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Exercise source and renderer isolation through real external processes.""" + +from __future__ import annotations + +import hashlib +import os +import subprocess +import sys +from types import SimpleNamespace + +import pytest + +from cuphoton_dev import build, renderers +from cuphoton_dev.transforms import check_snapshot + +from .test_transforms import rendered_guide + +# One fake executable implements uv, its provisioned Python, and Quarto. Git +# cloning, checkout, mutation detection and HTML postprocessing remain real. +TOOL = r""" +import os +import shutil +import subprocess +import sys +from pathlib import Path + +checkout = Path(os.environ["CUPHOTON_REPO"]) +source = Path(os.environ["BUILD_TEST_SOURCE"]) +assert checkout != source +quarto_keys = {key for key in os.environ if key.startswith("QUARTO_")} +assert quarto_keys == {"QUARTO_PYTHON"} +assert os.environ["QUARTO_PYTHON"] == str(checkout / ".venv/bin/python") +assert "PYTHONPATH" not in os.environ +assert "GITHUB_TOKEN" not in os.environ +assert os.environ["UV_PROJECT_ENVIRONMENT"] == str(checkout / ".venv") +mode = Path(sys.argv[0]).name +with Path(os.environ["BUILD_TEST_LOG"]).open("a", encoding="utf-8") as log: + log.write(mode + " " + " ".join(sys.argv[1:]) + "\n") + +if mode == "quarto" and sys.argv[1:] == ["--version"]: + print("1.9.36") + sys.exit(0) +assert Path.cwd() == checkout +lock = (checkout / "uv.lock").read_text(encoding="utf-8") +assert lock == "committed lock\n" +text = (checkout / "source.txt").read_text(encoding="utf-8") +assert text == "committed source\n" +if mode == "uv": + assert "--locked" in sys.argv, "render environment must honor target lock" + assert not (checkout / ".venv").exists() + assert not (checkout / "docs/guide/_book").exists() + assert not (checkout / ".git/objects/info/alternates").exists() + def object_inodes(repo): + return {(p.stat().st_dev, p.stat().st_ino) + for p in (repo / ".git/objects").rglob("*") if p.is_file()} + shared = object_inodes(checkout) & object_inodes(source) + assert not shared, "shared Git objects" + python = checkout / ".venv/bin/python" + python.parent.mkdir(parents=True) + shutil.copyfile(__file__, python) + python.chmod(0o755) +elif mode == "python": + assert sys.argv[1:5] == ["-m", "ipykernel", "install", "--prefix"] + assert sys.argv[5] == str(checkout / ".venv") + (checkout / ".venv/kernel-installed").touch() +elif mode == "quarto": + assert (checkout / ".venv/kernel-installed").exists() + assert "--execute" in sys.argv and "--no-cache" in sys.argv + shutil.copytree( + checkout / "render-fixture", checkout / "docs/guide/_book" + ) + mutation = os.environ.get("BUILD_TEST_MUTATION") + if mutation: + (checkout / "source.txt").write_text( + "render mutation\n", encoding="utf-8" + ) + if mutation == "staged": + subprocess.run(["git", "add", "source.txt"], check=True) +else: + raise AssertionError(mode) +""" + + +def git(path, *args): + return subprocess.check_output( + ["git", "-C", str(path), *args], + text=True, + encoding="utf-8", + stderr=subprocess.PIPE, + ).strip() + + +@pytest.fixture +def build_source(tmp_path, monkeypatch): + monkeypatch.setattr( + renderers, "urlopen", lambda *a, **k: pytest.fail("must not download") + ) + source = tmp_path / "source" + guide = source / "docs/guide" + guide.mkdir(parents=True) + (guide / "_quarto.yml").write_text( + "project:\n type: book\n", encoding="utf-8" + ) + workflow = source / ".github/workflows/docs.yml" + workflow.parent.mkdir(parents=True) + workflow.write_text( + "# https://github.com/quarto-dev/quarto-cli/releases/download/" + "v1.9.36/quarto-1.9.36-linux-amd64.tar.gz\n", + encoding="utf-8", + ) + (source / "uv.lock").write_text("committed lock\n", encoding="utf-8") + (source / "source.txt").write_text("committed source\n", encoding="utf-8") + (source / ".gitignore").write_text(".venv/\n_book/\n", encoding="utf-8") + rendered_guide(source / "render-fixture") + git(source, "init", "-q", "--initial-branch=main") + git(source, "config", "user.name", "Test") + git(source, "config", "user.email", "test@example.com") + git(source, "config", "commit.gpgsign", "false") + git(source, "add", ".") + git(source, "commit", "-qm", "committed guide") + git(source, "tag", "v0.2.0") + (source / "later.txt").write_text( + "development commit\n", encoding="utf-8" + ) + git(source, "add", ".") + git(source, "commit", "-qm", "development change") + # None of this controller state may enter the rendered snapshot. + (source / "uv.lock").write_text( + "dirty controller lock\n", encoding="utf-8" + ) + (source / "source.txt").write_text( + "dirty controller source\n", encoding="utf-8" + ) + (source / ".venv").mkdir() + (guide / "_book").mkdir() + + tools = tmp_path / "tools" + tools.mkdir() + for name in ("uv", "quarto"): + executable = tools / name + executable.write_text(f"#!{sys.executable}\n{TOOL}", encoding="utf-8") + executable.chmod(0o755) + monkeypatch.setenv("PATH", str(tools) + os.pathsep + os.environ["PATH"]) + monkeypatch.setenv("CUPHOTON_DOCS_UV", str(tools / "uv")) + monkeypatch.setenv("BUILD_TEST_SOURCE", str(source)) + log = tmp_path / "tools.log" + monkeypatch.setenv("BUILD_TEST_LOG", str(log)) + for name in ( + "QUARTO_FORCE_VERSION", + "QUARTO_BIN_PATH", + "QUARTO_SHARE_PATH", + "QUARTO_PROFILE", + "QUARTO_PYTHON", + "PYTHONPATH", + "GITHUB_TOKEN", + ): + monkeypatch.setenv(name, "controller-only") + return SimpleNamespace(source=source, log=log, output=tmp_path / "output") + + +@pytest.mark.parametrize( + "ref", ["v0.2.0", "tags/v0.2.0", "refs/tags/v0.2.0", "HEAD"] +) +def test_build_uses_committed_source_and_isolated_locked_environment( + build_source, ref +): + fixture = build_source + before = git(fixture.source, "status", "--porcelain") + result = build.docs_build( + ref=ref, output=fixture.output, repo=fixture.source + ) + expected_version = "main" if ref == "HEAD" else "v0.2.0" + assert result["version"] == expected_version + assert result["source_sha"] == git(fixture.source, "rev-parse", ref) + assert ( + result["lock_sha256"] + == hashlib.sha256(b"committed lock\n").hexdigest() + ) + assert check_snapshot(fixture.output)["version"] == expected_version + assert f"/cuPhoton/{expected_version}/index.html" in ( + fixture.output / "index.html" + ).read_text(encoding="utf-8") + assert git(fixture.source, "status", "--porcelain") == before + assert (fixture.source / "source.txt").read_text( + encoding="utf-8" + ) == "dirty controller source\n" + + +@pytest.mark.parametrize("mutation", ["unstaged", "staged"]) +def test_build_rejects_tracked_render_mutations( + build_source, monkeypatch, mutation +): + fixture = build_source + monkeypatch.setenv("BUILD_TEST_MUTATION", mutation) + with pytest.raises(RuntimeError, match="git failed"): + build.docs_build( + ref="v0.2.0", output=fixture.output, repo=fixture.source + ) + assert not fixture.output.exists() + assert (fixture.source / "source.txt").read_text( + encoding="utf-8" + ) == "dirty controller source\n" + assert ( + fixture.log.read_text(encoding="utf-8") + .splitlines()[-1] + .startswith("quarto render") + ) diff --git a/dev/tests/test_ci_changes.py b/dev/tests/test_ci_changes.py index ce4cf3bc..1b21844d 100644 --- a/dev/tests/test_ci_changes.py +++ b/dev/tests/test_ci_changes.py @@ -10,6 +10,7 @@ from pathlib import Path import pytest +import yaml SCRIPT = Path(__file__).resolve().parents[2] / "scripts/ci/dev_changes.py" SPEC = importlib.util.spec_from_file_location("dev_changes", SCRIPT) @@ -31,6 +32,7 @@ "tests/conftest.py", "docs/guide/install.qmd", ".github/workflows/release-docs.yml", + ".github/workflows/docs-preview.yml", "new-unknown-build-file", ], ) @@ -121,3 +123,20 @@ def git(*args): assert changes.changed_paths(head, git("rev-parse", "HEAD"), False) == [ "moved.py" ] + + +def test_preview_cancellation_is_separate_from_publication_lock(): + workflows = SCRIPT.parents[2] / ".github/workflows" + preview = yaml.safe_load((workflows / "docs-preview.yml").read_text()) + publication = yaml.safe_load((workflows / "docs.yml").read_text()) + # PyYAML interprets the Actions `on` key as YAML 1.1's boolean true. + assert set(preview[True]) == {"pull_request"} + assert "pull_request" not in publication[True] + assert preview["permissions"] == {"contents": "read"} + assert preview["concurrency"]["cancel-in-progress"] is True + assert "queue" not in preview["concurrency"] + assert publication["concurrency"]["cancel-in-progress"] is False + assert publication["concurrency"]["queue"] == "max" + assert ( + preview["concurrency"]["group"] != publication["concurrency"]["group"] + ) diff --git a/dev/tests/test_cli.py b/dev/tests/test_cli.py index 457b3903..8dae1a2a 100644 --- a/dev/tests/test_cli.py +++ b/dev/tests/test_cli.py @@ -366,6 +366,58 @@ def api(path: str, *, data=None, **kwargs): assert result["error"] in err.getvalue() +@pytest.mark.parametrize( + ("http_status", "expected"), + [ + (403, "dispatch_rejected"), + (404, "dispatch_rejected"), + (422, "dispatch_rejected"), + (408, "dispatch_unknown"), + (429, "dispatch_unknown"), + (500, "dispatch_unknown"), + ], +) +def test_dispatch_http_rejection_is_distinct_from_uncertain_submission( + monkeypatch: pytest.MonkeyPatch, http_status: int, expected: str +) -> None: + from cuphoton_dev import github + + submitted = [] + + def gh(args, **kwargs): + submitted.append(json.loads(kwargs["input"])["inputs"]["request_id"]) + body = '{"message":"Request failed"}' + stdout = ( + f"HTTP/2.0 {http_status} Request failed\n" + f"Content-Type: application/json\n\n{body}" + if "--include" in args + else body + ) + return subprocess.CompletedProcess( + args, 1, stdout, "gh: Request failed" + ) + + monkeypatch.setattr(github.subprocess, "run", gh) + out, err = io.StringIO(), io.StringIO() + assert ( + product_cli.main( + ["dev", "docs-publish", "--ref", "main", "--json"], + out=out, + err=err, + ) + == 1 + ) + result = json.loads(out.getvalue()) + assert len(submitted) == 1 + assert result["request_id"] == submitted[0] + assert result["status"] == expected + assert result["run_id"] is None + assert result["error"] in err.getvalue() + assert ("Inspect that request" in result["error"]) == ( + expected == "dispatch_unknown" + ) + + def test_module_entrypoint() -> None: result = subprocess.run( [sys.executable, "-m", "cuphoton_dev", "--help"], diff --git a/dev/tests/test_prepare.py b/dev/tests/test_prepare.py index 8e3b3e46..7fedf94f 100644 --- a/dev/tests/test_prepare.py +++ b/dev/tests/test_prepare.py @@ -257,3 +257,54 @@ def current_remote_tag(tag): == initial["archive_sha"] ) assert git(publication.source, "rev-parse", "v0.2.0") == publication.sha + + +def test_prepare_missing_skips_releases_without_a_guide( + publication, monkeypatch +): + git(publication.source, "tag", "v0.1.3") + monkeypatch.setattr( + publisher, "releases", lambda: [release(), release("v0.1.3")] + ) + monkeypatch.setattr(publisher, "has_guide", lambda tag: tag == "v0.2.0") + output = publication.root / "backfill" + result = publisher.prepare(tag="missing", output=output) + assert publication.builds == [publication.sha, "v0.2.0"] + assert {entry["version"] for entry in result["catalog"]["versions"]} == { + "main", + "v0.2.0", + } + assert result["catalog"]["stable"] == "v0.2.0" + assert not (output / "v0.1.3").exists() + publisher.docs_check(output) + + +def test_prepare_empty_backfill_refreshes_withdrawn_release( + publication, monkeypatch +): + first = publication.root / "first" + initial = publisher.prepare(tag="v0.2.0", output=first) + assert initial["catalog"]["stable"] == "v0.2.0" + retained_hashes = { + version: file_hashes(first / version) + for version in ("main", "v0.2.0") + } + release_receipt = (first / "v0.2.0/build.json").read_bytes() + monkeypatch.setattr( + publisher, "releases", lambda: [release(prerelease=True)] + ) + monkeypatch.setattr( + publisher, "docs_build", lambda **kwargs: pytest.fail("must retain") + ) + refreshed = publication.root / "refreshed" + result = publisher.prepare(tag="missing", output=refreshed) + assert result["catalog"]["stable"] is None + assert result["catalog"]["preferred"] == "main" + entries = {e["version"]: e for e in result["catalog"]["versions"]} + assert not entries["v0.2.0"]["released"] + assert { + v: file_hashes(refreshed / v) for v in retained_hashes + } == retained_hashes + assert (refreshed / "v0.2.0/build.json").read_bytes() == release_receipt + assert result["archive_sha"] != initial["archive_sha"] + assert publisher.docs_check(refreshed)["stable"] is None diff --git a/dev/tests/test_publisher.py b/dev/tests/test_publisher.py index dc1174dd..d3456fee 100644 --- a/dev/tests/test_publisher.py +++ b/dev/tests/test_publisher.py @@ -3,6 +3,7 @@ # SPDX-License-Identifier: Apache-2.0 """Publication eligibility, isolated builds, and workflow correlation.""" +import subprocess from pathlib import Path import pytest @@ -29,6 +30,7 @@ def release(tag="v0.2.0", **changes): {"published_at": None}, {"tag_name": "v0.2.0rc0"}, {"tag_name": "v01.2.0"}, + {"tag_name": "v0.2.3\u0663"}, ], ) def test_ineligible(changes): @@ -187,6 +189,25 @@ def test_release_pagination(monkeypatch): assert len(github.releases()) == 101 +@pytest.mark.parametrize( + ("status", "body", "expected"), + [(200, '{"value":1}', {"value": 1}), (204, "", None), (404, "{}", None)], +) +def test_api_reads_status_separately_from_json( + monkeypatch, status, body, expected +): + def gh(args, **kwargs): + return subprocess.CompletedProcess( + args, + 1 if status == 404 else 0, + f"HTTP/2.0 {status}\nContent-Type: application/json\n\n{body}", + "gh: Not Found" if status == 404 else "", + ) + + monkeypatch.setattr(github.subprocess, "run", gh) + assert github.api("repos/NVIDIA/cuPhoton", missing_ok=True) == expected + + def test_prepare_rejects_tag_workflow(monkeypatch, tmp_path): monkeypatch.setenv("GITHUB_REPOSITORY", github.REPOSITORY) monkeypatch.setenv("GITHUB_REF", "refs/tags/v0.2.0") diff --git a/dev/tests/test_release_hook.py b/dev/tests/test_release_hook.py index d4b246fb..85d30fb5 100644 --- a/dev/tests/test_release_hook.py +++ b/dev/tests/test_release_hook.py @@ -66,3 +66,21 @@ def test_hook_dispatches_only_final_tags_on_main(tmp_path, tag, dispatch): f"tag={tag}", ] assert not (tmp_path / "injected").exists() + + +@pytest.mark.parametrize( + ("actions", "dispatches"), + [ + (["created", "published", "released"], 1), + (["edited", "released"], 1), + (["created", "published", "prereleased"], 0), + (["created", "edited"], 0), + ], + ids=["initial-final", "promotion", "prerelease", "draft"], +) +def test_hook_selects_one_event_per_final_release(actions, dispatches): + # GitHub's release event contract; live event delivery is qualified + # separately. Subscribing to published as well duplicates initial finals. + workflow = yaml.safe_load(HOOK.read_text()) + subscribed = workflow[True]["release"]["types"] + assert sum(action in subscribed for action in actions) == dispatches diff --git a/dev/tests/test_renderers.py b/dev/tests/test_renderers.py index 1e7fbadb..3d7a92bf 100644 --- a/dev/tests/test_renderers.py +++ b/dev/tests/test_renderers.py @@ -13,73 +13,125 @@ from cuphoton_dev import renderers +def renderer_archive(version="1.9.36", *, unsafe=None): + buffer = io.BytesIO() + with tarfile.open(fileobj=buffer, mode="w:gz") as package: + if unsafe: + member = tarfile.TarInfo( + "../escaped" if unsafe == "path" else "escape" + ) + if unsafe == "symlink": + member.type = tarfile.SYMTYPE + member.linkname = "../escaped" + package.addfile(member) + binary = ( + '#!/bin/sh\nprintf "%s\\n" ' + f'"${{QUARTO_FORCE_VERSION:-{version}}}"\n' + ).encode() + member = tarfile.TarInfo("quarto-1.9.36/bin/quarto") + member.size = len(binary) + member.mode = 0o755 + package.addfile(member, io.BytesIO(binary)) + return buffer.getvalue() + + +def serve_renderer(monkeypatch, payload, *, checksum_matches=True): + monkeypatch.setattr(renderers.platform, "system", lambda: "Linux") + monkeypatch.setattr(renderers.platform, "machine", lambda: "x86_64") + expected = ( + hashlib.sha256(payload).hexdigest() if checksum_matches else "0" * 64 + ) + monkeypatch.setattr( + renderers, "RENDERERS", {"1.9.36": {"amd64": expected}} + ) + urls = [] + + def download(url, **kwargs): + urls.append(url) + return io.BytesIO(payload) + + monkeypatch.setattr(renderers, "urlopen", download) + return urls + + def test_matching_installed_renderer_does_not_use_network( tmp_path, monkeypatch ): binary = tmp_path / "quarto" - binary.write_text("#!/bin/sh\nprintf '1.9.36\\n'\n") + binary.write_text( + '#!/bin/sh\nprintf "%s\\n" "${QUARTO_FORCE_VERSION:-1.9.36}"\n' + ) binary.chmod(0o755) - monkeypatch.setattr(renderers.shutil, "which", lambda name: str(binary)) + monkeypatch.setenv("QUARTO_FORCE_VERSION", "2.0.0") monkeypatch.setattr( renderers, "urlopen", lambda *a, **k: pytest.fail("must not download") ) scratch = tmp_path / "unused" - assert renderers.renderer_for("1.9.36", scratch) == binary + env = {"PATH": str(tmp_path)} + assert renderers.renderer_for("1.9.36", scratch, env=env) == binary assert not scratch.exists() def test_unknown_renderer_requires_controller_update(tmp_path, monkeypatch): monkeypatch.setattr( - renderers.shutil, "which", lambda name: pytest.fail("unsupported pin") + renderers.shutil, + "which", + lambda *a, **k: pytest.fail("unsupported pin"), ) with pytest.raises(ValueError, match="Unsupported Quarto 99.0.0"): - renderers.renderer_for("99.0.0", tmp_path) + renderers.renderer_for("99.0.0", tmp_path, env={}) @pytest.mark.parametrize("checksum_matches", [True, False]) def test_mismatch_downloads_and_verifies_target( tmp_path, monkeypatch, checksum_matches ): - installed = tmp_path / "quarto-newer" - installed.write_text("#!/bin/sh\nprintf '2.0.0\\n'\n") - installed.chmod(0o755) - monkeypatch.setattr( - renderers.shutil, "which", lambda name: str(installed) + installed = tmp_path / "quarto" + installed.write_text( + '#!/bin/sh\nprintf "%s\\n" "${QUARTO_FORCE_VERSION:-2.0.0}"\n' ) - monkeypatch.setattr(renderers.platform, "system", lambda: "Linux") - monkeypatch.setattr(renderers.platform, "machine", lambda: "x86_64") - buffer = io.BytesIO() - binary = b"#!/bin/sh\nprintf '1.9.36\\n'\n" - with tarfile.open(fileobj=buffer, mode="w:gz") as package: - member = tarfile.TarInfo("quarto-1.9.36/bin/quarto") - member.size = len(binary) - member.mode = 0o755 - package.addfile(member, io.BytesIO(binary)) - payload = buffer.getvalue() - expected = ( - hashlib.sha256(payload).hexdigest() if checksum_matches else "0" * 64 - ) - monkeypatch.setattr( - renderers, "RENDERERS", {"1.9.36": {"amd64": expected}} + installed.chmod(0o755) + # Ambient configuration must not spoof either the host or extracted probe. + monkeypatch.setenv("QUARTO_FORCE_VERSION", "1.9.36") + urls = serve_renderer( + monkeypatch, renderer_archive(), checksum_matches=checksum_matches ) - urls = [] - - def download(url, **kwargs): - urls.append(url) - return io.BytesIO(payload) - - monkeypatch.setattr(renderers, "urlopen", download) + env = {"PATH": str(tmp_path)} scratch = tmp_path / "render" if checksum_matches: - executable = renderers.renderer_for("1.9.36", scratch) + executable = renderers.renderer_for("1.9.36", scratch, env=env) assert executable.is_relative_to(scratch) - assert renderers._version(executable) == "1.9.36" - assert installed.read_text() == "#!/bin/sh\nprintf '2.0.0\\n'\n" + assert renderers._version(executable, env=env) == "1.9.36" + assert renderers._version(installed, env=env) == "2.0.0" else: with pytest.raises(ValueError, match="checksum mismatch"): - renderers.renderer_for("1.9.36", scratch) + renderers.renderer_for("1.9.36", scratch, env=env) assert not (scratch / "quarto-1.9.36-amd64/quarto-1.9.36").exists() assert urls == [ "https://github.com/quarto-dev/quarto-cli/releases/download/" "v1.9.36/quarto-1.9.36-linux-amd64.tar.gz" ] + + +@pytest.mark.parametrize("unsafe", ["path", "symlink"]) +def test_verified_archive_cannot_escape_scratch( + tmp_path, monkeypatch, unsafe +): + serve_renderer(monkeypatch, renderer_archive(unsafe=unsafe)) + scratch = tmp_path / "render" + with pytest.raises(tarfile.FilterError): + renderers.renderer_for("1.9.36", scratch, env={"PATH": ""}) + assert not (scratch / "escaped").exists() + assert not (scratch / "quarto-1.9.36-amd64/escape").is_symlink() + + +def test_verified_archive_must_report_pinned_version(tmp_path, monkeypatch): + serve_renderer(monkeypatch, renderer_archive("2.0.0")) + # A trusted digest alone does not prove the executable matches the pin. + monkeypatch.setenv("QUARTO_FORCE_VERSION", "1.9.36") + with pytest.raises( + ValueError, match="Extracted Quarto does not report version 1.9.36" + ): + renderers.renderer_for( + "1.9.36", tmp_path / "render", env={"PATH": ""} + ) diff --git a/dev/tests/test_transforms.py b/dev/tests/test_transforms.py index 71567a10..8288cbd9 100644 --- a/dev/tests/test_transforms.py +++ b/dev/tests/test_transforms.py @@ -9,11 +9,17 @@ import subprocess import sys from pathlib import Path +from xml.etree import ElementTree as ET import pytest from bs4 import BeautifulSoup -from cuphoton_dev.transforms import SITE_URL, check_snapshot, postprocess +from cuphoton_dev.transforms import ( + SITE_URL, + check_snapshot, + file_hashes, + postprocess, +) def rendered_guide(path: Path, *, extra_page: bool = False) -> Path: @@ -399,3 +405,54 @@ def test_utf8_snapshot_and_archive_under_ascii_locale(tmp_path): text=True, ) assert completed.returncode == 0, completed.stderr + + +@pytest.mark.parametrize( + ("corruption", "message"), + [ + ("schema", "Unsupported documentation receipt schema"), + ("version", "Not a documentation version"), + ("required-output", "missing required guide output"), + ("page-inventory", "HTML inventory is incomplete"), + ("canonical", "Wrong canonical URL"), + ("anchor-inventory", "Wrong anchor inventory"), + ("search-target", "Search target is outside snapshot"), + ("sitemap", "Sitemap does not describe"), + ], +) +def test_snapshot_rejects_inconsistent_metadata( + tmp_path, corruption, message +): + path = snapshot(tmp_path / "snapshot", "v0.2.0") + receipt_path = path / "build.json" + receipt = json.loads(receipt_path.read_text(encoding="utf-8")) + if corruption == "schema": + receipt["schema"] = 2 + elif corruption == "version": + receipt["version"] = "v0.2.3\u0663" + elif corruption == "required-output": + (path / "search.json").unlink() + elif corruption == "page-inventory": + receipt["pages"].pop("install.html") + elif corruption == "canonical": + index = path / "index.html" + soup = BeautifulSoup(index.read_text(encoding="utf-8"), "html.parser") + soup.select_one('link[rel="canonical"]')["href"] = SITE_URL + "main/" + index.write_text(str(soup), encoding="utf-8") + elif corruption == "anchor-inventory": + receipt["pages"]["install.html"].append("unrendered-anchor") + elif corruption == "search-target": + search = path / "search.json" + records = json.loads(search.read_text(encoding="utf-8")) + records[0]["href"] = "not-a-chapter.html" + search.write_text(json.dumps(records), encoding="utf-8") + else: + sitemap = path / "sitemap.xml" + tree = ET.parse(sitemap) + tree.getroot().remove(tree.getroot()[0]) + tree.write(sitemap, encoding="utf-8", xml_declaration=True) + # Exercise semantic checks even when the receipt matches the file bytes. + receipt["files"] = file_hashes(path) + receipt_path.write_text(json.dumps(receipt), encoding="utf-8") + with pytest.raises(ValueError, match=message): + check_snapshot(path) diff --git a/src/cuphoton/core/cli/component.py b/src/cuphoton/core/cli/component.py index 0199d7c1..636ad50e 100644 --- a/src/cuphoton/core/cli/component.py +++ b/src/cuphoton/core/cli/component.py @@ -48,8 +48,7 @@ def __post_init__(self) -> None: ) ): raise ValueError( - "component import_name must be within the cuphoton namespace " - "or use the dedicated cuphoton_dev specification" + "component import_name must be within the cuphoton namespace" ) if self.parser_style not in {"optparse", "argparse"}: raise ValueError(f"unknown parser style: {self.parser_style!r}") From 3571fe56db17a8b9f1579b73b2817e1332b7f527 Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Thu, 12 Nov 2026 09:12:46 -0800 Subject: [PATCH 6/9] Clarify HTTP outcomes in documentation recovery guidance Name the HTTP responses classified as uncertain so rate-limit errors returned as HTTP 403 are not confused with the HTTP 429 policy. Signed-off-by: Trent Nelson --- dev/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dev/README.md b/dev/README.md index ef8ea3a1..8446d98d 100644 --- a/dev/README.md +++ b/dev/README.md @@ -136,8 +136,8 @@ request ID with null run fields; use that ID before attempting a new dispatch. If submission fails before confirmation, `dispatch_unknown` preserves the request ID without claiming acceptance; inspect that request before retrying. Definite HTTP client errors report `dispatch_rejected`; correct the reported -error before retrying. Timeouts, rate limits and server or transport failures -retain the unknown outcome. +error before retrying. HTTP 408 and 429 responses, server errors and transport +failures retain an unknown outcome. For an accepted or uncertain dispatch, replace `REQUEST_ID` with its returned identifier to find the run: From 8d830a948be1154b6dca1ed75ea8c7368ceab50e Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Thu, 12 Nov 2026 14:51:33 -0800 Subject: [PATCH 7/9] Resolve documentation release tags and active renderer pins Use the explicit tag commit for release labels, even when other refs share its name. Ignore commented renderer URLs so builds use the active target workflow pin. Signed-off-by: Trent Nelson --- dev/src/cuphoton_dev/build.py | 32 ++++++++++++++++++------- dev/tests/test_build.py | 45 +++++++++++++++++++++++++++++++++-- 2 files changed, 67 insertions(+), 10 deletions(-) diff --git a/dev/src/cuphoton_dev/build.py b/dev/src/cuphoton_dev/build.py index 46434a7e..0f78cb82 100644 --- a/dev/src/cuphoton_dev/build.py +++ b/dev/src/cuphoton_dev/build.py @@ -73,6 +73,19 @@ def resolve(repo: Path, ref: str) -> str: ) +def renderer_version(workflow: str) -> str: + """Read the target renderer pin, ignoring full-line comments.""" + active = "\n".join( + line + for line in workflow.splitlines() + if not line.lstrip().startswith("#") + ) + pin = re.search(r"releases/download/v([0-9.]+)/quarto", active) + if not pin: + raise ValueError("Target has no recognized pinned Quarto renderer") + return pin[1] + + def render_environment(checkout: Path) -> dict[str, str]: """Isolate Python, uv and Quarto from the controller's configuration.""" env = dict(os.environ) @@ -126,13 +139,21 @@ def docs_build( output = output.resolve() if output.exists(): raise ValueError(f"Output already exists: {output}") - source_sha = resolve(repo, ref) tag = ( ref.removeprefix("refs/tags/") if ref.startswith("refs/tags/") else ref.removeprefix("tags/") ) - version = tag if FINAL_TAG.fullmatch(tag) else "main" + version = "main" + if FINAL_TAG.fullmatch(tag): + try: + source_sha = resolve(repo, f"refs/tags/{tag}") + except RuntimeError: + source_sha = resolve(repo, ref) + else: + version = tag + else: + source_sha = resolve(repo, ref) controller_repo = Path(__file__).resolve().parents[3] controller_sha = resolve(controller_repo, "HEAD") output.parent.mkdir(parents=True, exist_ok=True) @@ -158,12 +179,7 @@ def docs_build( workflow = (checkout / ".github/workflows/docs.yml").read_text( encoding="utf-8" ) - pin = re.search(r"releases/download/v([0-9.]+)/quarto", workflow) - if not pin: - raise ValueError( - "Target has no recognized pinned Quarto renderer" - ) - renderer = pin[1] + renderer = renderer_version(workflow) env = render_environment(checkout) quarto = renderer_for(renderer, Path(temporary), env=env) # Allow a site-specific environment provisioning wrapper. diff --git a/dev/tests/test_build.py b/dev/tests/test_build.py index 51272d99..887d990d 100644 --- a/dev/tests/test_build.py +++ b/dev/tests/test_build.py @@ -108,7 +108,10 @@ def build_source(tmp_path, monkeypatch): workflow = source / ".github/workflows/docs.yml" workflow.parent.mkdir(parents=True) workflow.write_text( - "# https://github.com/quarto-dev/quarto-cli/releases/download/" + "jobs:\n build:\n steps:\n" + " # https://github.com/quarto-dev/quarto-cli/releases/download/" + "v1.8.0/quarto-1.8.0-linux-amd64.tar.gz\n" + " - run: curl https://github.com/quarto-dev/quarto-cli/releases/download/" "v1.9.36/quarto-1.9.36-linux-amd64.tar.gz\n", encoding="utf-8", ) @@ -169,13 +172,20 @@ def test_build_uses_committed_source_and_isolated_locked_environment( build_source, ref ): fixture = build_source + # Both the branch and a higher-precedence ref differ from the actual tag. + git(fixture.source, "branch", "v0.2.0", "HEAD") + git(fixture.source, "update-ref", "refs/v0.2.0", "HEAD") before = git(fixture.source, "status", "--porcelain") result = build.docs_build( ref=ref, output=fixture.output, repo=fixture.source ) expected_version = "main" if ref == "HEAD" else "v0.2.0" assert result["version"] == expected_version - assert result["source_sha"] == git(fixture.source, "rev-parse", ref) + expected_ref = "HEAD" if ref == "HEAD" else "refs/tags/v0.2.0" + assert result["source_sha"] == git( + fixture.source, "rev-parse", expected_ref + ) + assert result["renderer"] == "1.9.36" assert ( result["lock_sha256"] == hashlib.sha256(b"committed lock\n").hexdigest() @@ -190,6 +200,37 @@ def test_build_uses_committed_source_and_isolated_locked_environment( ) == "dirty controller source\n" +def test_semantic_version_branch_without_tag_is_a_main_preview(build_source): + fixture = build_source + git(fixture.source, "branch", "v0.2.1", "HEAD") + result = build.docs_build( + ref="v0.2.1", output=fixture.output, repo=fixture.source + ) + assert result["version"] == "main" + assert result["source_sha"] == git(fixture.source, "rev-parse", "HEAD") + assert "/cuPhoton/main/index.html" in ( + fixture.output / "index.html" + ).read_text(encoding="utf-8") + + +def test_commented_renderer_pin_cannot_build(build_source): + fixture = build_source + workflow = fixture.source / ".github/workflows/docs.yml" + workflow.write_text( + "# https://github.com/quarto-dev/quarto-cli/releases/download/" + "v1.9.36/quarto-1.9.36-linux-amd64.tar.gz\n", + encoding="utf-8", + ) + git(fixture.source, "add", str(workflow)) + git(fixture.source, "commit", "-qm", "remove active renderer install") + with pytest.raises(ValueError, match="no recognized pinned Quarto"): + build.docs_build( + ref="HEAD", output=fixture.output, repo=fixture.source + ) + assert not fixture.output.exists() + assert not fixture.log.exists() + + @pytest.mark.parametrize("mutation", ["unstaged", "staged"]) def test_build_rejects_tracked_render_mutations( build_source, monkeypatch, mutation From 8114eb2d704963f47bd437249c893cf87b84e366 Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Thu, 12 Nov 2026 14:52:04 -0800 Subject: [PATCH 8/9] Separate documentation rendering from archive and Pages credentials Render target source with read-only access, then verify its artifact in a fresh trusted-main job before retaining the complete site. Keep Pages deployment separate and reject retries of an obsolete archive. Require a dedicated archive writer and protected generated history. Check release ancestry and workflow schemas before publication, while preserving idempotent recovery and existing product CI requirements. Signed-off-by: Trent Nelson --- .github/workflows/ci.yml | 4 + .github/workflows/docs.yml | 130 +++++++++-- dev/.gitignore | 1 + dev/AGENTS.md | 5 + dev/README.md | 49 +++- dev/src/cuphoton_dev/artifacts.py | 170 ++++++++++++++ dev/src/cuphoton_dev/publisher.py | 331 ++++++++++++++++++++++------ dev/tests/test_artifacts.py | 234 ++++++++++++++++++++ dev/tests/test_prepare.py | 325 +++++++++++++++++++++++++-- dev/tests/test_publisher.py | 6 +- dev/uv.lock | 4 +- dev/workflow-lint/check.mjs | 72 ++++++ dev/workflow-lint/json-loader.mjs | 11 + dev/workflow-lint/package-lock.json | 64 ++++++ dev/workflow-lint/package.json | 15 ++ 15 files changed, 1308 insertions(+), 113 deletions(-) create mode 100644 dev/src/cuphoton_dev/artifacts.py create mode 100644 dev/tests/test_artifacts.py create mode 100644 dev/workflow-lint/check.mjs create mode 100644 dev/workflow-lint/json-loader.mjs create mode 100644 dev/workflow-lint/package-lock.json create mode 100644 dev/workflow-lint/package.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6eaf0a32..e62da101 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -86,6 +86,10 @@ jobs: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 with: persist-credentials: false + - name: Install the workflow schema validator + run: npm ci --prefix dev/workflow-lint --ignore-scripts --no-audit --no-fund + - name: Validate GitHub Actions workflows + run: npm run --prefix dev/workflow-lint check - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6 with: version: "0.12.1" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 9398591b..604244dc 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -48,24 +48,21 @@ env: UV_HTTP_TIMEOUT: "300" jobs: - publish: - name: publish user guide + render: + name: render user guide if: >- github.repository == 'NVIDIA/cuPhoton' && github.ref == 'refs/heads/main' runs-on: ubuntu-24.04 timeout-minutes: 90 permissions: - contents: write - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} + contents: read + outputs: + artifact_id: ${{ steps.snapshots.outputs.artifact-id }} + artifact_digest: ${{ steps.snapshots.outputs.artifact-digest }} steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 with: - # Controller code is always the main SHA that started this workflow. ref: ${{ github.sha }} persist-credentials: false fetch-depth: 0 @@ -83,22 +80,125 @@ jobs: 8c47762e78fe58642246a94d18f67eb332c1778b711e5bef991ef3c15490d83a \ "$RUNNER_TEMP/quarto.deb" | sha256sum --check sudo dpkg --install "$RUNNER_TEMP/quarto.deb" - - name: Retain snapshots and assemble the complete site + - name: Render missing snapshots env: GH_TOKEN: ${{ github.token }} DOCS_TAG: ${{ inputs.tag }} DOCS_REQUEST_ID: ${{ inputs.request_id }} run: >- - uv run --project dev --locked python -m cuphoton_dev.publisher prepare + uv run --project dev --locked python -m cuphoton_dev.publisher render --tag "$DOCS_TAG" --request-id "$DOCS_REQUEST_ID" - --output "$RUNNER_TEMP/site" - - name: Check the complete publication - run: uv run --project dev --locked cuphoton dev docs-check "$RUNNER_TEMP/site" - - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 + --output "$RUNNER_TEMP/snapshots" + - name: Upload rendered snapshots + id: snapshots + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: docs-snapshots-${{ github.run_id }}-${{ github.run_attempt }} + path: ${{ runner.temp }}/snapshots + include-hidden-files: true + if-no-files-found: error + retention-days: 7 + + retain: + name: retain and assemble user guide + needs: render + runs-on: ubuntu-24.04 + timeout-minutes: 30 + permissions: + actions: read + contents: read + environment: docs-archive + outputs: + archive_sha: ${{ steps.archive.outputs.sha }} + pages_artifact: ${{ steps.archive.outputs.pages_artifact }} + env: + # Never restore a cache populated by target-source execution. + UV_NO_CACHE: "1" + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + # Only the reviewed main controller runs in this fresh job. + ref: ${{ github.sha }} + persist-credentials: false + fetch-depth: 0 + - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6 + with: + version: "0.12.1" + enable-cache: false + - name: Install trusted main controller + run: uv sync --project dev --locked --python 3.12 + - name: Download and verify this run's snapshots + env: + GH_TOKEN: ${{ github.token }} + ARTIFACT_ID: ${{ needs.render.outputs.artifact_id }} + ARTIFACT_DIGEST: ${{ needs.render.outputs.artifact_digest }} + run: >- + uv run --project dev --locked python -m cuphoton_dev.artifacts download + --artifact-id "$ARTIFACT_ID" --digest "$ARTIFACT_DIGEST" + --output "$RUNNER_TEMP/snapshots" + - name: Require archive protection before publication + env: + GH_TOKEN: ${{ github.token }} + run: | + gh api repos/NVIDIA/cuPhoton/rules/branches/gh-pages > "$RUNNER_TEMP/archive-rules.json" + jq --exit-status ' + map(.type) as $types | + ["creation", "update", "deletion", "non_fast_forward"] | + all(. as $rule | $types | index($rule) != null) + ' "$RUNNER_TEMP/archive-rules.json" + - name: Create repository-scoped archive writer token + id: writer + uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2 + with: + app-id: ${{ vars.DOCS_ARCHIVE_APP_ID }} + private-key: ${{ secrets.DOCS_ARCHIVE_PRIVATE_KEY }} + permission-contents: write + - name: Retain snapshots and assemble the complete site + id: archive + env: + GH_TOKEN: ${{ steps.writer.outputs.token }} + DOCS_TAG: ${{ inputs.tag }} + DOCS_REQUEST_ID: ${{ inputs.request_id }} + run: | + uv run --project dev --locked python -m cuphoton_dev.publisher prepare \ + --tag "$DOCS_TAG" --request-id "$DOCS_REQUEST_ID" \ + --snapshots "$RUNNER_TEMP/snapshots" --output "$RUNNER_TEMP/site" \ + > "$RUNNER_TEMP/publication.json" + jq -r '"sha=" + .archive_sha' "$RUNNER_TEMP/publication.json" >> "$GITHUB_OUTPUT" + echo "pages_artifact=github-pages-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" >> "$GITHUB_OUTPUT" - name: Upload the complete retained site uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 with: + name: ${{ steps.archive.outputs.pages_artifact }} path: ${{ runner.temp }}/site + include-hidden-files: true + + deploy: + name: deploy user guide + needs: retain + runs-on: ubuntu-24.04 + timeout-minutes: 15 + permissions: + contents: read + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Refuse a stale deployment retry + env: + GH_TOKEN: ${{ github.token }} + ARCHIVE_SHA: ${{ needs.retain.outputs.archive_sha }} + run: | + current=$(gh api repos/NVIDIA/cuPhoton/git/ref/heads/gh-pages --jq .object.sha) + if [ -z "$ARCHIVE_SHA" ] || [ "$current" != "$ARCHIVE_SHA" ]; then + echo "Archive has advanced; dispatch a new publication instead of retrying this deployment." + exit 1 + fi + - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 + with: + artifact_name: ${{ needs.retain.outputs.pages_artifact }} diff --git a/dev/.gitignore b/dev/.gitignore index 22d65b82..af57b6aa 100644 --- a/dev/.gitignore +++ b/dev/.gitignore @@ -1,3 +1,4 @@ .venv .coverage* coverage*.xml +/workflow-lint/node_modules diff --git a/dev/AGENTS.md b/dev/AGENTS.md index c400e277..62bd83e1 100644 --- a/dev/AGENTS.md +++ b/dev/AGENTS.md @@ -17,6 +17,11 @@ Scope: the independent `dev/` project and its documentation publishing workflows - Every publication must validate formal-release eligibility, retained hashes, tag identity and the complete catalog. Hold the shared publication lock from reading the archive through native Pages deployment. Keep PR jobs read-only. +- Execute target source only in the read-only render job. The archive job must + run only main's controller, validate transferred snapshots and avoid render + caches. Keep archive-write and Pages/OIDC credentials in separate jobs. + Preserve the dedicated writer identity, main-only environments and archive + creation/update/deletion/force-push protections documented in the runbook. - Keep transformation fixtures synchronized with guide markup, install examples, link structure and search output. Unexpected version-sensitive markup should fail validation rather than silently publish stale main instructions. diff --git a/dev/README.md b/dev/README.md index 8446d98d..17c57a75 100644 --- a/dev/README.md +++ b/dev/README.md @@ -33,6 +33,8 @@ uv run --project dev --locked ruff check dev scripts/ci uv run --project dev --locked ruff format --check dev scripts/ci uv run --project dev --locked mypy --config-file dev/pyproject.toml dev/src/cuphoton_dev uv run --project dev --locked pytest -c dev/pyproject.toml dev/tests +npm ci --prefix dev/workflow-lint --ignore-scripts +npm run --prefix dev/workflow-lint check ``` CI writes developer coverage separately from product coverage. The changes @@ -54,6 +56,10 @@ uv lock --project dev --check Beautiful Soup and Soup Sieve are MIT-licensed developer-only dependencies. Keep dependency/license review and `dev/uv.lock` synchronized when updating them; they are not product dependencies or product payloads. +The workflow schema check uses GitHub's pinned `@actions/workflow-parser` +and its own npm lockfile. Its parser, expressions and cron dependencies are +MIT-licensed; YAML is ISC-licensed. Keep that lockfile and schema check current +when changing workflow syntax. These tools are also excluded from products. Keep new dependency paths in `scripts/ci/dev_changes.py`. Changes to guide markup, install wording, source URLs or search output also require review of @@ -91,7 +97,8 @@ uv run --project dev --locked cuphoton dev docs-status --json A draft release can be built and checked locally. Publication additionally requires a published, non-prerelease GitHub Release whose tag is a full final -version such as `v0.2.0`. Older tags without the guide are reported as +version such as `v0.2.0`, with its commit on `main`, `0.1.x` or `0.2.x`, matching +the package release policy. Older tags without the guide are reported as unavailable; they are not populated from newer content. ## Site layout and ownership @@ -123,6 +130,30 @@ These archive commits are exempt from source-contribution identity, signature and DCO requirements; each snapshot records the source and controller commit SHAs. Source changes continue to follow the contributor signing rules. +Before the first publication, configure a dedicated GitHub App installed only +on `NVIDIA/cuPhoton` with repository contents write permission. Store its app +ID as `DOCS_ARCHIVE_APP_ID` and its private key as `DOCS_ARCHIVE_PRIVATE_KEY` +in the `docs-archive` environment, restricted to the `main` deployment branch. +The workflow mints a short-lived token for this repository and revokes it when +the archive job ends. Keep the existing `github-pages` environment restricted +to main as well. + +Apply two active rulesets targeting exactly `refs/heads/gh-pages` before that +branch is created: + +- Prohibit deletion and force pushes, with no bypass actors. +- Restrict creation and updates, with only the dedicated App as an always + allowed integration bypass actor. + +Keeping these separate prevents the writer from bypassing the history rules. +Do not grant the shared GitHub Actions identity a bypass. Rulesets identify +the App, not the workflow filename; reviewed main code and the environment's +branch restriction control access to its key. Repository administrators +remain responsible for maintaining these policies. The archive job checks +that all four rule types apply and fails before obtaining a write token if +they do not. An administrator must also verify the exact bypass identities +and main-only environment configuration during setup and after policy edits. + ## Publish, bootstrap and recover Authenticate `gh` with access to dispatch repository Actions. For a normal @@ -163,12 +194,22 @@ Keep its tag unchanged. Before eligibility, finish the local render and check and leave this command ready; documentation rollout does not authorize release publication. -The workflow serializes archive updates through Pages deployment. It re-reads -retained state under the lock, rejects a moved tag or stale main rollback, -validates the complete site and publishes through native Pages actions. A +The workflow serializes archive updates through Pages deployment. Its render +job has read-only repository access and no publication environment or write +credentials. It uploads the new snapshots. A fresh archive job installs only +the trusted main controller, with caches disabled, verifies the artifact's +run, source and digest, and independently checks each snapshot's provenance +against Git source. It re-reads retained state under the lock, rejects a moved +tag or stale main rollback, validates the complete site and pushes the archive. +Only the final job receives Pages and OIDC write permissions; it runs native +Pages actions without checking out or executing the target source. A failed render leaves the live site and catalog intact. If deployment fails after retaining the assembled site, retry the workflow or repeat the same CLI command. Matching release snapshots are reused, so duplicate requests are safe. +Downstream retries can reuse the original render artifact from the same run. +If that artifact has expired, dispatch a new publication. A deployment-only +retry checks the retained commit and fails if another publication has advanced +the archive; dispatch a new publication in that case too. Use `--missing` for deliberate reconciliation of eligible missing releases. PR builds run in `docs-preview.yml` with read-only permissions and cancel diff --git a/dev/src/cuphoton_dev/artifacts.py b/dev/src/cuphoton_dev/artifacts.py new file mode 100644 index 00000000..e56c51f2 --- /dev/null +++ b/dev/src/cuphoton_dev/artifacts.py @@ -0,0 +1,170 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +"""Download and verify the immutable snapshot artifact for a main workflow.""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import re +import shutil +import stat +import subprocess +import tempfile +import zipfile +from pathlib import Path, PurePosixPath +from typing import Any + +from cuphoton_dev.github import REPOSITORY, api + + +def _extract(archive: Path, destination: Path) -> None: + seen: set[str] = set() + with zipfile.ZipFile(archive) as package: + for member in package.infolist(): + name = member.filename.removesuffix("/") + path = PurePosixPath(name) + kind = stat.S_IFMT(member.external_attr >> 16) + if ( + not path.parts + or member.filename != member.orig_filename + or path.is_absolute() + or path.as_posix() != name + or ".." in path.parts + or any(part.lower() == ".git" for part in path.parts) + or "\\" in name + or ":" in name + or name in seen + or kind not in {0, stat.S_IFREG, stat.S_IFDIR} + or (kind == stat.S_IFDIR and not member.is_dir()) + or (kind == stat.S_IFREG and member.is_dir()) + ): + raise ValueError(f"Unsafe snapshot artifact entry: {name!r}") + seen.add(name) + target = destination.joinpath(*path.parts) + if member.is_dir(): + target.mkdir(parents=True, exist_ok=True) + else: + target.parent.mkdir(parents=True, exist_ok=True) + with package.open(member) as source, target.open("xb") as out: + shutil.copyfileobj(source, out) + + +def download( + *, artifact_id: int, digest: str, output: Path +) -> dict[str, Any]: + """Accept only verified bytes from this canonical main workflow run.""" + output = output.absolute() + if output.exists() or output.is_symlink(): + raise ValueError(f"Output already exists: {output}") + run_id = os.environ.get("GITHUB_RUN_ID", "") + attempt = os.environ.get("GITHUB_RUN_ATTEMPT", "") + sha = os.environ.get("GITHUB_SHA", "") + digest = digest.lower() + if ( + os.environ.get("GITHUB_REPOSITORY") != REPOSITORY + or not re.fullmatch(r"[1-9][0-9]*", run_id) + or not re.fullmatch(r"[1-9][0-9]*", attempt) + or not re.fullmatch(r"[0-9a-f]{40}", sha) + or not re.fullmatch(r"[0-9a-f]{64}", digest) + or artifact_id < 1 + ): + raise ValueError( + "Expected canonical workflow identity and artifact digest" + ) + base = f"repos/{REPOSITORY}/actions" + run = api(f"{base}/runs/{run_id}") + if ( + run.get("id") != int(run_id) + or run.get("path") != ".github/workflows/docs.yml" + or run.get("event") not in {"push", "workflow_dispatch"} + or run.get("head_branch") != "main" + or run.get("head_sha") != sha + or run.get("repository", {}).get("full_name") != REPOSITORY + or run.get("head_repository", {}).get("full_name") != REPOSITORY + ): + raise ValueError( + "Artifact download requires the canonical main docs workflow" + ) + artifact = api(f"{base}/artifacts/{artifact_id}") + producer = artifact.get("workflow_run") or {} + name = re.fullmatch( + rf"docs-snapshots-{run_id}-([1-9][0-9]*)", artifact.get("name", "") + ) + if ( + artifact.get("id") != artifact_id + or artifact.get("expired") is not False + or artifact.get("digest") != f"sha256:{digest}" + or producer.get("id") != int(run_id) + or producer.get("head_sha") != sha + or name is None + or int(name[1]) > int(attempt) + ): + raise ValueError( + "Snapshot artifact identity or digest does not match this run" + ) + output.parent.mkdir(parents=True, exist_ok=True) + with tempfile.TemporaryDirectory( + prefix=".docs-artifact-", dir=output.parent + ) as temporary: + work = Path(temporary) + archive = work / "artifact.zip" + with archive.open("wb") as stream: + result = subprocess.run( + [ + "gh", + "api", + "-H", + "X-GitHub-Api-Version: 2026-03-10", + f"{base}/artifacts/{artifact_id}/zip", + ], + stdout=stream, + stderr=subprocess.PIPE, + ) + if result.returncode: + raise RuntimeError( + "Artifact download failed: " + + result.stderr.decode("utf-8", errors="replace").strip() + ) + with archive.open("rb") as stream: + actual = hashlib.file_digest(stream, "sha256").hexdigest() + if actual != digest: + raise ValueError("Downloaded snapshot artifact SHA256 mismatch") + extracted = work / "snapshots" + extracted.mkdir() + _extract(archive, extracted) + extracted.rename(output) + return { + "artifact_id": artifact_id, + "digest": digest, + "output": str(output), + } + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + commands = parser.add_subparsers(dest="command", required=True) + command = commands.add_parser("download") + command.add_argument("--artifact-id", required=True, type=int) + command.add_argument("--digest", required=True) + command.add_argument("--output", required=True, type=Path) + args = parser.parse_args() + print( + json.dumps( + download( + artifact_id=args.artifact_id, + digest=args.digest, + output=args.output, + ), + sort_keys=True, + ) + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/dev/src/cuphoton_dev/publisher.py b/dev/src/cuphoton_dev/publisher.py index 353980ff..96173e57 100644 --- a/dev/src/cuphoton_dev/publisher.py +++ b/dev/src/cuphoton_dev/publisher.py @@ -6,6 +6,7 @@ from __future__ import annotations import argparse +import hashlib import json import os import shutil @@ -14,7 +15,14 @@ from pathlib import Path from typing import Any -from cuphoton_dev.build import FINAL_TAG, docs_build, git, resolve, run +from cuphoton_dev.build import ( + FINAL_TAG, + docs_build, + git, + renderer_version, + resolve, + run, +) from cuphoton_dev.github import ( REPOSITORY, docs_publish, @@ -95,17 +103,7 @@ def clone_archive(destination: Path) -> None: git(destination, "remote", "add", "origin", remote) -def prepare( - *, tag: str, output: Path, request_id: str = "" -) -> dict[str, Any]: - """Assemble and retain a full site inside the workflow's publication lock. - - Deployment uses native Pages actions after this succeeds. A failed deploy - can retry this operation, reusing matching release snapshots verbatim. - """ - from cuphoton_dev.archive import assemble, check_archive - from cuphoton_dev.transforms import check_snapshot - +def _context(tag: str) -> tuple[Path, str, str, str, int]: if ( os.environ.get("GITHUB_REPOSITORY") != REPOSITORY or os.environ.get("GITHUB_REF") != "refs/heads/main" @@ -122,70 +120,253 @@ def prepare( raise ValueError( "Controller checkout must match the workflow main SHA" ) - output = output.resolve() - if output.exists(): - raise ValueError(f"Output already exists: {output}") tag = tag or "main" if tag not in {"main", "missing"} and not FINAL_TAG.fullmatch(tag): raise ValueError( "Expected main, missing, or a full release tag vX.Y.Z" ) - release_records = releases() - eligible_tags = {r["tag_name"] for r in release_records if eligible(r)} + run_id = os.environ.get("GITHUB_RUN_ID", "") + attempt = int(os.environ.get("GITHUB_RUN_ATTEMPT", "0")) + if not run_id.isascii() or not run_id.isdecimal() or attempt < 1: + raise ValueError("Publication requires a workflow run and attempt") + return repo, controller, tag, run_id, attempt + + +def _release_source(repo: Path, tag: str) -> str: + source = resolve(repo, f"refs/tags/{tag}") + if remote_tag_commit(tag) != source: + raise ValueError(f"Release tag moved during publication: {tag}") + supported = { + "refs/remotes/origin/main", + "refs/remotes/origin/0.1.x", + "refs/remotes/origin/0.2.x", + } + branches = supported.intersection( + git( + repo, "for-each-ref", "--format=%(refname)", *sorted(supported) + ).splitlines() + ) + if not any(is_ancestor(repo, source, branch) for branch in branches): + raise ValueError("Release commit must belong to main, 0.1.x or 0.2.x") + return source + + +def _targets( + repo: Path, controller: str, tag: str, retained: Path +) -> tuple[dict[str, str], set[str]]: + from cuphoton_dev.archive import check_archive + + if (retained / "versions.json").exists(): + check_archive(retained) + eligible_tags = {r["tag_name"] for r in releases() if eligible(r)} if tag not in {"main", "missing"} and tag not in eligible_tags: raise ValueError(f"{tag} is not a published final GitHub Release") - if tag == "missing": - targets = sorted(t for t in eligible_tags if has_guide(t)) - else: - targets = [tag] + targets = ( + sorted(t for t in eligible_tags if has_guide(t)) + if tag == "missing" + else [tag] + ) + if not (retained / "main/build.json").exists() and "main" not in targets: + targets.insert(0, "main") + sources = { + target: controller + if target == "main" + else _release_source(repo, target) + for target in targets + } + return sources, eligible_tags + + +def _reuse(prior: Path, target: str, source: str, controller: str) -> bool: + from cuphoton_dev.transforms import check_snapshot + + if not prior.exists(): + return False + receipt = check_snapshot(prior) + if target != "main" and receipt["source_sha"] != source: + raise ValueError(f"Retained {target} conflicts with the current tag") + return target != "main" or ( + receipt["source_sha"] == source + and receipt["controller_sha"] == controller + ) + + +def _check_render( + path: Path, repo: Path, target: str, source: str, controller: str +) -> None: + from cuphoton_dev.renderers import RENDERERS + from cuphoton_dev.transforms import SITE_URL, check_snapshot + + receipt = check_snapshot(path) + workflow = git(repo, "show", f"{source}:.github/workflows/docs.yml") + renderer = renderer_version(workflow) + if renderer not in RENDERERS: + raise ValueError(f"Unsupported Quarto {renderer}") + lock = subprocess.check_output( + ["git", "-C", str(repo), "show", f"{source}:uv.lock"] + ) + expected = { + "version": target, + "source_sha": source, + "controller_sha": controller, + "lock_sha256": hashlib.sha256(lock).hexdigest(), + "renderer": renderer, + "site_url": SITE_URL, + } + for key, value in expected.items(): + if receipt.get(key) != value: + raise ValueError(f"Rendered {target} has unexpected {key}") + + +def render_bundle( + *, tag: str, output: Path, request_id: str = "" +) -> dict[str, Any]: + """Render missing snapshots in a read-only workflow job. + + Retained snapshots are never copied into the bundle. The writer re-reads + them independently, so a retry after retention does not rebuild history. + """ + repo, controller, tag, run_id, attempt = _context(tag) + output = output.resolve() + if output.exists(): + raise ValueError(f"Output already exists: {output}") + with tempfile.TemporaryDirectory(prefix="cuphoton-render-") as temporary: + work = Path(temporary) + retained = work / "archive" + clone_archive(retained) + sources, _ = _targets(repo, controller, tag, retained) + bundle = work / "bundle" + bundle.mkdir() + rendered = {} + for target, source in sources.items(): + if _reuse(retained / target, target, source, controller): + continue + docs_build( + ref=controller if target == "main" else f"refs/tags/{target}", + output=bundle / target, + repo=repo, + ) + _check_render(bundle / target, repo, target, source, controller) + rendered[target] = source + manifest = { + "schema": 1, + "repository": REPOSITORY, + "controller_sha": controller, + "run_id": run_id, + "run_attempt": attempt, + "tag": tag, + "request_id": request_id, + "snapshots": rendered, + } + (bundle / "manifest.json").write_text( + json.dumps(manifest, indent=2, sort_keys=True) + "\n", + encoding="utf-8", + ) + output.parent.mkdir(parents=True, exist_ok=True) + shutil.copytree(bundle, output) + return {"output": str(output), **manifest} + + +def _bundle_sources( + bundle: Path, + *, + controller: str, + tag: str, + run_id: str, + attempt: int, + request_id: str, +) -> dict[str, str]: + if bundle.is_symlink() or any(p.is_symlink() for p in bundle.iterdir()): + raise ValueError("Snapshot bundle contains a symbolic link") + manifest = json.loads( + (bundle / "manifest.json").read_text(encoding="utf-8") + ) + expected = { + "schema": 1, + "repository": REPOSITORY, + "controller_sha": controller, + "run_id": run_id, + "tag": tag, + "request_id": request_id, + } + if not isinstance(manifest, dict): + raise ValueError("Snapshot bundle manifest must be an object") + for key, value in expected.items(): + if manifest.get(key) != value: + raise ValueError(f"Snapshot bundle has unexpected {key}") + producer_attempt = manifest.get("run_attempt") + if ( + type(producer_attempt) is not int + or not 1 <= producer_attempt <= attempt + ): + raise ValueError("Snapshot bundle has unexpected run_attempt") + sources = manifest.get("snapshots") + if not isinstance(sources, dict) or not all( + isinstance(target, str) + and (target == "main" or FINAL_TAG.fullmatch(target)) + and isinstance(source, str) + for target, source in sources.items() + ): + raise ValueError("Snapshot bundle has invalid sources") + if {p.name for p in bundle.iterdir()} != {"manifest.json", *sources}: + raise ValueError( + "Snapshot bundle inventory differs from its manifest" + ) + return sources + + +def prepare( + *, tag: str, snapshots: Path, output: Path, request_id: str = "" +) -> dict[str, Any]: + """Validate transferred output and retain the site without rendering. + + The caller verifies the immutable Actions artifact identity and digest. + This trusted-main phase independently checks source policy and receipts. + """ + from cuphoton_dev.archive import assemble, check_archive + + repo, controller, tag, run_id, attempt = _context(tag) + output = output.resolve() + if output.exists(): + raise ValueError(f"Output already exists: {output}") + supplied = _bundle_sources( + snapshots, + controller=controller, + tag=tag, + run_id=run_id, + attempt=attempt, + request_id=request_id, + ) with tempfile.TemporaryDirectory( prefix="cuphoton-publication-" ) as temporary: work = Path(temporary) retained = work / "archive" clone_archive(retained) - if (retained / "versions.json").exists(): - check_archive(retained) - if ( - not (retained / "main/build.json").exists() - and "main" not in targets - ): - targets.insert(0, "main") - release_sources: dict[str, str] = {} - for target in targets: - source_ref = ( - controller if target == "main" else f"refs/tags/{target}" - ) - source_sha = resolve(repo, source_ref) - if target != "main": - release_sources[target] = source_sha - prior = retained / target - receipt = check_snapshot(prior) if prior.exists() else None - if ( - target != "main" - and receipt is not None - and receipt["source_sha"] != source_sha - ): + sources, eligible_tags = _targets(repo, controller, tag, retained) + for target, source in supplied.items(): + # A downstream retry can find main already bootstrapped, possibly + # by a newer publication. Validate this unused proposal but do + # not replace the currently retained main with it. + expected_source = sources.get(target) + if target == "main" and expected_source is None and tag != "main": + expected_source = controller + if expected_source != source: raise ValueError( - f"Retained {target} conflicts with the current tag" - ) - reuse = receipt is not None and ( - target != "main" - or ( - receipt["source_sha"] == source_sha - and receipt["controller_sha"] == controller + f"Snapshot bundle has unexpected source: {target}" ) + _check_render( + snapshots / target, repo, target, source, controller ) - if reuse: - # Retained main also permits deployment recovery without - # rendering again, but a new controller must rebuild it. + for target, source in sources.items(): + prior = retained / target + if _reuse(prior, target, source, controller): snapshot = prior + elif target in supplied: + snapshot = snapshots / target else: - snapshot = work / f"build-{target}" - docs_build( - ref=controller if target == "main" else target, - output=snapshot, - repo=repo, + raise ValueError( + f"Snapshot bundle is missing required {target}" ) assemble( retained, @@ -195,8 +376,7 @@ def prepare( repo, older, newer ), ) - if not targets: - # Empty reconciliation refreshes generated aliases/catalog. + if not sources: assemble( retained, retained / "main", @@ -205,8 +385,6 @@ def prepare( repo, older, newer ), ) - # Release state can change during a render. Do not publish a decision - # made before a release was withdrawn or promoted; retry instead. if eligible_tags != { r["tag_name"] for r in releases() if eligible(r) }: @@ -231,7 +409,9 @@ def prepare( ) # Tags can move independently of Release eligibility. Re-read them # after rendering and before pushing or deploying retained output. - for release_tag, source_sha in release_sources.items(): + for release_tag, source_sha in sources.items(): + if release_tag == "main": + continue if remote_tag_commit(release_tag) != source_sha: raise ValueError( f"Release tag moved during publication: {release_tag}" @@ -265,14 +445,25 @@ def prepare( def main() -> int: parser = argparse.ArgumentParser(description=__doc__) subcommands = parser.add_subparsers(dest="command", required=True) - command = subcommands.add_parser("prepare") - command.add_argument("--tag", default="main") - command.add_argument("--request-id", default="") - command.add_argument("--output", required=True, type=Path) + for name in ("render", "prepare"): + command = subcommands.add_parser(name) + command.add_argument("--tag", default="main") + command.add_argument("--request-id", default="") + command.add_argument("--output", required=True, type=Path) + if name == "prepare": + command.add_argument("--snapshots", required=True, type=Path) args = parser.parse_args() - result = prepare( - tag=args.tag, request_id=args.request_id, output=args.output - ) + if args.command == "render": + result = render_bundle( + tag=args.tag, request_id=args.request_id, output=args.output + ) + else: + result = prepare( + tag=args.tag, + request_id=args.request_id, + snapshots=args.snapshots, + output=args.output, + ) print(json.dumps(result, sort_keys=True)) return 0 diff --git a/dev/tests/test_artifacts.py b/dev/tests/test_artifacts.py new file mode 100644 index 00000000..63dc9299 --- /dev/null +++ b/dev/tests/test_artifacts.py @@ -0,0 +1,234 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import hashlib +import io +import os +import stat +import sys +import warnings +import zipfile +from types import SimpleNamespace + +import pytest + +from cuphoton_dev import artifacts + + +def zipped(entries): + output = io.BytesIO() + with warnings.catch_warnings(): + warnings.simplefilter("ignore", UserWarning) + with zipfile.ZipFile(output, "w") as package: + for entry, content in entries: + package.writestr(entry, content) + return output.getvalue() + + +@pytest.fixture +def transfer(tmp_path, monkeypatch): + sha = "a" * 40 + run_id = 123 + for key, value in { + "GITHUB_REPOSITORY": "NVIDIA/cuPhoton", + "GITHUB_RUN_ID": str(run_id), + "GITHUB_RUN_ATTEMPT": "2", + "GITHUB_SHA": sha, + }.items(): + monkeypatch.setenv(key, value) + run = { + "id": run_id, + "path": ".github/workflows/docs.yml", + "event": "workflow_dispatch", + "head_branch": "main", + "head_sha": sha, + "repository": {"full_name": "NVIDIA/cuPhoton"}, + "head_repository": {"full_name": "NVIDIA/cuPhoton"}, + } + artifact = { + "id": 456, + "name": "docs-snapshots-123-1", + "expired": False, + "workflow_run": {"id": run_id, "head_sha": sha}, + } + payload = tmp_path / "response.zip" + + def set_payload(content): + payload.write_bytes(content) + digest = hashlib.sha256(content).hexdigest() + artifact["digest"] = "sha256:" + digest + return digest + + digest = set_payload( + zipped( + [ + ("manifest.json", b"{}"), + ("main/", b""), + ("main/index.html", b"verified snapshot"), + ] + ) + ) + calls = [] + + def api(path): + calls.append(path) + if path == "repos/NVIDIA/cuPhoton/actions/runs/123": + return run + assert path == "repos/NVIDIA/cuPhoton/actions/artifacts/456" + return artifact + + monkeypatch.setattr(artifacts, "api", api) + tools = tmp_path / "tools" + tools.mkdir() + downloaded = tmp_path / "downloaded" + gh = tools / "gh" + gh.write_text( + f"#!{sys.executable}\nimport sys\nfrom pathlib import Path\n" + "assert sys.argv[-1] == " + "'repos/NVIDIA/cuPhoton/actions/artifacts/456/zip'\n" + f"Path({str(downloaded)!r}).touch()\n" + f"sys.stdout.buffer.write(Path({str(payload)!r}).read_bytes())\n", + encoding="utf-8", + ) + gh.chmod(0o755) + monkeypatch.setenv("PATH", str(tools) + os.pathsep + os.environ["PATH"]) + return SimpleNamespace( + run=run, + artifact=artifact, + payload=payload, + digest=digest, + output=tmp_path / "snapshot", + downloaded=downloaded, + set_payload=set_payload, + calls=calls, + ) + + +def test_prior_producer_attempt_downloads_verified_bytes( + transfer, monkeypatch, capsys +): + monkeypatch.setattr( + sys, + "argv", + [ + "artifacts", + "download", + "--artifact-id", + "456", + "--digest", + transfer.digest, + "--output", + str(transfer.output), + ], + ) + assert artifacts.main() == 0 + assert ( + transfer.output / "main/index.html" + ).read_bytes() == b"verified snapshot" + assert transfer.downloaded.exists() + assert transfer.digest in capsys.readouterr().out + assert len(transfer.calls) == 2 + + +@pytest.mark.parametrize( + "field,value", + [ + ("run", 789), + ("head", "b" * 40), + ("digest", "sha256:" + "0" * 64), + ("expired", True), + ("attempt", "docs-snapshots-123-3"), + ("name", "docs-snapshots-789-1"), + ], +) +def test_rejects_other_or_unverified_artifact_before_download( + transfer, field, value +): + if field == "run": + transfer.artifact["workflow_run"]["id"] = value + elif field == "head": + transfer.artifact["workflow_run"]["head_sha"] = value + else: + transfer.artifact[ + "name" if field in {"attempt", "name"} else field + ] = value + with pytest.raises(ValueError, match="identity or digest"): + artifacts.download( + artifact_id=456, digest=transfer.digest, output=transfer.output + ) + assert not transfer.downloaded.exists() + assert not transfer.output.exists() + + +@pytest.mark.parametrize( + "field,value", + [ + ("path", ".github/workflows/docs-preview.yml"), + ("event", "pull_request"), + ("head_branch", "topic"), + ("head_sha", "b" * 40), + ("repository", {"full_name": "fork/cuPhoton"}), + ], +) +def test_rejects_nonpublisher_run(transfer, field, value): + transfer.run[field] = value + with pytest.raises(ValueError, match="canonical main docs workflow"): + artifacts.download( + artifact_id=456, digest=transfer.digest, output=transfer.output + ) + assert not transfer.downloaded.exists() + assert not transfer.output.exists() + + +def test_rejects_changed_download_bytes_without_exposing_output(transfer): + transfer.payload.write_bytes( + zipped([("main/index.html", b"substituted")]) + ) + with pytest.raises(ValueError, match="SHA256 mismatch"): + artifacts.download( + artifact_id=456, digest=transfer.digest, output=transfer.output + ) + assert transfer.downloaded.exists() + assert not transfer.output.exists() + assert not list(transfer.output.parent.glob(".docs-artifact-*")) + + +@pytest.mark.parametrize( + "unsafe", ["traversal", "absolute", "symlink", "duplicate", "git"] +) +def test_rejects_unsafe_zip_with_matching_digest(transfer, unsafe): + if unsafe == "symlink": + entry = zipfile.ZipInfo("link") + entry.create_system = 3 + entry.external_attr = (stat.S_IFLNK | 0o777) << 16 + entries = [(entry, b"../escaped")] + elif unsafe == "duplicate": + entries = [ + ("main/index.html", b"first"), + ("main/index.html", b"second"), + ] + elif unsafe == "git": + entries = [ + ("main/.git/config", b"[core]\nrepositoryformatversion=0\n") + ] + else: + name = ( + "../escaped" + if unsafe == "traversal" + else str(transfer.output.parent / "escaped") + ) + entries = [(name, b"escaped")] + # A preceding good entry exercises cleanup after extraction has begun. + digest = transfer.set_payload( + zipped([("manifest.json", b"{}"), *entries]) + ) + with pytest.raises(ValueError, match="Unsafe snapshot artifact entry"): + artifacts.download( + artifact_id=456, digest=digest, output=transfer.output + ) + assert not transfer.output.exists() + assert not (transfer.output.parent / "escaped").exists() + assert not list(transfer.output.parent.glob(".docs-artifact-*")) diff --git a/dev/tests/test_prepare.py b/dev/tests/test_prepare.py index 7fedf94f..3b9f02ff 100644 --- a/dev/tests/test_prepare.py +++ b/dev/tests/test_prepare.py @@ -6,6 +6,9 @@ from __future__ import annotations +import hashlib +import json +import shutil import subprocess from types import SimpleNamespace @@ -33,10 +36,19 @@ def publication(tmp_path, monkeypatch): git(source, "config", "user.email", "test@example.com") git(source, "config", "commit.gpgsign", "false") (source / "source.txt").write_text("first source\n") + (source / "uv.lock").write_text("# exact lock bytes\n", encoding="utf-8") + workflow = source / ".github/workflows/docs.yml" + workflow.parent.mkdir(parents=True) + workflow.write_text( + "url: https://github.com/quarto-dev/quarto-cli/releases/download/" + "v1.9.36/quarto-1.9.36-linux-amd64.deb\n", + encoding="utf-8", + ) git(source, "add", ".") git(source, "commit", "-qm", "first source") sha = git(source, "rev-parse", "HEAD") git(source, "tag", "v0.2.0") + git(source, "update-ref", "refs/remotes/origin/main", sha) remote = tmp_path / "remote.git" remote.mkdir() git(remote, "init", "-q", "--bare") @@ -68,11 +80,17 @@ def build(*, ref, output, repo): rendered_guide(output) return postprocess( output, - version=ref if ref.startswith("v") else "main", + version=ref.removeprefix("refs/tags/") + if ref.startswith("refs/tags/") + else "main", source_sha=publisher.resolve(repo, ref), controller_sha=publisher.resolve(source, "HEAD"), renderer="1.9.36", - lock_sha256="c" * 64, + lock_sha256=hashlib.sha256( + subprocess.check_output( + ["git", "-C", str(repo), "show", f"{ref}:uv.lock"] + ) + ).hexdigest(), ) monkeypatch.chdir(source) @@ -80,6 +98,8 @@ def build(*, ref, output, repo): monkeypatch.setenv("GITHUB_REF", "refs/heads/main") monkeypatch.setenv("GITHUB_EVENT_NAME", "workflow_dispatch") monkeypatch.setenv("GITHUB_SHA", sha) + monkeypatch.setenv("GITHUB_RUN_ID", "123") + monkeypatch.setenv("GITHUB_RUN_ATTEMPT", "1") monkeypatch.setattr(publisher, "clone_archive", clone) monkeypatch.setattr(publisher, "docs_build", build) monkeypatch.setattr(publisher, "releases", lambda: [release()]) @@ -99,11 +119,19 @@ def build(*, ref, output, repo): ) +def publish(*, tag, output, request_id=""): + bundle = output.with_name(output.name + "-bundle") + publisher.render_bundle(tag=tag, output=bundle, request_id=request_id) + return publisher.prepare( + tag=tag, snapshots=bundle, output=output, request_id=request_id + ) + + def test_prepare_retries_retained_main_after_deployment_failure( publication, monkeypatch ): first = publication.root / "first" - result = publisher.prepare(tag="main", output=first) + result = publish(tag="main", output=first) assert result["catalog"]["preferred"] == "main" hashes = file_hashes(first) assert len(publication.builds) == 1 @@ -113,7 +141,7 @@ def test_prepare_retries_retained_main_after_deployment_failure( publisher, "docs_build", lambda **kwargs: pytest.fail("must reuse") ) retry = publication.root / "retry" - recovered = publisher.prepare(tag="main", output=retry) + recovered = publish(tag="main", output=retry) assert recovered["archive_sha"] == result["archive_sha"] assert file_hashes(retry) == hashes assert not (retry / ".git").exists() @@ -123,20 +151,19 @@ def test_prepare_duplicate_release_and_next_main_preserve_history( publication, monkeypatch ): first = publication.root / "first" - original = publisher.prepare(tag="v0.2.0", output=first) + original = publish(tag="v0.2.0", output=first) release_hashes = file_hashes(first / "v0.2.0") assert len(publication.builds) == 2 # Bootstrap main and the release. - duplicate = publisher.prepare( - tag="v0.2.0", output=publication.root / "duplicate" - ) + duplicate = publish(tag="v0.2.0", output=publication.root / "duplicate") assert duplicate["archive_sha"] == original["archive_sha"] assert len(publication.builds) == 2 (publication.source / "source.txt").write_text("next source\n") git(publication.source, "commit", "-qam", "next source") sha = git(publication.source, "rev-parse", "HEAD") monkeypatch.setenv("GITHUB_SHA", sha) + git(publication.source, "update-ref", "refs/remotes/origin/main", sha) updated = publication.root / "updated" - publisher.prepare(tag="main", output=updated) + publish(tag="main", output=updated) assert len(publication.builds) == 3 assert file_hashes(updated / "v0.2.0") == release_hashes assert publisher.docs_check(updated)["stable"] == "v0.2.0" @@ -144,15 +171,16 @@ def test_prepare_duplicate_release_and_next_main_preserve_history( def test_prepare_rejects_moved_tag_without_pushing(publication, monkeypatch): first = publication.root / "first" - original = publisher.prepare(tag="v0.2.0", output=first) + original = publish(tag="v0.2.0", output=first) (publication.source / "source.txt").write_text("different source\n") git(publication.source, "commit", "-qam", "different source") sha = git(publication.source, "rev-parse", "HEAD") monkeypatch.setenv("GITHUB_SHA", sha) git(publication.source, "tag", "-f", "v0.2.0") + git(publication.source, "update-ref", "refs/remotes/origin/main", sha) output = publication.root / "rejected" with pytest.raises(ValueError, match="conflicts with the current tag"): - publisher.prepare(tag="v0.2.0", output=output) + publish(tag="v0.2.0", output=output) assert not output.exists() assert ( git(publication.remote, "rev-parse", "gh-pages") @@ -164,9 +192,7 @@ def test_prepare_rejects_moved_tag_without_pushing(publication, monkeypatch): def test_prepare_failure_does_not_change_retained_site( publication, monkeypatch, failure ): - original = publisher.prepare( - tag="main", output=publication.root / "first" - ) + original = publish(tag="main", output=publication.root / "first") if failure == "build": def broken_build(**kwargs): @@ -174,7 +200,7 @@ def broken_build(**kwargs): monkeypatch.setattr(publisher, "docs_build", broken_build) elif failure == "eligibility": - records = iter([[release()], [release(draft=True)]]) + records = iter([[release()], [release()], [release(draft=True)]]) monkeypatch.setattr(publisher, "releases", lambda: next(records)) else: real_git = publisher.git @@ -187,7 +213,7 @@ def broken_push(repo, *args): monkeypatch.setattr(publisher, "git", broken_push) output = publication.root / "failed" with pytest.raises(RuntimeError): - publisher.prepare(tag="v0.2.0", output=output) + publish(tag="v0.2.0", output=output) assert not output.exists() assert ( git(publication.remote, "rev-parse", "gh-pages") @@ -231,7 +257,7 @@ def local_remote(args): def test_remote_tag_change_during_render_cannot_publish( publication, monkeypatch, remote_change ): - initial = publisher.prepare(tag="main", output=publication.root / "first") + initial = publish(tag="main", output=publication.root / "first") real_build = publisher.docs_build remote_sha = publication.sha @@ -250,7 +276,7 @@ def current_remote_tag(tag): monkeypatch.setattr(publisher, "remote_tag_commit", current_remote_tag) output = publication.root / "rejected-remote" with pytest.raises(ValueError, match="moved|missing"): - publisher.prepare(tag="v0.2.0", output=output) + publish(tag="v0.2.0", output=output) assert not output.exists() assert ( git(publication.remote, "rev-parse", "gh-pages") @@ -268,8 +294,8 @@ def test_prepare_missing_skips_releases_without_a_guide( ) monkeypatch.setattr(publisher, "has_guide", lambda tag: tag == "v0.2.0") output = publication.root / "backfill" - result = publisher.prepare(tag="missing", output=output) - assert publication.builds == [publication.sha, "v0.2.0"] + result = publish(tag="missing", output=output) + assert publication.builds == [publication.sha, "refs/tags/v0.2.0"] assert {entry["version"] for entry in result["catalog"]["versions"]} == { "main", "v0.2.0", @@ -283,7 +309,7 @@ def test_prepare_empty_backfill_refreshes_withdrawn_release( publication, monkeypatch ): first = publication.root / "first" - initial = publisher.prepare(tag="v0.2.0", output=first) + initial = publish(tag="v0.2.0", output=first) assert initial["catalog"]["stable"] == "v0.2.0" retained_hashes = { version: file_hashes(first / version) @@ -297,7 +323,7 @@ def test_prepare_empty_backfill_refreshes_withdrawn_release( publisher, "docs_build", lambda **kwargs: pytest.fail("must retain") ) refreshed = publication.root / "refreshed" - result = publisher.prepare(tag="missing", output=refreshed) + result = publish(tag="missing", output=refreshed) assert result["catalog"]["stable"] is None assert result["catalog"]["preferred"] == "main" entries = {e["version"]: e for e in result["catalog"]["versions"]} @@ -308,3 +334,258 @@ def test_prepare_empty_backfill_refreshes_withdrawn_release( assert (refreshed / "v0.2.0/build.json").read_bytes() == release_receipt assert result["archive_sha"] != initial["archive_sha"] assert publisher.docs_check(refreshed)["stable"] is None + + +def test_writer_never_renders_and_retries_earlier_attempt( + publication, monkeypatch +): + bundle = publication.root / "bundle" + publisher.render_bundle(tag="v0.2.0", output=bundle, request_id="request") + assert not git(publication.remote, "for-each-ref", "refs/heads/gh-pages") + monkeypatch.setattr( + publisher, + "docs_build", + lambda **kwargs: pytest.fail("writer cannot render"), + ) + first = publisher.prepare( + tag="v0.2.0", + snapshots=bundle, + output=publication.root / "first", + request_id="request", + ) + monkeypatch.setenv("GITHUB_RUN_ATTEMPT", "2") + recovered = publisher.prepare( + tag="v0.2.0", + snapshots=bundle, + output=publication.root / "recovered", + request_id="request", + ) + assert recovered["archive_sha"] == first["archive_sha"] + assert file_hashes(publication.root / "first") == file_hashes( + publication.root / "recovered" + ) + duplicate = publisher.render_bundle( + tag="v0.2.0", output=publication.root / "duplicate" + ) + assert duplicate["snapshots"] == {} + assert {p.name for p in (publication.root / "duplicate").iterdir()} == { + "manifest.json" + } + + +@pytest.mark.parametrize( + "key,value", + [ + ("repository", "other/cuPhoton"), + ("controller_sha", "f" * 40), + ("run_id", "999"), + ("run_attempt", 0), + ("run_attempt", 2), + ("run_attempt", True), + ("tag", "v0.2.0"), + ("request_id", "other"), + ], +) +def test_writer_rejects_bundle_from_another_publication( + publication, key, value +): + bundle = publication.root / "bundle" + publisher.render_bundle(tag="main", output=bundle) + path = bundle / "manifest.json" + manifest = json.loads(path.read_text()) + manifest[key] = value + path.write_text(json.dumps(manifest)) + with pytest.raises(ValueError, match="unexpected " + key): + publisher.prepare( + tag="main", snapshots=bundle, output=publication.root / "site" + ) + assert not git(publication.remote, "for-each-ref", "refs/heads/gh-pages") + + +@pytest.mark.parametrize( + "key,value", + [ + ("source_sha", "f" * 40), + ("controller_sha", "f" * 40), + ("lock_sha256", "f" * 64), + ("renderer", "1.0.0"), + ], +) +def test_writer_rejects_self_consistent_but_wrong_receipt( + publication, key, value +): + bundle = publication.root / "bundle" + publisher.render_bundle(tag="main", output=bundle) + path = bundle / "main/build.json" + receipt = json.loads(path.read_text()) + receipt[key] = value + path.write_text(json.dumps(receipt)) + # Receipt fields are outside the file hashes, but must still match the + # independently resolved target rather than trusting the producer. + publisher.docs_check(bundle / "main") + with pytest.raises(ValueError, match="unexpected " + key): + publisher.prepare( + tag="main", snapshots=bundle, output=publication.root / "site" + ) + assert not git(publication.remote, "for-each-ref", "refs/heads/gh-pages") + + +@pytest.mark.parametrize( + "failure", ["missing", "inventory", "hash", "source"] +) +def test_writer_refuses_incomplete_or_changed_bundle(publication, failure): + bundle = publication.root / "bundle" + publisher.render_bundle(tag="main", output=bundle) + if failure in {"missing", "source"}: + path = bundle / "manifest.json" + manifest = json.loads(path.read_text()) + if failure == "missing": + shutil.rmtree(bundle / "main") + manifest["snapshots"] = {} + else: + manifest["snapshots"]["main"] = "f" * 40 + path.write_text(json.dumps(manifest)) + elif failure == "inventory": + (bundle / "extra.txt").write_text("unexpected") + else: + (bundle / "main/index.html").write_text("changed") + with pytest.raises( + ValueError, + match="missing required|inventory|hashes|unexpected source", + ): + publisher.prepare( + tag="main", snapshots=bundle, output=publication.root / "site" + ) + assert not git(publication.remote, "for-each-ref", "refs/heads/gh-pages") + + +@pytest.mark.parametrize("phase", ["render", "prepare"]) +def test_publication_rejects_release_outside_supported_branches( + publication, phase +): + bundle = publication.root / "bundle" + if phase == "prepare": + publisher.render_bundle(tag="v0.2.0", output=bundle) + # A real unrelated commit exists, but none of the supported origin refs + # contains the tagged source any longer. + tree = git(publication.source, "rev-parse", "HEAD^{tree}") + unrelated = subprocess.check_output( + ["git", "-C", str(publication.source), "commit-tree", tree], + input="unrelated root\n", + text=True, + ).strip() + git( + publication.source, + "update-ref", + "refs/remotes/origin/main", + unrelated, + ) + with pytest.raises( + ValueError, match="must belong to main, 0.1.x or 0.2.x" + ): + if phase == "render": + publisher.render_bundle(tag="v0.2.0", output=bundle) + else: + publisher.prepare( + tag="v0.2.0", + snapshots=bundle, + output=publication.root / "site", + ) + assert not git(publication.remote, "for-each-ref", "refs/heads/gh-pages") + + +@pytest.mark.parametrize("branch", ["0.1.x", "0.2.x"]) +def test_publication_accepts_supported_release_branch(publication, branch): + git(publication.source, "update-ref", "-d", "refs/remotes/origin/main") + git( + publication.source, + "update-ref", + f"refs/remotes/origin/{branch}", + publication.sha, + ) + result = publish(tag="v0.2.0", output=publication.root / "site") + assert result["catalog"]["stable"] == "v0.2.0" + + +@pytest.mark.parametrize("phase", ["render", "prepare"]) +def test_both_phases_require_canonical_main(publication, monkeypatch, phase): + monkeypatch.setenv("GITHUB_REF", "refs/tags/v0.2.0") + with pytest.raises(ValueError, match="canonical main"): + if phase == "render": + publisher.render_bundle( + tag="main", output=publication.root / "bundle" + ) + else: + publisher.prepare( + tag="main", + snapshots=publication.root / "bundle", + output=publication.root / "site", + ) + assert not publication.builds + assert not git(publication.remote, "for-each-ref", "refs/heads/gh-pages") + + +def test_similarly_named_branch_does_not_authorize_release(publication): + git(publication.source, "update-ref", "-d", "refs/remotes/origin/main") + git( + publication.source, + "update-ref", + "refs/remotes/origin/main/topic", + publication.sha, + ) + with pytest.raises( + ValueError, match="must belong to main, 0.1.x or 0.2.x" + ): + publisher.render_bundle( + tag="v0.2.0", output=publication.root / "bundle" + ) + + +def test_retry_ignores_obsolete_bootstrap_main(publication, monkeypatch): + old_controller = publication.sha + old_bundle = publication.root / "old-bundle" + publisher.render_bundle(tag="v0.2.0", output=old_bundle) + (publication.source / "source.txt").write_text("new main\n") + git(publication.source, "commit", "-qam", "new main") + new_controller = git(publication.source, "rev-parse", "HEAD") + git( + publication.source, + "update-ref", + "refs/remotes/origin/main", + new_controller, + ) + monkeypatch.setenv("GITHUB_SHA", new_controller) + current = publication.root / "current" + publish(tag="main", output=current) + hashes = file_hashes(current / "main") + git(publication.source, "checkout", "--detach", old_controller) + monkeypatch.setenv("GITHUB_SHA", old_controller) + monkeypatch.setenv("GITHUB_RUN_ATTEMPT", "2") + site = publication.root / "retry" + publisher.prepare(tag="v0.2.0", snapshots=old_bundle, output=site) + assert file_hashes(site / "main") == hashes + assert publisher.docs_check(site)["stable"] == "v0.2.0" + + +def test_writer_checks_release_lock_from_tag_not_controller( + publication, monkeypatch +): + tag_lock = (publication.source / "uv.lock").read_bytes() + (publication.source / "uv.lock").write_text("# updated controller lock\n") + git(publication.source, "commit", "-qam", "update lock") + controller = git(publication.source, "rev-parse", "HEAD") + git( + publication.source, + "update-ref", + "refs/remotes/origin/main", + controller, + ) + monkeypatch.setenv("GITHUB_SHA", controller) + site = publication.root / "site" + publish(tag="v0.2.0", output=site) + receipt = publisher.docs_check(site / "v0.2.0") + main = publisher.docs_check(site / "main") + assert receipt["lock_sha256"] == hashlib.sha256(tag_lock).hexdigest() + assert receipt["lock_sha256"] != main["lock_sha256"] + assert receipt["source_sha"] == publication.sha + assert receipt["controller_sha"] == controller diff --git a/dev/tests/test_publisher.py b/dev/tests/test_publisher.py index d3456fee..ed658c96 100644 --- a/dev/tests/test_publisher.py +++ b/dev/tests/test_publisher.py @@ -213,7 +213,11 @@ def test_prepare_rejects_tag_workflow(monkeypatch, tmp_path): monkeypatch.setenv("GITHUB_REF", "refs/tags/v0.2.0") monkeypatch.setenv("GITHUB_EVENT_NAME", "release") with pytest.raises(ValueError, match="canonical main"): - publisher.prepare(tag="v0.2.0", output=tmp_path / "site") + publisher.prepare( + tag="v0.2.0", + snapshots=tmp_path / "bundle", + output=tmp_path / "site", + ) def test_build_failure_preserves_existing_output(tmp_path): diff --git a/dev/uv.lock b/dev/uv.lock index dd124afb..8736ddb6 100644 --- a/dev/uv.lock +++ b/dev/uv.lock @@ -156,6 +156,7 @@ requires-dist = [ { name = "cuda-toolkit", extras = ["cufile"], marker = "sys_platform == 'linux' and extra == 'io'", specifier = ">=13,<14" }, { name = "cuphoton", extras = ["io", "photometry"], marker = "extra == 'gpu'" }, { name = "cuphoton", extras = ["photometry", "torch"], marker = "extra == 'ximage'" }, + { name = "cuphoton", extras = ["xlens-inference"], marker = "extra == 'xlens-nooa'" }, { name = "cupy-cuda13x", extras = ["ctk"], marker = "sys_platform == 'linux' and extra == 'cutile'", specifier = ">=14,<15" }, { name = "cupy-cuda13x", extras = ["ctk"], marker = "sys_platform == 'linux' and extra == 'io'", specifier = ">=14,<15" }, { name = "dragonhpc", marker = "extra == 'dragon'", specifier = ">=0.14.2,<0.15" }, @@ -169,6 +170,7 @@ requires-dist = [ { name = "lsst-images", extras = ["https"], marker = "extra == 'rubin'", specifier = "==30.0.10" }, { name = "mpi4py", marker = "extra == 'mpi'", specifier = ">=4.1.2,<5" }, { name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" }, + { name = "nooa", marker = "python_full_version < '3.14' and sys_platform == 'linux' and extra == 'xlens-nooa'", specifier = "==0.0.12" }, { name = "numexpr", marker = "extra == 'catalog'", specifier = ">=2.10" }, { name = "numpy", specifier = ">=2.0,<2.6" }, { name = "nvidia-libnvcomp-cu13", marker = "sys_platform == 'linux' and extra == 'io'", specifier = "==5.2.*" }, @@ -192,7 +194,7 @@ requires-dist = [ { name = "virtualenv", marker = "extra == 'dev'", specifier = ">=21.15.4" }, { name = "zarr", marker = "extra == 'ximage'", specifier = ">=3,<4" }, ] -provides-extras = ["catalog", "ximage", "rubin", "xlens-inference", "photometry", "torch", "viz", "io", "gpu", "cutile", "mpi", "dragon", "dev"] +provides-extras = ["catalog", "ximage", "rubin", "xlens-inference", "xlens-nooa", "photometry", "torch", "viz", "io", "gpu", "cutile", "mpi", "dragon", "dev"] [package.metadata.requires-dev] docs = [ diff --git a/dev/workflow-lint/check.mjs b/dev/workflow-lint/check.mjs new file mode 100644 index 00000000..9dc10476 --- /dev/null +++ b/dev/workflow-lint/check.mjs @@ -0,0 +1,72 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +import { readdirSync, readFileSync } from "node:fs"; +import { register } from "node:module"; +import { fileURLToPath } from "node:url"; + +register(new URL("./json-loader.mjs", import.meta.url)); +const { + convertWorkflowTemplate, + isMapping, + NoOperationTraceWriter, + parseWorkflow, +} = await import("@actions/workflow-parser"); + +const directory = fileURLToPath( + new URL("../../.github/workflows/", import.meta.url), +); +const files = process.argv.length > 2 + ? process.argv.slice(2) + : readdirSync(directory) + .filter((name) => /\.ya?ml$/.test(name)) + .sort() + .map((name) => `${directory}/${name}`); + +if (files.length === 0) { + throw new Error("No GitHub Actions workflows found"); +} + +let failures = 0; +for (const file of files) { + try { + const result = parseWorkflow( + { name: file, content: readFileSync(file, "utf8") }, + new NoOperationTraceWriter(), + ); + if (result.value) { + const workflow = await convertWorkflowTemplate( + result.context, result.value, + ); + // The published schema accepts these values independently; GitHub + // also rejects this combination for workflow and job concurrency. + const groups = [ + workflow.concurrency, + ...(workflow.jobs ?? []).map((job) => job.concurrency), + ]; + for (const group of groups) { + if ( + isMapping(group) && group.find("queue")?.value === "max" && + group.find("cancel-in-progress")?.value === true + ) { + result.context.error( + group, + "queue: max cannot be combined with cancel-in-progress: true", + ); + } + } + } + const errors = result.context.errors.getErrors(); + for (const error of errors) { + console.error(error.message); + } + failures += errors.length; + } catch (error) { + console.error(`${file}: ${error.message}`); + failures += 1; + } +} + +console.log(`Validated ${files.length} workflow files; ${failures} errors.`); +process.exitCode = failures ? 1 : 0; diff --git a/dev/workflow-lint/json-loader.mjs b/dev/workflow-lint/json-loader.mjs new file mode 100644 index 00000000..49db259c --- /dev/null +++ b/dev/workflow-lint/json-loader.mjs @@ -0,0 +1,11 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// +// SPDX-License-Identifier: Apache-2.0 + +// The parser's published ESM omits Node's required JSON import attribute. +export async function load(url, context, nextLoad) { + if (url.endsWith("/@actions/workflow-parser/dist/workflow-v1.0.min.json")) { + context = { ...context, importAttributes: { type: "json" } }; + } + return nextLoad(url, context); +} diff --git a/dev/workflow-lint/package-lock.json b/dev/workflow-lint/package-lock.json new file mode 100644 index 00000000..1f72482a --- /dev/null +++ b/dev/workflow-lint/package-lock.json @@ -0,0 +1,64 @@ +{ + "name": "cuphoton-workflow-lint", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "cuphoton-workflow-lint", + "license": "Apache-2.0", + "dependencies": { + "@actions/workflow-parser": "0.3.61" + }, + "engines": { + "node": ">=20.10.0" + } + }, + "node_modules/@actions/expressions": { + "version": "0.3.61", + "resolved": "https://registry.npmjs.org/@actions/expressions/-/expressions-0.3.61.tgz", + "integrity": "sha512-Ig+tXELvTjlqxQAWBQnLNn2dPpNraLMdSnT+vDzDPmJtbNUhIAH/Z9kVT8pZ8UtJi9vUGs8hwHE8JFJmbOnLEA==", + "license": "MIT", + "engines": { + "node": ">= 20" + } + }, + "node_modules/@actions/workflow-parser": { + "version": "0.3.61", + "resolved": "https://registry.npmjs.org/@actions/workflow-parser/-/workflow-parser-0.3.61.tgz", + "integrity": "sha512-NBjJrbwwrEN3LSN0NAISLpCWQLcPSBjmAIkLXHgjGX8Yql4PiD33ifSAvr9sIMU9uIs8wZiGUnvo9yPIMIfKdg==", + "license": "MIT", + "dependencies": { + "@actions/expressions": "^0.3.61", + "cronstrue": "^2.21.0", + "yaml": "^2.0.0-8" + }, + "engines": { + "node": ">= 20" + } + }, + "node_modules/cronstrue": { + "version": "2.59.0", + "resolved": "https://registry.npmjs.org/cronstrue/-/cronstrue-2.59.0.tgz", + "integrity": "sha512-YKGmAy84hKH+hHIIER07VCAHf9u0Ldelx1uU6EBxsRPDXIA1m5fsKmJfyC3xBhw6cVC/1i83VdbL4PvepTrt8A==", + "license": "MIT", + "bin": { + "cronstrue": "bin/cli.js" + } + }, + "node_modules/yaml": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz", + "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==", + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + }, + "funding": { + "url": "https://github.com/sponsors/eemeli" + } + } + } +} diff --git a/dev/workflow-lint/package.json b/dev/workflow-lint/package.json new file mode 100644 index 00000000..ac42c53c --- /dev/null +++ b/dev/workflow-lint/package.json @@ -0,0 +1,15 @@ +{ + "name": "cuphoton-workflow-lint", + "private": true, + "type": "module", + "license": "Apache-2.0", + "engines": { + "node": ">=20.10.0" + }, + "scripts": { + "check": "node check.mjs" + }, + "dependencies": { + "@actions/workflow-parser": "0.3.61" + } +} From 7609b874e34bbc8a8baf023aee69d2828fc1e9aa Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Thu, 12 Nov 2026 15:47:48 -0800 Subject: [PATCH 9/9] Isolate publication fixtures from global tag signing Disable tag signing in temporary test repositories so contributor signing preferences cannot prompt for keys during publication tests. Signed-off-by: Trent Nelson --- dev/tests/test_prepare.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/dev/tests/test_prepare.py b/dev/tests/test_prepare.py index 3b9f02ff..685a9b63 100644 --- a/dev/tests/test_prepare.py +++ b/dev/tests/test_prepare.py @@ -35,6 +35,7 @@ def publication(tmp_path, monkeypatch): git(source, "config", "user.name", "Test") git(source, "config", "user.email", "test@example.com") git(source, "config", "commit.gpgsign", "false") + git(source, "config", "tag.gpgsign", "false") (source / "source.txt").write_text("first source\n") (source / "uv.lock").write_text("# exact lock bytes\n", encoding="utf-8") workflow = source / ".github/workflows/docs.yml" @@ -229,6 +230,7 @@ def test_remote_tag_commit_prefers_peeled_annotated_target( git(tmp_path, "config", "user.name", "Test") git(tmp_path, "config", "user.email", "test@example.com") git(tmp_path, "config", "commit.gpgsign", "false") + git(tmp_path, "config", "tag.gpgsign", "false") (tmp_path / "source.txt").write_text("release source\n") git(tmp_path, "add", ".") git(tmp_path, "commit", "-qm", "release source")