afterpython 0.0.1.dev2__py3-none-any.whl → 0.1.0__py3-none-any.whl

afterpython/pcu.py

@@ -0,0 +1,166 @@
+"""
+pcu = "pip check updates", similar to ncu (npm check updates in Node.js)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NamedTuple, TypeAlias, TypedDict
+
+if TYPE_CHECKING:
+    from tomlkit.toml_document import TOMLDocument
+
+import asyncio
+
+from packaging.requirements import Requirement
+
+from afterpython.version import Version
+
+
+class Dependency(NamedTuple):
+    requirement: Requirement
+    min_version: Version | None
+    max_version: Version | None = None
+    latest_version: Version | None = None
+
+
+DependencyName: TypeAlias = str
+ExtrasName: TypeAlias = str
+GroupName: TypeAlias = str
+FakeCategoryName: TypeAlias = str
+Dependencies = TypedDict(
+    "Dependencies",
+    {
+        "dependencies": dict[FakeCategoryName, list[Dependency]],
+        "optional-dependencies": dict[ExtrasName, list[Dependency]],
+        "dependency-groups": dict[GroupName, list[Dependency]],
+        "build-system": dict[str, list[Dependency]],
+    },
+)
+
+
+def parse_min_max_versions_from_requirement(
+    req: Requirement,
+) -> dict[str, Version | None]:
+    min_ver: Version | None = None
+    max_ver: Version | None = None
+    if req.specifier:
+        # req.specifier is like ">=8.3.0" or ">=1.0,<2.0"
+        versions = sorted(Version(spec.version) for spec in req.specifier)
+        if len(versions) == 1:
+            min_ver = versions[0]
+        else:
+            min_ver, max_ver = versions[0], versions[-1]
+    return {
+        "min_version": min_ver,
+        "max_version": max_ver,
+    }
+
+
+async def get_latest_versions(
+    requirements: list[Requirement],
+) -> dict[str, Version | None]:
+    """Get latest versions for a list of dependencies from PyPI."""
+    import httpx
+
+    from afterpython.utils import fetch_pypi_json
+
+    async def fetch_version(
+        client: httpx.AsyncClient, package_name: str
+    ) -> Version | None:
+        """Fetch the latest version of a package from PyPI."""
+        data = await fetch_pypi_json(client, package_name)
+        return Version(data["info"]["version"]) if data else None
+
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        tasks = [fetch_version(client, req.name) for req in requirements]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return dict(zip([req.name for req in requirements], results, strict=False))
+
+
+def get_dependencies() -> Dependencies:
+    """Get dependencies from pyproject.toml"""
+    from afterpython.tools.pyproject import read_pyproject
+
+    doc: TOMLDocument = read_pyproject()
+    dependencies = {
+        "dependencies": list(doc["project"].get("dependencies", [])),
+        "optional-dependencies": dict(doc["project"].get("optional-dependencies", {})),
+        "dependency-groups": dict(doc.get("dependency-groups", {})),
+        "build-system": dict(doc.get("build-system", {})),
+    }
+    # add "fake_category" to "dependencies" to have the same structure as "optional-dependencies" and "dependency-groups"
+    dependencies["dependencies"] = {"fake_category": dependencies["dependencies"]}
+    # only keep the "requires" key
+    if "requires" in dependencies["build-system"]:
+        dependencies["build-system"] = {
+            "requires": dependencies["build-system"]["requires"]
+        }
+
+    # convert all dependency strings to type "Requirement"
+    for dep_type in dependencies:
+        for category, deps in dependencies[dep_type].items():
+            dependencies[dep_type][category] = [Requirement(dep) for dep in deps]
+
+    # flatten the dependencies to a list of type "Requirement"
+    all_reqs = [
+        req
+        for deps_dict in dependencies.values()
+        for req_list in deps_dict.values()
+        for req in req_list
+    ]
+
+    # Fetch ALL latest versions in ONE async call
+    latest_versions = asyncio.run(get_latest_versions(all_reqs))
+
+    # convert the requirements to type "Dependency"
+    for dep_type in dependencies:
+        for category, requirements in dependencies[dep_type].items():
+            dependencies[dep_type][category] = [
+                Dependency(
+                    **parse_min_max_versions_from_requirement(req),
+                    requirement=req,
+                    latest_version=latest_versions.get(req.name),
+                )
+                for req in requirements
+            ]
+
+    return dependencies
+
+
+def update_dependencies(dependencies: Dependencies):
+    """Update dependency versions in pyproject.toml"""
+    from afterpython.tools.pyproject import read_pyproject, write_pyproject
+
+    doc: TOMLDocument = read_pyproject()
+    for dep_type in dependencies:
+        # category = extras or group name
+        for category, deps in dependencies[dep_type].items():
+            if dep_type == "dependencies":
+                doc_deps = doc["project"][dep_type]
+            elif dep_type == "optional-dependencies":
+                doc_deps = doc["project"][dep_type][category]
+            elif dep_type in ["dependency-groups", "build-system"]:
+                doc_deps = doc[dep_type][category]
+            else:
+                raise ValueError(f"Invalid dependency type: {dep_type}")
+
+            # Update in place
+            for i, (dep, package) in enumerate(zip(deps, doc_deps, strict=False)):
+                package: str  # package = e.g. "click>=8.3.0"
+                req: Requirement = dep.requirement
+                min_ver = str(dep.min_version) if dep.min_version else None
+                max_ver = str(dep.max_version) if dep.max_version else None
+                latest_ver = str(dep.latest_version) if dep.latest_version else None
+                if (
+                    req.name in package
+                    and min_ver
+                    and latest_ver
+                    and min_ver in package
+                ):
+                    doc_deps[i] = package.replace(min_ver, latest_ver)
+                    if max_ver and dep.latest_version not in req.specifier:
+                        doc_deps[i] = doc_deps[i].replace(
+                            max_ver, str(dep.max_version.next_breaking())
+                        )
+
+    write_pyproject(doc)

afterpython/templates/ci-workflow-template.yml

@@ -0,0 +1,197 @@
+name: CI
+
+# Trigger CI on pushes to main and all pull requests
+# This ensures every code change is validated before merging
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    # Run on all PRs regardless of target branch
+    branches:
+      - '**'
+
+jobs:
+  # Job 1: Lint and Format Check
+  # Runs ruff to check code quality and formatting
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        # Install the package with uv in system mode
+        # This installs ruff and other tools defined in dependencies
+        run: uv pip install --system .
+
+      - name: Run ruff check
+        run: ruff check --config ./afterpython/ruff.toml .
+
+      - name: Run ruff format check
+        # --check flag ensures it only validates, doesn't reformat
+        run: ruff format --check --config ./afterpython/ruff.toml .
+
+  # Job 2: Detect Test Strategy
+  # Determines whether to use pixi or uv based on pixi.toml presence
+  detect-test-strategy:
+    runs-on: ubuntu-latest
+    outputs:
+      use_pixi: ${{ steps.check.outputs.use_pixi }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Check for pixi.toml
+        id: check
+        run: |
+          if [ -f "pixi.toml" ]; then
+            echo "use_pixi=true" >> $GITHUB_OUTPUT
+          else
+            echo "use_pixi=false" >> $GITHUB_OUTPUT
+          fi
+
+  # Job 3.1: Test Suite - UV Workflow
+  # Traditional Python testing with uv for projects without pixi
+  test-uv:
+    needs: detect-test-strategy
+    if: needs.detect-test-strategy.outputs.use_pixi == 'false'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+      # TODO: support python 3.14
+        python-version: ['3.11', '3.12', '3.13']
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          # Install package, main dependencies, and test dependencies
+          # If no [dependency-groups] test exists, only the package and main dependencies are installed
+          uv pip install --system . --group test || uv pip install --system .
+
+      - name: Run tests with pytest
+        # Run pytest with verbose output
+        # Exit code 5 (no tests collected) is treated as success
+        run: |
+          pytest -v || if [ $? -eq 5 ]; then exit 0; else exit $?; fi
+
+  # Job 3.2: Test Suite - Pixi Workflow
+  # Pixi-based testing for projects using pixi.toml
+  test-pixi:
+    needs: detect-test-strategy
+    if: needs.detect-test-strategy.outputs.use_pixi == 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+      # TODO: support python 3.14
+        environment: ['py311', 'py312', 'py313']
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up pixi
+        uses: prefix-dev/setup-pixi@v0.9.3
+        with:
+          pixi-version: v0.60.0
+          cache: true
+          # Optional: Uncomment if you need prefix.dev authentication
+          # auth-host: prefix.dev
+          # auth-token: ${{ secrets.PREFIX_DEV_TOKEN }}
+
+      - name: Run tests with pixi
+        # Runs test in specific Python environment (py311, py312, py313)
+        # Assumes you have environments defined in pixi.toml with a "test" task
+        # Example pixi.toml:
+        #   [environments]
+        #   py311 = ["py311", "test"]
+        #   [feature.test.tasks]
+        #   test = "pytest -v"
+        # Note: Exit code 5 (no tests collected) is treated as success
+        run: |
+          pixi run -e ${{ matrix.environment }} test || if [ $? -eq 5 ]; then exit 0; else exit $?; fi
+
+  # Job 3.3: Test Suite - Complete
+  # Unified test status for branch protection
+  test:
+    if: always()
+    needs: [detect-test-strategy, test-uv, test-pixi]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check test results
+        run: |
+          uv_result="${{ needs.test-uv.result }}"
+          pixi_result="${{ needs.test-pixi.result }}"
+          # One should succeed, the other should be skipped
+          if [ "$uv_result" == "success" ] || [ "$uv_result" == "skipped" ]; then
+            if [ "$pixi_result" == "success" ] || [ "$pixi_result" == "skipped" ]; then
+              echo "All tests passed!"
+              exit 0
+            fi
+          fi
+          echo "Tests failed: uv=$uv_result, pixi=$pixi_result"
+          exit 1
+
+  # Job 4: Build Verification
+  # Ensures the package can be built successfully
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: List build artifacts
+        # Show what was built (wheel + sdist)
+        # Useful for debugging build issues
+        run: ls -lh dist/
+
+      - name: Install built package
+        # Test that the built wheel can be installed
+        # This catches packaging issues like missing files
+        run: uv pip install --system dist/*.whl
+
+      - name: Verify installation
+        # Confirm the CLI entry point works
+        # This ensures the package is usable after installation
+        run: ap --help
+
+  # Job 5: Type Check
+  # typecheck:

afterpython/templates/cz-template.toml

@@ -0,0 +1,7 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_scheme = "pep440"
+version_provider = "uv"
+update_changelog_on_bump = false
+major_version_zero = true

afterpython/templates/dependabot-template.yml

@@ -0,0 +1,30 @@
+# Dependabot configuration for automatic dependency updates
+# See: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # Update GitHub Actions versions
+  # This keeps your workflow actions secure and up-to-date
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates monthly (less noisy than weekly)
+      interval: "monthly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    # Group all GitHub Actions updates into a single PR
+    # This reduces PR noise and makes reviewing easier
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    # Automatically add reviewers (optional - uncomment and customize)
+    # reviewers:
+    #   - "your-username"
+    # Limit how many Dependabot PRs can be open at once (optional)
+    # Default is 5, increase if you want more concurrent PRs
+    # open-pull-requests-limit: 10
+    #
+    # Note: Auto-merge is configured in GitHub repo settings, not here.
+    # Go to: Settings → General → Pull Requests → Allow auto-merge

afterpython/templates/deploy-workflow-template.yml

@@ -0,0 +1,88 @@
+name: Deploy Project Website to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main  # Deploy when pushing to main branch
+    paths:
+      # Trigger deployment only when content or website files change
+      - 'afterpython/doc/**'
+      - 'afterpython/blog/**'
+      - 'afterpython/tutorial/**'
+      - 'afterpython/example/**'
+      - 'afterpython/guide/**'
+      - 'afterpython/static/**'
+      - 'afterpython/_website/**'
+      - 'afterpython/authors.yml'
+      - 'afterpython/faq.yml'
+      - '.github/workflows/deploy.yml'
+  workflow_dispatch:  # Allow manual deployment from Actions tab
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'pnpm'
+          cache-dependency-path: './afterpython/_website/pnpm-lock.yaml'
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install afterpython
+        run: uv pip install --system afterpython
+
+      - name: Install website dependencies
+        run: pnpm install
+        working-directory: ./afterpython/_website
+
+      - name: Build website
+        run: |
+          ap build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: './afterpython/_website/build'
+
+  deploy:
+    environment:
+      name: github-pages
+      # This will dynamically generate the deployment URL
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

afterpython/templates/pre-commit-config-template.yaml

@@ -0,0 +1,48 @@
+default_install_hook_types:
+- pre-commit
+- commit-msg
+- pre-push
+exclude: ^afterpython/_website/
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+    stages:
+    - pre-commit
+  - id: end-of-file-fixer
+    stages:
+    - pre-commit
+  - id: check-yaml
+    stages:
+    - pre-commit
+  - id: check-toml
+    stages:
+    - pre-commit
+  - id: check-added-large-files
+    stages:
+    - pre-commit
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.14.8
+  hooks:
+  - id: ruff-check
+    stages:
+    - pre-commit
+    args:
+    - --config
+    - ./afterpython/ruff.toml
+  - id: ruff-format
+    stages:
+    - pre-commit
+    args:
+    - --config
+    - ./afterpython/ruff.toml
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: v4.10.0
+  hooks:
+  - id: commitizen
+    stages:
+    - commit-msg
+  - id: commitizen-branch
+    stages:
+    - pre-push

afterpython/templates/release-workflow-template.yml

@@ -0,0 +1,56 @@
+name: Release to PyPI and GitHub
+
+on:
+  push:
+    tags:
+      - 'v*'  # Trigger on all version tags (v0.1.0, v0.1.0rc1, v0.1.0.dev4, etc.)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required for creating GitHub releases
+      id-token: write  # Required for PyPI trusted publishing
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+
+      - name: Determine if pre-release
+        id: check_prerelease
+        run: |
+          # Extract version from tag (remove 'v' prefix)
+          VERSION="${GITHUB_REF_NAME#v}"
+
+          # Check if this is a pre-release or dev version
+          # Matches: dev, rc, alpha, beta, a1, b2 (but not 'stable-version')
+          if [[ "$VERSION" =~ (dev|rc|alpha|beta|a[0-9]+|b[0-9]+) ]]; then
+            echo "prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "prerelease=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          generate_release_notes: false
+          prerelease: ${{ steps.check_prerelease.outputs.prerelease }}
+          files: dist/*  # Attach built packages (wheel + sdist)

afterpython/templates/ruff-template.toml

@@ -0,0 +1,32 @@
+# Ruff configuration
+# See More: https://docs.astral.sh/ruff/configuration/
+
+line-length = 88
+target-version = "py311"
+
+[lint]
+# ruff default rules:
+select = [
+    "E4",  # import-related errors (e.g., undefined names in imports)
+    "E7",  # statement errors (e.g., multiple statements on one line)
+    "E9",  # runtime errors (e.g., syntax errors, indentation issues)
+    "F",   # Pyflakes - logical errors (e.g., unused imports, undefined variables)
+]
+# ignored rules:
+ignore = [
+    "E501",  # line too long
+]
+# extended rules:
+extend-select = [
+    "I",     # isort - import sorting
+    "UP",    # pyupgrade - upgrade syntax for newer Python
+    "B",     # flake8-bugbear - find likely bugs
+    "SIM",   # flake8-simplify - simplify code
+    # "C90",   # mccabe - complexity checking
+    "N",     # pep8-naming - enforce naming conventions
+    "RUF",   # ruff-specific rules
+]
+
+[format]
+quote-style = "double"  # double quotes for strings
+indent-style = "space"  # indent with spaces, rather than tabs.