headerkit 0.4.0__tar.gz

headerkit-0.4.0/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    groups:
+      minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

headerkit-0.4.0/.github/workflows/check-llvm.yml

@@ -0,0 +1,113 @@
+name: Check LLVM Releases
+
+# Detect new stable LLVM major versions that aren't yet vendored in headerkit/_clang/
+# and open an issue with vendoring instructions.
+
+on:
+  schedule:
+    - cron: "0 10 * * 1" # Mondays at 10 AM UTC
+  workflow_dispatch:
+
+permissions:
+  issues: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Detect new LLVM versions
+        id: detect
+        run: |
+          # Fetch all LLVM tags once and cache for reuse
+          all_tags=$(
+            git -c 'versionsort.suffix=-' \
+              ls-remote --exit-code --refs --sort='version:refname' --tags \
+              https://github.com/llvm/llvm-project 'llvmorg-*.*.*' \
+            | sed 's/.*llvmorg-//' \
+            | grep -v '-'
+          )
+
+          # Get all stable LLVM major versions with releases (>= 18)
+          released_majors=$(
+            echo "$all_tags" \
+            | awk -F. '$1 >= 18 { print $1 }' \
+            | sort -un
+          )
+
+          # Get vendored major versions
+          vendored_majors=$(
+            ls -d headerkit/_clang/v*/ 2>/dev/null \
+            | sed 's|headerkit/_clang/v||; s|/||' \
+            | sort -n
+          )
+
+          echo "Released LLVM majors: $released_majors"
+          echo "Vendored majors: $vendored_majors"
+
+          # Find missing versions
+          missing=""
+          for major in $released_majors; do
+            if ! echo "$vendored_majors" | grep -qx "$major"; then
+              missing="$missing $major"
+            fi
+          done
+          missing=$(echo "$missing" | xargs)
+
+          echo "Missing: ${missing:-none}"
+          echo "missing=$missing" >> "$GITHUB_OUTPUT"
+
+          # Save tag list for reuse in the next step
+          {
+            echo "all_tags<<TAGS_EOF"
+            echo "$all_tags"
+            echo "TAGS_EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Open issues for missing versions
+        if: steps.detect.outputs.missing != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          MISSING: ${{ steps.detect.outputs.missing }}
+          ALL_TAGS: ${{ steps.detect.outputs.all_tags }}
+        run: |
+          for major in $MISSING; do
+            title="Vendor clang Python bindings for LLVM $major"
+
+            # Skip if issue already exists (open or closed)
+            existing=$(gh issue list --search "\"$title\" in:title" --state all --json number --jq 'length')
+            if [ "$existing" -gt 0 ]; then
+              echo "Issue already exists for LLVM $major, skipping"
+              continue
+            fi
+
+            # Get latest patch version for this major from cached tags
+            latest=$(
+              echo "$ALL_TAGS" \
+              | grep "^${major}\." \
+              | sort -t. -k1,1n -k2,2n -k3,3n \
+              | tail -1
+            )
+
+            body="A new LLVM major version ($major) has stable releases (latest: $latest) but no vendored bindings in \`headerkit/_clang/\`.
+
+          ## Steps to vendor
+
+          1. Download the clang Python bindings from the LLVM $latest source:
+             \`\`\`
+             https://github.com/llvm/llvm-project/tree/llvmorg-$latest/clang/bindings/python/clang
+             \`\`\`
+          2. Create \`headerkit/_clang/v$major/\` with:
+             - \`__init__.py\`
+             - \`cindex.py\` (from the LLVM source)
+             - \`PROVENANCE\` (source URL, SHA256, license)
+          3. Update \`headerkit/_clang/__init__.py\` if the loader needs changes for the new version.
+          4. Add tests and verify with \`pytest\`.
+
+          *This issue was automatically created by the check-llvm workflow.*"
+
+            gh issue create --title "$title" --body "$body"
+            echo "Created issue for LLVM $major"
+          done

headerkit-0.4.0/.github/workflows/check-python.yml

@@ -0,0 +1,161 @@
+# Check for Python version support updates
+#
+# Runs weekly to detect:
+# - New stable Python releases that should be added to the test matrix
+# - Python versions reaching end-of-life that should be dropped
+#
+# Creates GitHub issues when action is needed.
+#
+# Manual trigger:
+#   Go to Actions -> Check Python Versions -> Run workflow
+
+name: Check Python Versions
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 10 * * 1'  # Weekly on Monday
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Check Python versions
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Extract supported versions from pyproject.toml
+          supported=$(grep 'Programming Language :: Python :: 3\.' pyproject.toml \
+            | sed 's/.*Python :: //' | sed 's/".*//' | tr '\n' ' ')
+          min_python=$(grep 'requires-python' pyproject.toml \
+            | sed 's/.*>=\([0-9.]*\).*/\1/')
+          echo "supported=$supported" >> $GITHUB_OUTPUT
+          echo "min_python=$min_python" >> $GITHUB_OUTPUT
+          echo "Currently supported: $supported"
+          echo "Minimum Python: $min_python"
+
+          # Fetch Python release cycle data from endoflife.date API
+          curl -s https://endoflife.date/api/python.json > /tmp/python_versions.json
+
+          # Find stable versions we DON'T support yet
+          python3 -c "
+          import json, sys
+          with open('/tmp/python_versions.json') as f:
+              versions = json.load(f)
+          supported = '$supported'.split()
+          for v in versions:
+              cycle = v['cycle']
+              # Only consider 3.x versions
+              if not cycle.startswith('3.'):
+                  continue
+              minor = int(cycle.split('.')[1])
+              # Only consider versions >= our minimum
+              min_minor = int('$min_python'.split('.')[1])
+              if minor < min_minor:
+                  continue
+              # Check if this is a stable release (not pre-release)
+              if v.get('lts', False) or v.get('latest', ''):
+                  if cycle not in supported:
+                      print(f'NEW:{cycle}')
+              # Check for EOL versions we still support
+              eol = v.get('eol', '')
+              if eol and eol != 'false' and eol <= '$(date +%Y-%m-%d)':
+                  if cycle in supported:
+                      print(f'EOL:{cycle}:{eol}')
+          " > /tmp/version_actions.txt
+
+          cat /tmp/version_actions.txt
+
+          new=$(grep '^NEW:' /tmp/version_actions.txt | sed 's/NEW://' | tr '\n' ' ' || true)
+          eol=$(grep '^EOL:' /tmp/version_actions.txt || true)
+
+          echo "new_versions=$new" >> $GITHUB_OUTPUT
+          echo "eol_versions=$eol" >> $GITHUB_OUTPUT
+
+      - name: Create issue for new Python versions
+        if: steps.check.outputs.new_versions != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NEW_VERSIONS: ${{ steps.check.outputs.new_versions }}
+          SUPPORTED: ${{ steps.check.outputs.supported }}
+        run: |
+          for version in $NEW_VERSIONS; do
+            title="Add Python $version to test matrix"
+
+            # Check if issue already exists
+            existing=$(gh issue list --state open --search "$title" --json number,title \
+              --jq ".[] | select(.title == \"$title\") | .number")
+            if [ -n "$existing" ]; then
+              echo "Issue #$existing already open for Python $version, skipping"
+              continue
+            fi
+
+            run_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+            body=$(cat <<EOF
+          Python $version is now available as a stable release but is not in our test matrix.
+
+          ## Currently Supported
+          $SUPPORTED
+
+          ## Action Required
+          1. Add \`"Programming Language :: Python :: $version"\` to \`pyproject.toml\` classifiers
+          2. Add \`"$version"\` to the matrix in \`.github/workflows/test.yml\`
+          3. Verify all tests pass on Python $version
+
+          **Workflow run:** $run_url
+          EOF
+          )
+
+            gh issue create --title "$title" --body "$body" --label "dependencies"
+          done
+
+      - name: Create issue for EOL Python versions
+        if: steps.check.outputs.eol_versions != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EOL_VERSIONS: ${{ steps.check.outputs.eol_versions }}
+          SUPPORTED: ${{ steps.check.outputs.supported }}
+        run: |
+          echo "$EOL_VERSIONS" | grep '^EOL:' | while IFS=: read -r _ version eol_date; do
+            title="Drop Python $version (EOL $eol_date)"
+
+            # Check if issue already exists
+            existing=$(gh issue list --state open --search "$title" --json number,title \
+              --jq ".[] | select(.title == \"$title\") | .number")
+            if [ -n "$existing" ]; then
+              echo "Issue #$existing already open for Python $version EOL, skipping"
+              continue
+            fi
+
+            run_url="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+
+            body=$(cat <<EOF
+          Python $version reached end-of-life on $eol_date and no longer receives security patches.
+
+          ## Currently Supported
+          $SUPPORTED
+
+          ## Action Required
+          1. Remove \`"Programming Language :: Python :: $version"\` from \`pyproject.toml\` classifiers
+          2. Remove \`"$version"\` from the matrix in \`.github/workflows/test.yml\`
+          3. Update \`requires-python\` in \`pyproject.toml\` if this was the minimum version
+          4. Remove any version-specific workarounds for Python $version
+
+          **Workflow run:** $run_url
+          EOF
+          )
+
+            gh issue create --title "$title" --body "$body" --label "dependencies"
+          done

headerkit-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+      - run: pip install -e '.[lint]'
+      - uses: pre-commit/action@v3.0.1
+
+  test:
+    uses: ./.github/workflows/test.yml

headerkit-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Documentation
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to deploy (e.g., 0.3)'
+        required: true
+      set_latest:
+        description: 'Set as latest?'
+        type: boolean
+        default: true
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: pip install -e '.[docs]'
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Extract version from tag
+        if: github.event_name == 'push'
+        id: version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          MINOR="${TAG%.*}"
+          echo "version=$MINOR" >> "$GITHUB_OUTPUT"
+          echo "Deploying docs for version: $MINOR"
+
+      - name: Deploy versioned docs (tag push)
+        if: github.event_name == 'push'
+        run: |
+          mike deploy --push --update-aliases "${{ steps.version.outputs.version }}" latest
+
+      - name: Deploy versioned docs (manual)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if [ "${{ inputs.set_latest }}" = "true" ]; then
+            mike deploy --push --update-aliases "${{ inputs.version }}" latest
+          else
+            mike deploy --push "${{ inputs.version }}"
+          fi
+
+      - name: Set default version
+        if: github.event_name == 'push'
+        run: mike set-default --push latest

headerkit-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed.
+#
+# Prerequisites (one-time setup):
+#   1. Go to https://pypi.org/manage/account/publishing/
+#   2. Add a pending publisher:
+#      - Owner: axiomantic
+#      - Repository: headerkit
+#      - Workflow: release.yml
+#      - Environment: pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+      - run: pip install build
+      - run: python -m build
+      - name: Verify version matches tag
+        run: |
+          TAG="${{ github.ref_name }}"
+          EXPECTED="${TAG#v}"
+          VERSION=$(python -c "
+          import tomllib
+          with open('pyproject.toml', 'rb') as f:
+              print(tomllib.load(f)['project']['version'])
+          ")
+          if [ "$VERSION" != "$EXPECTED" ]; then
+            echo "::error::Version mismatch: tag=$EXPECTED, pyproject.toml=$VERSION"
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          retention-days: 5
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: [build, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: gh release create "$TAG" dist/* --repo "$REPO" --generate-notes

headerkit-0.4.0/.github/workflows/test-install-libclang.yml

@@ -0,0 +1,52 @@
+name: Test install_libclang
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  install-libclang:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+
+      - name: Install package
+        shell: bash
+        run: pip install -e .
+
+      - name: Run install_libclang
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            sudo python -m headerkit.install_libclang --skip-verify
+          else
+            python -m headerkit.install_libclang --skip-verify
+          fi
+
+      - name: Refresh PATH (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $machinePath = [Environment]::GetEnvironmentVariable("Path", "Machine")
+          $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+          $env:Path = "$machinePath;$userPath"
+          echo "Path=$env:Path" >> $env:GITHUB_ENV
+
+      - name: Verify libclang is usable
+        shell: bash
+        run: python -c "from headerkit.backends.libclang import is_system_libclang_available; assert is_system_libclang_available(), 'libclang not available after install'"

headerkit-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+      - name: Install libclang (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libclang-dev
+      - name: Install libclang (macOS)
+        if: runner.os == 'macOS'
+        run: brew install llvm
+      - name: Verify LLVM (Windows)
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          clang --version
+          which clang || true
+      - name: Install package
+        shell: bash
+        run: pip install -e '.[test]'
+      - name: Cache test header downloads
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/headerkit-test-headers
+          key: test-headers-v1
+      - name: Run tests
+        shell: bash
+        run: pytest

headerkit-0.4.0/.gitignore

@@ -0,0 +1,73 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Environments
+.env
+.venv/
+env/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+logs/
+
+# MkDocs
+site/

headerkit-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--unsafe]
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        args: [--strict]
+        additional_dependencies: []
+        pass_filenames: false
+        entry: mypy headerkit/