whytrail 0.1.0__tar.gz

whytrail-0.1.0/.github/actions/whytrail-run/README.md

@@ -0,0 +1,20 @@
+# whytrail run (GitHub Action)
+
+Wraps `whytrail run` (see `src/whytrail/cli/__main__.py`) so a CI job's failure
+output shows a causal explanation instead of a bare traceback -- the same
+CLI a developer would run locally, packaged for a workflow step.
+
+```yaml
+- uses: <owner>/whytrail/.github/actions/whytrail-run@main
+  with:
+    script: scripts/nightly_import.py
+    graph: "true"                          # optional: include a Mermaid graph
+    extra-packages: whytrail-requests         # optional: plugin distributions the script needs
+```
+
+On an uncaught exception, the step fails (matching `whytrail run`'s own exit
+code) and the explanation appears in the job log at the point of failure --
+no extra step needed to surface it.
+
+Inputs: `script` (required), `args`, `python-version` (default `3.x`),
+`graph` (default `false`), `extra-packages`.

whytrail-0.1.0/.github/actions/whytrail-run/action.yml

@@ -0,0 +1,50 @@
+name: "whytrail run"
+description: "Run a Python script and explain any uncaught exception with whytrail instead of a bare traceback."
+branding:
+  icon: "help-circle"
+  color: "orange"
+
+inputs:
+  script:
+    description: "Path to the Python script to run"
+    required: true
+  args:
+    description: "Arguments to pass to the script"
+    required: false
+    default: ""
+  python-version:
+    description: "Python version to set up before running"
+    required: false
+    default: "3.x"
+  graph:
+    description: "Include a Mermaid provenance graph in the explanation output"
+    required: false
+    default: "false"
+  extra-packages:
+    description: "Space-separated extra packages to install alongside whytrail (e.g. plugin distributions your script needs, like whytrail-requests)"
+    required: false
+    default: ""
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install whytrail
+      shell: bash
+      run: |
+        pip install whytrail
+        if [ -n "${{ inputs.extra-packages }}" ]; then
+          pip install ${{ inputs.extra-packages }}
+        fi
+
+    - name: Run script with whytrail
+      shell: bash
+      run: |
+        FLAGS=""
+        if [ "${{ inputs.graph }}" = "true" ]; then
+          FLAGS="--graph"
+        fi
+        whytrail run $FLAGS "${{ inputs.script }}" -- ${{ inputs.args }}

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

@@ -0,0 +1,333 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install whytrail (core + dev)
+        run: pip install -e ".[dev]"
+
+      - name: Type-check with mypy --strict
+        run: mypy
+
+      - name: Run core test suite
+        run: pytest tests -q
+
+  plugin-contract-tests:
+    # Each plugin has its own third-party dependency (pandas, sqlalchemy,
+    # fastapi, ...); installing all of them into the core matrix above
+    # would make every core-only change pay for every plugin's install
+    # time. Kept separate so a plugin dependency bump can't block a
+    # core-only PR, and vice versa.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        plugin:
+          - whytrail-requests
+          - whytrail-pytest
+          - whytrail-sentry
+          - whytrail-pandas
+          - whytrail-sqlalchemy
+          - whytrail-fastapi
+          - whytrail-django
+          - whytrail-celery
+          - whytrail-langchain
+          - whytrail-pydantic
+          - whytrail-boto3
+          - whytrail-httpx
+          - whytrail-openai
+          - whytrail-anthropic
+          - whytrail-asyncpg
+          - whytrail-pymongo
+          - whytrail-marshmallow
+          - whytrail-jsonschema
+          - whytrail-polars
+          - whytrail-rq
+          - whytrail-dramatiq
+          - whytrail-flask
+          - whytrail-pyyaml
+          - whytrail-grpcio
+          - whytrail-scrapy
+          - whytrail-aiohttp
+          - whytrail-huggingface-hub
+          - whytrail-google-cloud
+          - whytrail-ddtrace
+          - whytrail-prefect
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install whytrail + plugin under test + test deps
+        run: |
+          pip install -e ".[dev]"
+          # [test] is requested for every plugin uniformly; pip just warns
+          # ("does not provide the extra") and continues for the ~28 that
+          # don't declare one. The two that do (whytrail-fastapi needs the
+          # real fastapi package + httpx's TestClient; whytrail-rq needs
+          # fakeredis) are test-only tools neither plugin depends on at
+          # runtime, so they don't belong in the plugin's own
+          # `dependencies` -- found when both failed on the first real CI
+          # run with pytest exit 5 ("no tests collected"), since their
+          # test files' module-level `pytest.importorskip` guards turned a
+          # missing test-only dependency into a silent zero-test skip
+          # rather than a visible failure.
+          pip install -e "./plugins/${{ matrix.plugin }}[test]"
+
+      - name: Run this plugin's contract tests
+        run: |
+          # Strip the "whytrail-" prefix, then convert any remaining
+          # dashes to underscores -- needed for plugins like
+          # whytrail-google-cloud and whytrail-huggingface-hub, whose test
+          # files (test_google_cloud_plugin.py,
+          # test_huggingface_hub_plugin.py) use underscores throughout.
+          # A prefix-only strip would look for a literal dash in the
+          # filename and silently match zero tests.
+          name="${{ matrix.plugin }}"
+          test_name="${name#whytrail-}"
+          test_name="${test_name//-/_}"
+          pytest "tests/plugin_contract/test_${test_name}_plugin.py" -q
+
+  plugin-version-matrix:
+    # docs/testing-maturity.md gap #1: every plugin above installs
+    # whatever `pip` resolves today, never the specific floor each
+    # pyproject.toml claims to support. Checking that floor for real
+    # found real version-compatibility bugs in two rounds: first locally
+    # in this sandbox (Windows, before this job existed), then again --
+    # differently -- on the actual ubuntu-latest runners this job
+    # targets, the first time it ever executed for real. Neither round
+    # alone would have found everything the other did; several "confirmed
+    # fine" conclusions from local-only testing turned out wrong once a
+    # real CI run actually exercised each plugin's contract tests against
+    # its pinned floor, not just "does it install and import."
+    #
+    # No 3.13 wheel / build failure (found locally, still holds on Linux):
+    #   - pydantic==2.0.3: pydantic-core fails to build from source
+    #     (ForwardRef._evaluate() signature changed). First working: 2.8.0.
+    #   - pyyaml==6.0: source build fails (Cython/setuptools mismatch).
+    #     First working: 6.0.2.
+    #   - grpcio==1.60.0: no 3.13 wheel on any platform. First working: 1.66.2.
+    #   - pandas==2.0.0: no 3.13 wheel. First working: 2.2.3.
+    #
+    # Genuine Python 3.13 runtime incompatibility in the dependency's own
+    # code, not a packaging gap:
+    #   - sqlalchemy==2.0.0: TypingOnly assertion predates two dunders
+    #     3.13 added to every class. First working: 2.0.36.
+    #   - asyncpg==0.29.0: pgproto.c calls a C API function with the
+    #     pre-3.13 argument count. First working: 0.30.0.
+    #   - sentry-sdk==2.0.0: copies frame locals via copy.copy(), which
+    #     breaks on 3.13's FrameLocalsProxy (PEP 667) -- passed a local
+    #     install-and-import check, only failed when its actual capture
+    #     path ran against a real exception in a real CI run. First
+    #     working, found by bisection: 2.11.0.
+    #   - prefect==2.14.0-2.20.0: not fixable within the 2.x line at all --
+    #     `GatherTaskGroup` (prefect's own asyncio.TaskGroup subclass)
+    #     doesn't implement an abstract method 3.13's asyncio added,
+    #     independent of which pydantic/griffe versions are present. The
+    #     floor moved to the 3.x line entirely: 3.7.8 (earlier 3.x
+    #     releases have their own pydantic-version-drift issues below).
+    #
+    # Standard-library removal, unrelated to any single dependency version:
+    #   - marshmallow==3.0.0: imports `distutils.version.LooseVersion`,
+    #     removed in 3.12 (PEP 632). First working, by bisection: 3.15.0.
+    #
+    # Transitive-dependency drift -- the floor's own unpinned/loosely-pinned
+    # sub-dependency moved on and broke it, nothing to do with Python 3.13:
+    #   - requests==2.20.0: imports `urllib3.packages.six.moves`, a shim
+    #     urllib3 2.0 removed. First working, by bisection: 2.25.0.
+    #   - flask==2.3.0: testing.py reads `werkzeug.__version__`, which
+    #     werkzeug 3.x removed. First working: 2.3.3.
+    #   - prefect (see above): also hit a `pydantic.ConfigWrapper`
+    #     TypeError against pydantic's newest 2.x releases, and separately
+    #     a `griffe.Docstring` import removed by a later griffe release --
+    #     three independent drift issues layered on the same plugin.
+    #
+    # Plugin/test written against a newer version of the SDK's own API
+    # than the stated floor actually provides -- not a Python-version or
+    # transitive-drift issue, just an old client library:
+    #   - ddtrace==2.0.0: `ddtrace.trace.tracer` (a module-level singleton
+    #     the test imports) didn't exist yet. First working: 2.20.0.
+    #   - openai==1.0.0: exception `.body` shape at this version doesn't
+    #     match what the plugin reads. First working, by bisection: 1.30.0.
+    #   - anthropic==0.30.0: same shape issue. First working: 0.34.0.
+    #   - huggingface_hub==0.20.0: `huggingface_hub.errors` (the module the
+    #     plugin imports) didn't exist yet, and even once it did (0.22+),
+    #     `hf_raise_for_status()`'s response-shape handling didn't match
+    #     until the 1.x line. First working: 1.0.0 -- a major-version
+    #     jump, not a patch bump, the same way prefect needed one.
+    #
+    # Not independently version-testable the way this job assumes:
+    #   - whytrail-fastapi tests build a real FastAPI app, so `starlette`
+    #     alone isn't a meaningful axis to pin -- forcing an old starlette
+    #     floor (0.36.0) against whatever fastapi the test-tools step
+    #     installs breaks on an unrelated TestClient API mismatch the
+    #     moment the two are versioned independently. `fastapi` is the
+    #     pinned dependency instead (floor 0.115.0, the oldest version
+    #     confirmed to both resolve a starlette satisfying the plugin's
+    #     real >=0.36 floor *and* pass); the test-tools step below installs
+    #     only httpx for this plugin now, not fastapi.
+    #
+    # Every other plugin's stated floor (boto3, httpx, django, celery,
+    # dramatiq, rq, langchain-core, google-api-core, pytest, jsonschema,
+    # scrapy, polars, aiohttp, pymongo) was checked the same way on real
+    # ubuntu-latest CI and confirmed to already work -- not assumed, just
+    # not (yet) found broken. See docs/testing-maturity.md for why "found
+    # broken so far" and "confirmed working" are different-strength claims,
+    # and CHANGELOG.md for the full account of both rounds of findings.
+    #
+    # This job pins each plugin's *actual* Python-3.13-compatible floor
+    # (not the aspirational one in pyproject.toml, which is still correct
+    # for older Python versions) against the latest release, so a future
+    # dependency bump that reintroduces a gap like this fails CI instead
+    # of being discovered by a user.
+    # Each entry below is fully explicit (plugin, dependency, floor,
+    # dependency-version) rather than a `plugin`x`dependency-version`
+    # cross-product via a separate `include:` list. The cross-product
+    # form was tried first and is wrong: `include` entries only merge
+    # into a base matrix when they share a key with it, and these entries
+    # share no key with a bare `dependency-version: [floor, latest]` axis
+    # -- so instead of the intended 60 jobs (30 plugins x 2 versions),
+    # only 2 generic jobs ran, both missing plugin context entirely. Not
+    # caught by local `mkdocs`/`mypy`/`pytest` verification, since none
+    # of those parse this workflow file -- only found by watching the
+    # first real push actually run it and seeing "plugin-version-matrix
+    # (floor)" and "(latest)" instead of 60 named jobs.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { plugin: whytrail-pydantic, dependency: pydantic, floor: "2.8.0", dependency-version: floor }
+          - { plugin: whytrail-pydantic, dependency: pydantic, floor: "2.8.0", dependency-version: latest }
+          - { plugin: whytrail-sqlalchemy, dependency: sqlalchemy, floor: "2.0.36", dependency-version: floor }
+          - { plugin: whytrail-sqlalchemy, dependency: sqlalchemy, floor: "2.0.36", dependency-version: latest }
+          - { plugin: whytrail-asyncpg, dependency: asyncpg, floor: "0.30.0", dependency-version: floor }
+          - { plugin: whytrail-asyncpg, dependency: asyncpg, floor: "0.30.0", dependency-version: latest }
+          - { plugin: whytrail-pyyaml, dependency: pyyaml, floor: "6.0.2", dependency-version: floor }
+          - { plugin: whytrail-pyyaml, dependency: pyyaml, floor: "6.0.2", dependency-version: latest }
+          - { plugin: whytrail-grpcio, dependency: grpcio, floor: "1.66.2", dependency-version: floor }
+          - { plugin: whytrail-grpcio, dependency: grpcio, floor: "1.66.2", dependency-version: latest }
+          - { plugin: whytrail-ddtrace, dependency: ddtrace, floor: "2.20.0", dependency-version: floor }
+          - { plugin: whytrail-ddtrace, dependency: ddtrace, floor: "2.20.0", dependency-version: latest }
+          - { plugin: whytrail-pandas, dependency: pandas, floor: "2.2.3", dependency-version: floor }
+          - { plugin: whytrail-pandas, dependency: pandas, floor: "2.2.3", dependency-version: latest }
+          - { plugin: whytrail-marshmallow, dependency: marshmallow, floor: "3.15.0", dependency-version: floor }
+          - { plugin: whytrail-marshmallow, dependency: marshmallow, floor: "3.15.0", dependency-version: latest }
+          - { plugin: whytrail-requests, dependency: requests, floor: "2.25.0", dependency-version: floor }
+          - { plugin: whytrail-requests, dependency: requests, floor: "2.25.0", dependency-version: latest }
+          - { plugin: whytrail-prefect, dependency: prefect, floor: "3.7.8", dependency-version: floor }
+          - { plugin: whytrail-prefect, dependency: prefect, floor: "3.7.8", dependency-version: latest }
+          - { plugin: whytrail-polars, dependency: polars, floor: "0.20.0", dependency-version: floor }
+          - { plugin: whytrail-polars, dependency: polars, floor: "0.20.0", dependency-version: latest }
+          - { plugin: whytrail-aiohttp, dependency: aiohttp, floor: "3.9.0", dependency-version: floor }
+          - { plugin: whytrail-aiohttp, dependency: aiohttp, floor: "3.9.0", dependency-version: latest }
+          - { plugin: whytrail-boto3, dependency: boto3, floor: "1.34.0", dependency-version: floor }
+          - { plugin: whytrail-boto3, dependency: boto3, floor: "1.34.0", dependency-version: latest }
+          - { plugin: whytrail-httpx, dependency: httpx, floor: "0.27.0", dependency-version: floor }
+          - { plugin: whytrail-httpx, dependency: httpx, floor: "0.27.0", dependency-version: latest }
+          - { plugin: whytrail-flask, dependency: flask, floor: "2.3.3", dependency-version: floor }
+          - { plugin: whytrail-flask, dependency: flask, floor: "2.3.3", dependency-version: latest }
+          - { plugin: whytrail-django, dependency: django, floor: "4.2.0", dependency-version: floor }
+          - { plugin: whytrail-django, dependency: django, floor: "4.2.0", dependency-version: latest }
+          - { plugin: whytrail-celery, dependency: celery, floor: "5.3.0", dependency-version: floor }
+          - { plugin: whytrail-celery, dependency: celery, floor: "5.3.0", dependency-version: latest }
+          - { plugin: whytrail-dramatiq, dependency: dramatiq, floor: "1.14.0", dependency-version: floor }
+          - { plugin: whytrail-dramatiq, dependency: dramatiq, floor: "1.14.0", dependency-version: latest }
+          - { plugin: whytrail-rq, dependency: rq, floor: "1.15.0", dependency-version: floor }
+          - { plugin: whytrail-rq, dependency: rq, floor: "1.15.0", dependency-version: latest }
+          - { plugin: whytrail-sentry, dependency: sentry-sdk, floor: "2.11.0", dependency-version: floor }
+          - { plugin: whytrail-sentry, dependency: sentry-sdk, floor: "2.11.0", dependency-version: latest }
+          - { plugin: whytrail-langchain, dependency: langchain-core, floor: "0.2.0", dependency-version: floor }
+          - { plugin: whytrail-langchain, dependency: langchain-core, floor: "0.2.0", dependency-version: latest }
+          - { plugin: whytrail-huggingface-hub, dependency: huggingface_hub, floor: "1.0.0", dependency-version: floor }
+          - { plugin: whytrail-huggingface-hub, dependency: huggingface_hub, floor: "1.0.0", dependency-version: latest }
+          - { plugin: whytrail-google-cloud, dependency: google-api-core, floor: "2.15.0", dependency-version: floor }
+          - { plugin: whytrail-google-cloud, dependency: google-api-core, floor: "2.15.0", dependency-version: latest }
+          - { plugin: whytrail-anthropic, dependency: anthropic, floor: "0.34.0", dependency-version: floor }
+          - { plugin: whytrail-anthropic, dependency: anthropic, floor: "0.34.0", dependency-version: latest }
+          - { plugin: whytrail-openai, dependency: openai, floor: "1.30.0", dependency-version: floor }
+          - { plugin: whytrail-openai, dependency: openai, floor: "1.30.0", dependency-version: latest }
+          - { plugin: whytrail-pytest, dependency: pytest, floor: "7.0.0", dependency-version: floor }
+          - { plugin: whytrail-pytest, dependency: pytest, floor: "7.0.0", dependency-version: latest }
+          - { plugin: whytrail-jsonschema, dependency: jsonschema, floor: "4.0.0", dependency-version: floor }
+          - { plugin: whytrail-jsonschema, dependency: jsonschema, floor: "4.0.0", dependency-version: latest }
+          - { plugin: whytrail-scrapy, dependency: scrapy, floor: "2.8.0", dependency-version: floor }
+          - { plugin: whytrail-scrapy, dependency: scrapy, floor: "2.8.0", dependency-version: latest }
+          - { plugin: whytrail-fastapi, dependency: fastapi, floor: "0.115.0", dependency-version: floor }
+          - { plugin: whytrail-fastapi, dependency: fastapi, floor: "0.115.0", dependency-version: latest }
+          - { plugin: whytrail-pymongo, dependency: pymongo, floor: "4.0.0", dependency-version: floor }
+          - { plugin: whytrail-pymongo, dependency: pymongo, floor: "4.0.0", dependency-version: latest }
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install whytrail + plugin (without its dependency pin)
+        run: |
+          pip install -e ".[dev]"
+          pip install -e "./plugins/${{ matrix.plugin }}" --no-deps
+
+      - name: Install this plugin's test-only tools, if any
+        # --no-deps above (deliberately, so the next step controls the
+        # dependency-under-test's exact version) also blocks pip from
+        # resolving [test]-extra packages via the normal
+        # "pkg[test]" syntax, since --no-deps skips all dependency
+        # metadata, not just the core `dependencies` list -- so these
+        # are installed directly by name instead, same tools as
+        # plugin-contract-tests' [test] extra above.
+        # whytrail-fastapi installs only httpx here, not fastapi itself --
+        # fastapi is the dependency under test for this plugin (see the
+        # entries above and the note by them), handled by the next step.
+        run: |
+          case "${{ matrix.plugin }}" in
+            whytrail-fastapi) pip install httpx ;;
+            whytrail-rq) pip install fakeredis ;;
+          esac
+
+      - name: Install the dependency at the version under test
+        run: |
+          if [ "${{ matrix.dependency-version }}" = "floor" ]; then
+            pip install "${{ matrix.dependency }}==${{ matrix.floor }}"
+          else
+            pip install --upgrade "${{ matrix.dependency }}"
+          fi
+
+      - name: Run this plugin's contract tests
+        run: |
+          name="${{ matrix.plugin }}"
+          test_name="${name#whytrail-}"
+          test_name="${test_name//-/_}"
+          pytest "tests/plugin_contract/test_${test_name}_plugin.py" -q
+
+  benchmarks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Run performance benchmarks (informational, not a merge gate yet)
+        run: pytest benchmarks/ --benchmark-only
+        continue-on-error: true

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

@@ -0,0 +1,51 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build with mkdocs --strict
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

whytrail-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+# Triggers on a GitHub Release being published, not on every push -- a
+# release is a deliberate, human action, and PyPI publishes are
+# effectively irreversible (a version number can never be reused, even
+# if yanked). Tag the release vX.Y.Z to match pyproject.toml's version.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: pip install build twine
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Validate metadata
+        run: twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # id-token: write is what makes this "trusted publishing" -- PyPI
+      # verifies this workflow's OIDC identity directly, no API token
+      # stored as a repo secret, nothing to rotate or leak.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

whytrail-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg
+site/
+.claude/
+.playwright-mcp/