pywhatwgurl 0.1.0__tar.gz

pywhatwgurl-0.1.0/.github/workflows/actions/fetch_wpt_url_test_data/action.yml

@@ -0,0 +1,46 @@
+name: 'fetch_wpt_url_test_data'
+description: 'Retrieve WPT URL test suite JSON.'
+inputs:
+  dest_dir:
+    description: 'Directory (relative to $GITHUB_WORKSPACE) in which to save the sanitized file'
+    required: true
+  commit:
+    description: 'Pinned WPT commit hash to fetch URL resources from'
+    required: false
+    default: 'efb889eb4c9ca0b4e3ebd8ab308646b7483a8f54'
+runs:
+  using: "composite"
+  steps:
+    - name: Ensure destination directory exists
+      shell: bash
+      run: |
+        mkdir -p "${{ github.workspace }}/${{ inputs.dest_dir }}"
+
+    - name: Restore cached JSON
+      id: cache
+      uses: actions/cache@v3
+      with:
+        path: |
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/urltestdata.json
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/setters_tests.json
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/percent-encoding.json
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/toascii.json
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/IdnaTestV2.json
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/IdnaTestV2-removed.json
+          ${{ github.workspace }}/${{ inputs.dest_dir }}/wpt_url_test_data_meta.json
+        key: wpt-urltestdata-${{ inputs.commit }}
+
+    - name: Download JSON if cache miss
+      if: steps.cache.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        echo "Cache miss! Downloading fresh copy…"
+        python3 "${{ github.workspace }}/util/wpt_url_test_data.py" download \
+          --dest_dir "${{ github.workspace }}/${{ inputs.dest_dir }}" \
+          --commit "${{ inputs.commit }}"
+        echo "Download complete."
+
+    - name: Skip download if cache hit
+      if: steps.cache.outputs.cache-hit == 'true'
+      shell: bash
+      run: echo "Cache hit! Using existing JSON."

pywhatwgurl-0.1.0/.github/workflows/docs-check.yml

@@ -0,0 +1,33 @@
+name: Docstring Coverage
+
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+
+jobs:
+  docstring-coverage:
+    name: docstring coverage
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project (including dev tools)
+        run: uv sync --locked --all-extras --dev
+
+      - name: Check docstring coverage (interrogate)
+        run: uv run interrogate pywhatwgurl/

pywhatwgurl-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Create .nojekyll
+        run: touch site/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

pywhatwgurl-0.1.0/.github/workflows/fetch_test_data.yml

@@ -0,0 +1,24 @@
+name: Fetch WPT URL Test Data
+
+env:
+  WPT_URL_COMMIT: efb889eb4c9ca0b4e3ebd8ab308646b7483a8f54
+  WPT_TEST_DATA_PATH: tests/conformance/data
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *'  # Runs every day at midnight UTC
+
+jobs:
+  fetch-wpt-url-test-data:
+    name: Fetch fixtures
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Fetch WPT URL test suite JSON
+        uses: ./.github/workflows/actions/fetch_wpt_url_test_data
+        with:
+          commit: ${{ env.WPT_URL_COMMIT }}
+          dest_dir: ${{ env.WPT_TEST_DATA_PATH }}

pywhatwgurl-0.1.0/.github/workflows/main.yml

@@ -0,0 +1,73 @@
+name: CI
+
+env:
+  SOURCE_ROOT: pywhatwgurl
+  WPT_URL_COMMIT: efb889eb4c9ca0b4e3ebd8ab308646b7483a8f54
+  WPT_TEST_DATA_PATH: tests/conformance/data
+
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install the project (including dev tools)
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run Ruff
+        run: uv run ruff check "${{ env.SOURCE_ROOT }}"
+
+      - name: Run mypy
+        run: uv run mypy "${{ env.SOURCE_ROOT }}"
+
+      - name: Run pip-audit
+        run: |
+          uv export --no-dev --no-hashes --no-emit-project -o /tmp/requirements.txt
+          uv run pip-audit --disable-pip --no-deps -r /tmp/requirements.txt
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Fetch WPT URL resources
+        uses: ./.github/workflows/actions/fetch_wpt_url_test_data
+        with:
+          commit: ${{ env.WPT_URL_COMMIT }}
+          dest_dir: ${{ env.WPT_TEST_DATA_PATH }}
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest

pywhatwgurl-0.1.0/.github/workflows/package.yml

@@ -0,0 +1,33 @@
+name: Package
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+      - name: Build package
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        run: uv publish --publish-url "$UV_PUBLISH_URL"
+        env:
+          UV_PUBLISH_URL: https://${{ secrets.GEMFURY_PUSH_TOKEN }}@push.fury.io/pywhatwgurl/

pywhatwgurl-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_rule:
+        description: 'Version Bump Rule'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+        - patch
+        - minor
+        - major
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pywhatwgurl/
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Calculate Next Version
+        id: version
+        run: python util/bump_version.py ${{ inputs.bump_rule }}
+
+      - name: Create and Push Tag
+        run: |
+          git tag ${{ steps.version.outputs.new_tag }}
+          git push origin ${{ steps.version.outputs.new_tag }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Generate SBOM
+        run: |
+          uv export --no-dev --no-hashes --format=requirements-txt > requirements.txt
+          uv run cyclonedx-py requirements requirements.txt --output-format json --output-file sbom.json
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.new_tag }}
+          generate_release_notes: true
+          files: sbom.json

pywhatwgurl-0.1.0/.github/workflows/update_wpt_url.yml

@@ -0,0 +1,131 @@
+name: Bump WPT URL Pin
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 3 * * 1"  # Mondays at 03:00 UTC
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-wpt-url:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Get pinned WPT commit
+        id: current
+        shell: bash
+        run: |
+          CURRENT=$(python - <<'PY'
+          import pathlib, re, sys
+          text = pathlib.Path("util/wpt_url_test_data.py").read_text()
+          m = re.search(r'DEFAULT_WPT_COMMIT = "([0-9a-f]+)"', text)
+          if not m:
+              sys.exit("Could not find DEFAULT_WPT_COMMIT")
+          print(m.group(1))
+          PY
+          )
+          echo "commit=${CURRENT}" >> "$GITHUB_OUTPUT"
+
+      - name: Get latest WPT url commit
+        id: latest
+        shell: bash
+        run: |
+          LATEST=$(python - <<'PY'
+          import json
+          import os
+          import urllib.request
+
+          token = os.getenv("GITHUB_TOKEN")
+          headers = {"User-Agent": "pywhatwgurl-ci"}
+          if token:
+              headers["Authorization"] = f"Bearer {token}"
+
+          req = urllib.request.Request(
+              "https://api.github.com/repos/web-platform-tests/wpt/commits?path=url&per_page=1",
+              headers=headers,
+          )
+          with urllib.request.urlopen(req) as resp:
+              data = json.load(resp)
+          print(data[0]["sha"])
+          PY
+          )
+          echo "commit=${LATEST}" >> "$GITHUB_OUTPUT"
+
+      - name: Stop if already up to date
+        if: steps.latest.outputs.commit == steps.current.outputs.commit
+        run: |
+          echo "Pinned commit matches latest (${{ steps.latest.outputs.commit }}). Nothing to do."
+          exit 0
+
+      - name: Update pinned commit hashes
+        if: steps.latest.outputs.commit != steps.current.outputs.commit
+        shell: bash
+        run: |
+          TARGET="${{ steps.latest.outputs.commit }}"
+          python - <<'PY'
+          import pathlib
+          import re
+          import sys
+
+          target = "${{ steps.latest.outputs.commit }}"
+          def replace_yaml_scalar_key(key: str, text: str) -> str:
+              pattern = rf"^(\s*){re.escape(key)}\s*:\s*([0-9a-f]+)\s*$"
+              new_text, count = re.subn(
+                  pattern,
+                  lambda m: f"{m.group(1)}{key}: {target}",
+                  text,
+                  flags=re.MULTILINE,
+              )
+              if count == 0:
+                  raise RuntimeError(f"Failed to update {key}")
+              return new_text
+
+          updates = [
+              ".github/workflows/fetch_test_data.yml",
+              ".github/workflows/main.yml",
+          ]
+          for path in updates:
+              p = pathlib.Path(path)
+              p.write_text(replace_yaml_scalar_key("WPT_URL_COMMIT", p.read_text()))
+
+          action_path = pathlib.Path(".github/workflows/actions/fetch_wpt_url_test_data/action.yml")
+          action_text = action_path.read_text()
+          def action_repl(m: re.Match[str]) -> str:
+              return f"{m.group(1)}'{target}'"
+          new_action, count = re.subn(r"(default: )'[^']+'", action_repl, action_text)
+          if count == 0:
+              raise RuntimeError("Failed to update action default commit")
+          action_path.write_text(new_action)
+
+          util_path = pathlib.Path("util/wpt_url_test_data.py")
+          util_text = util_path.read_text()
+          def util_repl(m: re.Match[str]) -> str:
+              return f'{m.group(1)}{target}{m.group(3)}'
+          new_util, count = re.subn(r'(DEFAULT_WPT_COMMIT = ")([0-9a-f]+)(")', util_repl, util_text)
+          if count == 0:
+              raise RuntimeError("Failed to update util DEFAULT_WPT_COMMIT")
+          util_path.write_text(new_util)
+          PY
+
+      - name: Create pull request
+        if: steps.latest.outputs.commit != steps.current.outputs.commit
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.WORKFLOW_PAT || github.token }}
+          commit-message: "chore: bump WPT URL tests to ${{ steps.latest.outputs.commit }}"
+          title: "chore: bump WPT URL tests to ${{ steps.latest.outputs.commit }}"
+          branch: "ci/update-wpt-url"
+          delete-branch: true
+          body: |
+            - Update pinned WPT URL commit to `${{ steps.latest.outputs.commit }}`

pywhatwgurl-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# VS Code configuration
+.vscode/
+*.code-workspace
+
+# Downloaded WPT URL test data
+tests/conformance/data/
+
+# Local caches (do not commit)
+.cache/
+.cache/tests/wpt/
+.uv-cache/
+
+# Generated version file
+pywhatwgurl/_version.py
+
+# MkDocs build output
+site/
+
+# Agent files
+AGENTS.md

pywhatwgurl-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: Run ruff check with fix
+        entry: uv run ruff check --fix
+        language: system  # Assumes `uv` is installed and available in the system PATH
+        types: [python]
+        files: \.py$
+
+      - id: mypy
+        name: Run mypy type checking
+        entry: uv run mypy pywhatwgurl
+        language: system
+        types: [python]
+        files: ^pywhatwgurl/
+        pass_filenames: false
+
+      - id: pip-audit
+        name: Run pip-audit (dependency vulnerability scan)
+        entry: bash -c 'uv export --no-dev --no-hashes --no-emit-project -o /tmp/requirements.txt && uv run pip-audit --disable-pip --no-deps -r /tmp/requirements.txt'
+        language: system
+        always_run: true
+        pass_filenames: false

pywhatwgurl-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

pywhatwgurl-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-03
+
+### Added
+- Initial public release of `pywhatwgurl`.
+- Full `URL` and `URLSearchParams` API implementation per the WHATWG URL Standard.
+- 100% WHATWG URL Standard conformance for core URL parsing (validated against [Web Platform Tests](https://github.com/web-platform-tests/wpt/tree/master/url)).
+- Pure Python, fully type-annotated (`py.typed`), zero compiled dependencies.
+- Comprehensive documentation with API reference, user guide, and migration notes.
+- CI pipeline with linting (ruff), type checking (mypy), and security scanning (pip-audit).
+- Automated weekly WPT test data updates via GitHub Actions.
+- SBOM generation (CycloneDX) attached to every GitHub release.
+
+### Known Limitations
+- **IDNA Conformance**: IDNA tests are marked as expected failures (`xfail`). The Python `idna` library follows stricter RFC 5891/5892 rules than the WHATWG URL Standard's lenient UTS46 processing.
+    - Real-world domains generally work correctly; failures are primarily with obscure edge cases not covered by the stricter RFCs.
+    - No Python WHATWG-compliant IDNA implementation currently exists.