fastapi-router-lazy 0.1.0__tar.gz

fastapi_router_lazy-0.1.0/.github/actions/ensure-pages-published/action.yml

@@ -0,0 +1,78 @@
+name: Ensure Pages published
+description: >-
+  Wait for GitHub's auto "pages build and deployment" of the current gh-pages
+  HEAD and rerun it (with backoff) if it fails with a transient error.
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      env:
+        GH_TOKEN: ${{ github.token }}
+        REPO: ${{ github.repository }}
+        ATTEMPTS: "5"
+      run: |
+        set -euo pipefail
+
+        target_sha="$(gh api "repos/$REPO/branches/gh-pages" --jq '.commit.sha')"
+        echo "Ensuring Pages is published for gh-pages@$target_sha"
+
+        find_run() {
+          gh run list --repo "$REPO" --workflow "pages-build-deployment" \
+            --commit "$target_sha" --limit 1 \
+            --json databaseId,status,conclusion \
+            --jq '.[0] // empty | "\(.databaseId) \(.status) \(.conclusion // "")"' 2>/dev/null || true
+        }
+
+        # Block until a run for this SHA reaches "completed"; echo "id conclusion".
+        await_completed() {
+          for _ in $(seq 1 60); do
+            local info id status conclusion
+            info="$(find_run)"
+            id="$(printf '%s' "$info" | awk '{print $1}')"
+            status="$(printf '%s' "$info" | awk '{print $2}')"
+            conclusion="$(printf '%s' "$info" | awk '{print $3}')"
+            if [ -n "$id" ] && [ "$status" = "completed" ]; then
+              printf '%s %s\n' "$id" "$conclusion"
+              return 0
+            fi
+            sleep 10
+          done
+          return 1
+        }
+
+        for attempt in $(seq 1 "$ATTEMPTS"); do
+          echo "::group::Pages publish check (attempt $attempt/$ATTEMPTS)"
+          if ! result="$(await_completed)"; then
+            echo "Timed out waiting for the pages-build-deployment run." >&2
+            echo "::endgroup::"
+            exit 1
+          fi
+          run_id="${result%% *}"
+          conclusion="${result##* }"
+          echo "pages-build-deployment run $run_id -> $conclusion"
+          echo "::endgroup::"
+
+          if [ "$conclusion" = "success" ]; then
+            echo "Pages published for gh-pages@$target_sha."
+            exit 0
+          fi
+
+          if [ "$attempt" -lt "$ATTEMPTS" ]; then
+            # Progressive backoff: transient failures are usually account-level
+            # Pages throttling under concurrent deploys — give it room to clear.
+            backoff=$((attempt * 30))
+            echo "Transient failure; waiting ${backoff}s before rerunning run $run_id…"
+            sleep "$backoff"
+            gh run rerun "$run_id" --repo "$REPO" || true
+            # Let the rerun leave the "completed" state before we poll again.
+            for _ in $(seq 1 12); do
+              status="$(find_run | awk '{print $2}')"
+              [ "$status" != "completed" ] && break
+              sleep 5
+            done
+          fi
+        done
+
+        echo "Pages deployment still failing after $ATTEMPTS attempts for gh-pages@$target_sha." >&2
+        exit 1

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

@@ -0,0 +1,280 @@
+name: ci
+on:
+  push: ~
+  pull_request: ~
+jobs:
+  ci:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    name: Python ${{ matrix.python-version }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.12", "3.13", "3.14" ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install Dependencies (core only, no variants extra)
+        run: uv sync --locked --no-dev --group test
+
+      - name: Test
+        # The wall-clock startup benchmark runs once in the dedicated
+        # `benchmark` job, without coverage, so instrumentation and the matrix
+        # do not distort its timings.
+        run: uv run --no-sync pytest -m "not benchmark" --cov=fastapi_router_lazy --cov-report=xml
+
+      - name: Codecov
+        # Core-only coverage; a single matrix leg uploads (the report is
+        # identical across versions). Combined with the variants job's upload.
+        if: matrix.python-version == '3.14'
+        uses: codecov/codecov-action@v7
+        with:
+          use_oidc: true
+          flags: core
+
+  variants:
+    # The variant/version-aware extractors live behind the optional `variants`
+    # extra. The dev group pulls fastapi-router-variants (git source, see
+    # pyproject [tool.uv.sources]) so the variant integration tests actually run.
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ubuntu-latest
+
+    name: Variants integration
+
+    permissions:
+      contents: read
+      id-token: write   # OIDC token for Codecov upload
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install (with fastapi-router-variants from git)
+        run: uv sync
+
+      - name: Test
+        run: uv run --no-sync pytest -m "not benchmark" --cov=fastapi_router_lazy --cov-report=xml
+
+      - name: Codecov
+        # Covers the variant-aware subpackage, which is skipped in the core job.
+        uses: codecov/codecov-action@v7
+        with:
+          use_oidc: true
+          flags: variants
+
+  fastapi-compat:
+    # Core lazy loading only needs plain FastAPI routing/middleware. Validate
+    # against the supported floor (0.115) up to latest.
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ubuntu-latest
+
+    name: FastAPI ${{ matrix.fastapi-version }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        fastapi-version:
+          - "0.115.0"   # floor
+          - "0.120.2"
+          - "0.129.0"
+          - "0.139.0"   # latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install (core + test deps)
+        run: uv sync --no-dev --group test
+
+      - name: Force FastAPI ${{ matrix.fastapi-version }}
+        run: uv pip install "fastapi==${{ matrix.fastapi-version }}"
+
+      - name: Test
+        run: uv run --no-sync pytest -m "not benchmark"
+
+  benchmark:
+    # Startup benchmark: fails (and fails the pipeline) if a warm cache does not
+    # defer imports and speed app startup up by at least the required factor
+    # over the default extractor. Run without coverage so instrumentation does
+    # not distort the timings.
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install (core + test deps)
+        run: uv sync --no-dev --group test
+
+      - name: Benchmark (fails if cached startup speedup < 3x)
+        run: uv run --no-sync pytest -m benchmark
+
+  pre-commit:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies (incl. fastapi-router-variants from git)
+        run: uv sync
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files --show-diff-on-failure
+
+  commitizen:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Check commit messages
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            RANGE="${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
+          elif [ "${{ github.event.before }}" = "0000000000000000000000000000000000000000" ] \
+            || ! git cat-file -e "${{ github.event.before }}^{commit}" 2>/dev/null; then
+            RANGE="HEAD~1..HEAD"
+          else
+            RANGE="${{ github.event.before }}..${{ github.event.after }}"
+          fi
+          echo "Checking commit range: ${RANGE}"
+          uv run cz check --rev-range "${RANGE}"
+
+  build:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+    needs: [ ci ]
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Git User config
+        run: |
+          git config --global user.email "action@github.com"
+          git config --global user.name "github-actions"
+
+      - name: Bump version
+        run: uvx --from python-semantic-release semantic-release version --no-commit --no-tag --no-push
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: fastapi-router-lazy-python
+          path: ./dist
+
+  release:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [ pre-commit, commitizen, build ]
+
+    runs-on: ubuntu-latest
+
+    environment: pypi
+
+    permissions:
+      contents: write   # semantic-release pushes the version bump commit + tag + GitHub release
+      id-token: write   # OIDC token for PyPI Trusted Publishing (no API token needed)
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Git User config
+        run: |
+          git config --global user.email "action@github.com"
+          git config --global user.name "github-actions"
+
+      - name: Bump version
+        run: uvx --from python-semantic-release semantic-release version
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build
+        run: uv build
+
+      - name: Upload to pypi
+        # Trusted Publishing via the job's OIDC token (see permissions above);
+        # requires a trusted publisher configured on PyPI for this repo + ci.yml.
+        run: uv publish --trusted-publishing always dist/*.tar.gz dist/*.whl
+
+      - name: Publish release
+        run: uvx --from python-semantic-release semantic-release publish
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Merge main to develop
+        uses: robotology/gh-action-nightly-merge@v1.5.2
+        with:
+          stable_branch: 'main'
+          development_branch: 'develop'
+          allow_ff: true
+          user_name: github-actions
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

fastapi_router_lazy-0.1.0/.github/workflows/zensical-develop.yml

@@ -0,0 +1,43 @@
+name: zensical-develop
+on:
+  push:
+    branches:
+      - develop
+# Per-target group: coalesce rapid develop pushes to the latest build, without
+# cancelling the main/preview deploys. Concurrent pushes to disjoint gh-pages
+# folders are handled by the deploy action's fetch+rebase+retry.
+concurrency:
+  group: gh-pages-develop
+  cancel-in-progress: true
+permissions:
+  contents: write
+  actions: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv run --only-group docs zensical build --strict
+
+      # GitHub Pages would otherwise run Jekyll on the static site; disable it.
+
+      - run: touch site/.nojekyll
+
+      - name: Deploy develop preview 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: site
+          # Publish the develop build under /dev/ without touching the stable site at the root.
+          target-folder: dev
+          clean: true
+
+      - name: Ensure Pages published (retry ×3)
+        uses: ./.github/actions/ensure-pages-published

fastapi_router_lazy-0.1.0/.github/workflows/zensical-preview.yml

@@ -0,0 +1,79 @@
+name: zensical-preview
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+# Per-PR group: a new push (or the close/cleanup) supersedes an in-flight build
+# for the same PR, without touching other PRs' or the main/develop deploys.
+# Concurrent pushes to disjoint gh-pages folders are handled by the deploy
+# action's fetch+rebase+retry.
+concurrency:
+  group: gh-pages-preview-${{ github.head_ref }}
+  cancel-in-progress: true
+permissions:
+  contents: write
+  actions: write
+jobs:
+  deploy:
+    # Same-repo docs/* PRs only: fork PRs get a read-only token and cannot push to gh-pages.
+    if: >-
+      github.event.action != 'closed'
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && startsWith(github.head_ref, 'docs/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Compute preview slug
+        id: slug
+        run: |
+          name="${GITHUB_HEAD_REF#docs/}"
+          name="$(printf '%s' "$name" | tr '/' '-' | tr -cd '[:alnum:]._-')"
+          echo "name=$name" >> "$GITHUB_OUTPUT"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv run --only-group docs zensical build --strict
+
+      # GitHub Pages would otherwise run Jekyll on the static site; disable it.
+
+      - run: touch site/.nojekyll
+
+      - name: Deploy MR preview 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: site
+          # Publish under preview/<branch-without-docs>/ without touching the rest of gh-pages.
+          target-folder: preview/${{ steps.slug.outputs.name }}
+          clean: true
+
+      - name: Ensure Pages published (retry ×3)
+        uses: ./.github/actions/ensure-pages-published
+
+  cleanup:
+    # When a docs/* PR is merged or closed, remove its preview folder.
+    if: >-
+      github.event.action == 'closed'
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && startsWith(github.head_ref, 'docs/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: gh-pages
+      - name: Remove preview folder
+        run: |
+          name="${GITHUB_HEAD_REF#docs/}"
+          name="$(printf '%s' "$name" | tr '/' '-' | tr -cd '[:alnum:]._-')"
+          if [ -d "preview/$name" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git rm -r "preview/$name"
+            git commit -m "chore(docs): remove MR preview for ${name}"
+            git push
+          else
+            echo "No preview folder preview/${name} to remove."
+          fi

fastapi_router_lazy-0.1.0/.github/workflows/zensical.yml

@@ -0,0 +1,46 @@
+name: zensical
+on:
+  push:
+    branches:
+      - main
+# Per-target group: a release deploy is never cancelled by the develop/preview
+# workflows. Concurrent pushes to disjoint gh-pages folders are handled by the
+# deploy action's fetch+rebase+retry.
+concurrency:
+  group: gh-pages-main
+  cancel-in-progress: false
+permissions:
+  contents: write
+  actions: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv run --only-group docs zensical build --strict
+
+      # GitHub Pages would otherwise run Jekyll on the static site; disable it.
+
+      - run: touch site/.nojekyll
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: site
+          clean: true
+          # Preserve the develop preview (dev/) and the docs/* MR previews (preview/)
+          # published by the zensical-develop and zensical-preview workflows.
+          clean-exclude: |
+            dev
+            preview
+
+      - name: Ensure Pages published (retry ×3)
+        uses: ./.github/actions/ensure-pages-published