ftready 1.0.0__tar.gz

ftready-1.0.0/.github/copilot-instructions.md

@@ -0,0 +1,62 @@
+# Copilot Instructions
+
+These instructions guide GitHub Copilot in understanding code style, conventions, and best practices for this repository. For executable commands, build/test workflows, and agent-specific boundaries, see the [AGENTS.md](../AGENTS.md) file in the repository root.
+
+---
+
+## Code Standards
+
+### Documentation Requirements
+
+* All documentation and code must be written in **English**.
+* Use **Sphinx-style reStructuredText (RST)** docstrings for all public classes and functions:
+
+```python
+"""Check project dependencies for free-threaded Python compatibility.
+
+:param pyproject_path: Path to the pyproject.toml file
+:param include_dev: When True, also include dev dependencies
+:return: List of compatibility results
+"""
+```
+
+* Exclude `:type`, `:raises`, and `:rtype` fields — these are inferred from type annotations.
+* For small, self-explanatory functions, use one-line docstrings.
+
+### Python Code Style
+
+* Follow **Ruff** linting rules as configured in `pyproject.toml`.
+* `rich-click` is the sole required runtime dependency (provides Click CLI + Rich output).
+* Apply core design principles: **SOC**, **DRY**, **KISS**, **YAGNI**.
+* Optimize for **clarity and maintainability** over cleverness or micro-optimization.
+
+---
+
+## Import Management
+
+* Use `__init__.py` to define the public API of `ftready`.
+* Use explicit imports — no wildcard imports (`from .module import *`).
+* Group imports: standard library → third-party → local application.
+
+---
+
+## Testing Best Practices
+
+### Mock Guidelines
+
+* Mock where the object is **used**, not where it's defined.
+* Use `autospec=True` to prevent invalid mock usage.
+* Add call assertions to verify mock interactions.
+* Use **pytest-mock's `mocker` fixture** (not `@patch` decorators).
+
+```python
+def test_example(mocker):
+    mock_func = mocker.patch("ftready.scraper._http_get", autospec=True)
+    mock_func.assert_called_once_with(expected_url)
+```
+
+### Network Isolation
+
+* All tests must run **without network access** by default.
+* Mock HTTP calls in unit tests — never hit ft-checker.com or PyPI in CI.
+* Tests that require network access must be marked with `@pytest.mark.network`.

ftready-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & type check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run pyright
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.python-version }}
+      cancel-in-progress: true
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov-branch --cov=ftready

ftready-1.0.0/.github/workflows/ft_check.yml

@@ -0,0 +1,91 @@
+name: Free-threaded Compatibility Check
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Monday 06:00 UTC
+  workflow_dispatch:
+    inputs:
+      include_dev:
+        description: Include dev-only dependencies
+        type: boolean
+        default: false
+      no_cache:
+        description: Force a fresh scrape (ignore cache)
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  ft-check:
+    name: Check free-threaded Python compatibility
+    runs-on: ubuntu-latest
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Get current date (cache key helper)
+        id: date
+        run: echo "date=$(date -u +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore ft-checker cache
+        id: ft-cache
+        if: ${{ !inputs.no_cache }}
+        uses: actions/cache@v4
+        with:
+          path: .ft_cache.json
+          key: ft-checker-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}-${{ steps.date.outputs.date }}
+          restore-keys: |
+            ft-checker-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}-
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install ftready
+        run: uv sync --all-extras
+
+      - name: Run ftready
+        id: run-check
+        run: |
+          ARGS="--output ft_report.txt --verbose --plain"
+          if [ "${{ inputs.include_dev }}" = "true" ]; then ARGS="$ARGS --include-dev"; fi
+          if [ "${{ inputs.no_cache }}" = "true" ]; then ARGS="$ARGS --no-cache"; fi
+          uv run ftready $ARGS
+          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+        continue-on-error: true
+
+      - name: Write job summary
+        if: always()
+        run: |
+          echo "## Free-threaded Python Compatibility Report" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          cat ft_report.txt >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ft-check-report-${{ github.run_id }}
+          path: ft_report.txt
+          retention-days: 30
+
+      - name: Evaluate result
+        if: steps.run-check.outputs.exit_code != '0'
+        run: |
+          echo "::warning::One or more dependencies are marked as FAILED for free-threaded Python."
+          echo "See the uploaded artifact ft_report.txt for details."
+          exit 1
+                  echo "See the uploaded artifact ft_report.txt for details."
+                  exit 1

ftready-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,133 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+# Least-privilege defaults; jobs escalate individually
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    outputs:
+      hashes: ${{ steps.hash.outputs.hashes }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build --no-sources
+
+      - name: Generate subject hashes for SLSA provenance
+        id: hash
+        run: |
+          cd dist
+          echo "hashes=$(sha256sum * | base64 -w0)" >> "$GITHUB_OUTPUT"
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-install:
+    name: Verify installation
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Test install from wheel
+        run: |
+          uv venv --python 3.12
+          uv pip install dist/*.whl
+          uv run python -c "import ftready; print('ftready imported successfully')"
+
+  # --------------------------------------------------------------- #
+  # SLSA Build Level 3 provenance via slsa-framework                #
+  # --------------------------------------------------------------- #
+  provenance:
+    name: Generate SLSA provenance
+    needs: build
+    permissions:
+      actions: read
+      contents: write
+      id-token: write # OIDC for SLSA
+    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.1.0
+    with:
+      base64-subjects: ${{ needs.build.outputs.hashes }}
+      upload-assets: true
+      compile-generator: true
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: [build, test-install, provenance]
+    runs-on: ubuntu-latest
+    environment: test-pypi
+    permissions:
+      id-token: write
+      attestations: write # Sigstore attestations
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate Sigstore attestations
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: dist/*
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+          attestations: true
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, test-install, provenance, publish-testpypi]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      attestations: write # Sigstore attestations
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate Sigstore attestations
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

ftready-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - "CHANGELOG.md"
+      - "docs/**"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    name: Semantic release
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-release-${{ github.ref_name }}
+      cancel-in-progress: false
+
+    steps:
+      - name: Checkout repository on release branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Force release branch to workflow SHA
+        run: git reset --hard ${{ github.sha }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Python Semantic Release
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BEFORE_SHA=$(git rev-parse HEAD)
+
+          uv run semantic-release -v version --no-push --no-vcs-release
+
+          AFTER_SHA=$(git rev-parse HEAD)
+
+          if [ "$BEFORE_SHA" = "$AFTER_SHA" ]; then
+            echo "released=false" >> "$GITHUB_OUTPUT"
+            echo "No release needed."
+          else
+            git push --follow-tags
+            VERSION=$(git tag --points-at HEAD | sed 's/^v//' | head -1)
+            TAG=$(git tag --points-at HEAD | head -1)
+            echo "released=true" >> "$GITHUB_OUTPUT"
+            echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+            echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Create a draft release for review before publishing.
+      # Publishing the draft triggers the publish workflow.
+      - name: Create draft GitHub Release
+        if: steps.release.outputs.released == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ steps.release.outputs.tag }}"
+          uv run semantic-release changelog --post-to-release-tag "$TAG"
+          gh release create "$TAG" \
+            --draft \
+            --title "$TAG" \
+            --notes-file CHANGELOG.md \
+            --verify-tag

ftready-1.0.0/.gitignore

@@ -0,0 +1,35 @@
+# ftready
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Cache and reports
+.ft_cache.json
+.ft_cache.tmp
+ft_report.txt
+
+# Coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+tests/reports/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

ftready-1.0.0/.markdownlint.json

@@ -0,0 +1,12 @@
+{
+    "MD013": false,
+    "MD033": {
+        "allowed_elements": [
+            "h1",
+            "p",
+            "strong",
+            "a",
+            "img"
+        ]
+    }
+}

ftready-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,87 @@
+default_stages: [pre-commit]
+fail_fast: true
+
+default_language_version:
+  python: python3
+
+repos:
+  # Conventional commit validation
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args:
+          - feat
+          - fix
+          - docs
+          - style
+          - refactor
+          - perf
+          - test
+          - build
+          - ci
+          - chore
+          - revert
+
+    # Sanity check for pre-commit hooks and excludes
+  - repo: meta
+    hooks:
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+
+    # Update pre-commit hooks
+  - repo: https://gitlab.com/vojko.pribudic.foss/pre-commit-update
+    rev: v0.9.0
+    hooks:
+      - id: pre-commit-update
+        args: [--verbose, --warnings]
+
+    # Find spelling mistakes in source code
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.45.0
+    hooks:
+      - id: typos
+
+    # Linting and Formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff-check
+        args: [--fix, --unsafe-fixes]
+      - id: ruff-format
+      - id: ruff-check
+
+    # Type checking
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        description: Static type checker for Python
+        entry: uv run pyright
+        language: system
+        pass_filenames: false
+        files: \.py$
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        files: \.(yml|yaml|toml)
+        args: ["--print-width=120"]
+
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: v2.21.0
+    hooks:
+      - id: pyproject-fmt
+
+    # Miscellaneous
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-toml
+      - id: check-yaml
+        args: [--unsafe]
+      - id: check-case-conflict

ftready-1.0.0/.pre-commit-hooks.yaml

@@ -0,0 +1,23 @@
+- id: ftready
+  name: Free-threaded Python compatibility check (pyproject.toml)
+  description: >
+    Check pyproject.toml dependencies for free-threaded Python (3.13t/3.14t)
+    compatibility using ft-checker.com data and PyPI wheel tags.
+  entry: ftready
+  language: python
+  types: [toml]
+  files: ^pyproject\.toml$
+  pass_filenames: false
+  args: [--fail-on=failed]
+
+- id: ftready-requirements
+  name: Free-threaded Python compatibility check (requirements.txt)
+  description: >
+    Check requirements.txt (or any requirements-style file) for free-threaded
+    Python (3.13t/3.14t) compatibility.
+  entry: ftready
+  language: python
+  types_or: [text]
+  files: ^requirements.*\.txt$
+  pass_filenames: false
+  args: [--requirements, requirements.txt, --fail-on=failed]

ftready-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12