apifacts-pytest 0.1.0__tar.gz

apifacts_pytest-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# secrets never
+.env
+.env.*
+*.key
+*.pem
+.private_keys/
+
+# python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# node
+node_modules/
+coverage/
+
+# probe runner state (results.jsonl, probe-state.sqlite): transient, never in git
+var/
+
+# local scratch
+.DS_Store
+tmp/
+
+# check() API state (never in git)
+observations.sqlite
+observations.sqlite-*
+
+# kill switch (spec 04): a host-local file, never committed
+ops/KILL

apifacts_pytest-0.1.0/.python-version

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

apifacts_pytest-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.5
+Name: apifacts-pytest
+Version: 0.1.0
+Summary: pytest plugin: a test failing on an HTTP error prints the known facts from the apifacts registry.
+Project-URL: Homepage, https://apifacts.dev
+Project-URL: Repository, https://github.com/Illouminus/apifacts
+Project-URL: Issues, https://github.com/Illouminus/apifacts/issues
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.12
+Requires-Dist: apifacts>=0.1.0
+Requires-Dist: pytest>=8.0
+Description-Content-Type: text/markdown
+
+# apifacts-pytest
+
+A pytest plugin for the [apifacts](https://github.com/Illouminus/apifacts) registry: when a test
+fails on an HTTP error from a registered API, the failure report gets a section with the verified facts
+about that error and their typed fixes. Zero tokens and zero requests until a test fails.
+
+```
+pip install apifacts-pytest      # loads automatically; or: pytest -p apifacts
+```
+
+```
+──────────── Known facts (apifacts, CC BY 4.0) ────────────
+POST api.stripe.com/v1/payment_intents → 400 idempotency_error
+✅ verified:server:prod · Reusing an Idempotency-Key with a different request body returns HTTP 400 …
+   fix: Send header Idempotency-Key = new UUID per distinct request
+   https://github.com/Illouminus/apifacts/blob/main/pages/stripe/idempotency-key-reuse-different-params.md
+```
+
+## What it reads and sends
+
+- Recognized exceptions anywhere in the chain (`__cause__`, `__context__`, exception groups):
+  `requests.HTTPError`, `httpx.HTTPStatusError`, and SDK errors carrying `status_code`/`http_status`
+  and `request.url` (OpenAI, Anthropic and similar clients).
+- Nothing is sent unless the host is in the registry's service list (`GET /v0/services`, cached 24 h
+  in `~/.cache/apifacts/`). Then one `POST /v0/check` per distinct failure, 2 s timeout, at most 20
+  per session; none on a pass; the first network failure turns the plugin off for the session.
+- Sent: method, `scheme://host/path` (no query, fragment, credentials or port; secret-looking path
+  segments and tenant subdomains replaced), status, the first 2 KB of the error body with secrets,
+  e-mail addresses, long ids and URL query strings removed, and the vendor SDK name and version.
+  Never sent: request bodies, headers, cookies, tokens.
+- Any plugin error is swallowed: it never changes a test outcome.
+
+## Configuration
+
+| Setting | Effect |
+|---------|--------|
+| `APIFACTS_DISABLE=1` or `-p no:apifacts` | off |
+| `APIFACTS_ENDPOINT` | registry URL (default `https://apifacts.dev`) |
+| `--apifacts-offline` | no network: answer from the snapshot shipped in the package |
+| `APIFACTS_SNAPSHOT=<dir>` | snapshot directory (`services/*.yaml`, `facts/*/*.yaml`) for offline mode |
+
+Code MIT; facts CC BY 4.0.

apifacts_pytest-0.1.0/README.md

@@ -0,0 +1,42 @@
+# apifacts-pytest
+
+A pytest plugin for the [apifacts](https://github.com/Illouminus/apifacts) registry: when a test
+fails on an HTTP error from a registered API, the failure report gets a section with the verified facts
+about that error and their typed fixes. Zero tokens and zero requests until a test fails.
+
+```
+pip install apifacts-pytest      # loads automatically; or: pytest -p apifacts
+```
+
+```
+──────────── Known facts (apifacts, CC BY 4.0) ────────────
+POST api.stripe.com/v1/payment_intents → 400 idempotency_error
+✅ verified:server:prod · Reusing an Idempotency-Key with a different request body returns HTTP 400 …
+   fix: Send header Idempotency-Key = new UUID per distinct request
+   https://github.com/Illouminus/apifacts/blob/main/pages/stripe/idempotency-key-reuse-different-params.md
+```
+
+## What it reads and sends
+
+- Recognized exceptions anywhere in the chain (`__cause__`, `__context__`, exception groups):
+  `requests.HTTPError`, `httpx.HTTPStatusError`, and SDK errors carrying `status_code`/`http_status`
+  and `request.url` (OpenAI, Anthropic and similar clients).
+- Nothing is sent unless the host is in the registry's service list (`GET /v0/services`, cached 24 h
+  in `~/.cache/apifacts/`). Then one `POST /v0/check` per distinct failure, 2 s timeout, at most 20
+  per session; none on a pass; the first network failure turns the plugin off for the session.
+- Sent: method, `scheme://host/path` (no query, fragment, credentials or port; secret-looking path
+  segments and tenant subdomains replaced), status, the first 2 KB of the error body with secrets,
+  e-mail addresses, long ids and URL query strings removed, and the vendor SDK name and version.
+  Never sent: request bodies, headers, cookies, tokens.
+- Any plugin error is swallowed: it never changes a test outcome.
+
+## Configuration
+
+| Setting | Effect |
+|---------|--------|
+| `APIFACTS_DISABLE=1` or `-p no:apifacts` | off |
+| `APIFACTS_ENDPOINT` | registry URL (default `https://apifacts.dev`) |
+| `--apifacts-offline` | no network: answer from the snapshot shipped in the package |
+| `APIFACTS_SNAPSHOT=<dir>` | snapshot directory (`services/*.yaml`, `facts/*/*.yaml`) for offline mode |
+
+Code MIT; facts CC BY 4.0.

apifacts_pytest-0.1.0/apifacts_pytest/__init__.py

@@ -0,0 +1,3 @@
+"""apifacts-pytest: known facts from the apifacts registry in pytest failure reports."""
+
+__version__ = "0.1.0"

apifacts_pytest-0.1.0/apifacts_pytest/client.py

@@ -0,0 +1,22 @@
+"""The plugin's `Client`: settings from the environment, `--apifacts-offline`, its user agent."""
+
+import pytest
+from apifacts.client.settings import Settings
+from apifacts.client.transport import Client
+
+from apifacts_pytest import __version__
+
+USER_AGENT = f"apifacts-pytest/{__version__} (+https://github.com/Illouminus/apifacts)"
+
+
+def make_client(config: pytest.Config) -> Client | None:
+    """None when the user opted out (`APIFACTS_DISABLE=1`)."""
+    settings = Settings.from_env()
+    if settings.disabled:
+        return None
+    return Client(
+        settings.endpoint,
+        USER_AGENT,
+        offline=bool(config.getoption("apifacts_offline", False)),
+        snapshot=settings.snapshot,
+    )

apifacts_pytest-0.1.0/apifacts_pytest/extract.py

@@ -0,0 +1,155 @@
+"""From a test's exception to a `Signal`: method, URL, status, body excerpt, vendor SDK.
+
+Duck-typed, so neither requests nor httpx is imported: `requests.HTTPError` and
+`httpx.HTTPStatusError` (`.response`, `.request`), SDK errors with `status_code`/`http_status` and
+`request.url` (openai, anthropic, …), aiohttp's `status` + `request_info`. Reading never touches the
+network: an unread streaming body is left alone and `str(exc)` stands in for it.
+"""
+
+import functools
+import importlib.metadata
+import re
+from collections.abc import Iterator
+from typing import Any
+
+from apifacts.client.request import RAW_CHARS, Signal, make_signal
+
+CHAIN_LIMIT = 32
+# Modules whose exceptions say nothing about a vendor SDK.
+HTTP_LIBRARIES = frozenset(
+    {
+        "requests",
+        "httpx",
+        "httpcore",
+        "urllib3",
+        "aiohttp",
+        "urllib",
+        "http",
+        "builtins",
+        "pytest",
+        "_pytest",
+        "apifacts",
+        "apifacts_pytest",
+    }
+)
+
+
+def _attr(obj: Any, name: str) -> Any:
+    """getattr that never raises (httpx raises RuntimeError for an unset `.request`)."""
+    if obj is None:
+        return None
+    try:
+        return getattr(obj, name, None)
+    except Exception:
+        return None
+
+
+def _text(value: Any) -> str | None:
+    try:
+        return value if isinstance(value, str) else (None if value is None else str(value))
+    except Exception:
+        return None
+
+
+def iter_chain(exc: BaseException) -> Iterator[BaseException]:
+    """The exception, its causes and contexts, and group members; breadth-first, each once."""
+    queue: list[Any] = [exc]
+    seen: set[int] = set()
+    while queue and len(seen) < CHAIN_LIMIT:
+        current = queue.pop(0)
+        if not isinstance(current, BaseException) or id(current) in seen:
+            continue
+        seen.add(id(current))
+        yield current
+        if isinstance(current, BaseExceptionGroup):
+            queue.extend(current.exceptions)
+        queue.extend((current.__cause__, current.__context__))
+
+
+def _status(*candidates: Any) -> int | None:
+    for value in candidates:
+        if isinstance(value, int) and not isinstance(value, bool) and 100 <= value <= 599:
+            return value
+    return None
+
+
+def _body(exc: BaseException, response: Any) -> str | None:
+    # requests keeps `_content = False` until a streamed body is consumed; reading it would block
+    # on the socket. httpx raises ResponseNotRead instead, which _attr turns into None.
+    if response is not None and _attr(response, "_content") is not False:
+        content = _attr(response, "content")
+        if isinstance(content, bytes | bytearray):
+            text = bytes(content[: RAW_CHARS * 4]).decode("utf-8", "replace")
+        else:
+            text = _text(_attr(response, "text"))
+        if text and text.strip():
+            return text
+    http_body = _attr(exc, "http_body")  # stripe-style SDKs
+    if isinstance(http_body, bytes | bytearray):
+        http_body = bytes(http_body[: RAW_CHARS * 4]).decode("utf-8", "replace")
+    if isinstance(http_body, str) and http_body.strip():
+        return http_body
+    return _text(exc)
+
+
+def _signal(exc: BaseException) -> Signal | None:
+    response = _attr(exc, "response")
+    request = _attr(exc, "request") or _attr(response, "request")
+    request_info = _attr(exc, "request_info")
+    status = _status(
+        _attr(response, "status_code"),
+        _attr(exc, "status_code"),
+        _attr(exc, "http_status"),
+        _attr(exc, "status"),
+    )
+    if status is None:
+        return None
+    url = next(
+        (
+            u
+            for u in map(
+                _text, (_attr(request, "url"), _attr(request_info, "url"), _attr(response, "url"))
+            )
+            if u
+        ),
+        None,
+    )
+    if url is None:
+        return None
+    method = _text(_attr(request, "method")) or _text(_attr(request_info, "method"))
+    return make_signal(
+        url, method=method, status=status, body=_body(exc, response), sdk=sdk_context(exc)
+    )
+
+
+@functools.cache
+def _distributions() -> dict[str, list[str]]:
+    return importlib.metadata.packages_distributions()
+
+
+def sdk_context(exc: BaseException) -> dict[str, str] | None:
+    """`{package, ecosystem, version}` of the installed distribution that defines the exception."""
+    module = (_text(type(exc).__module__) or "").split(".")[0]
+    if not module or module in HTTP_LIBRARIES or module.startswith("_"):
+        return None
+    try:
+        names = _distributions().get(module) or []
+        if len(set(names)) != 1:  # unknown, or a namespace shared by several distributions
+            return None
+        version = importlib.metadata.version(names[0])
+    except Exception:
+        return None
+    package = re.sub(r"[-_.]+", "-", names[0]).lower()
+    return {"package": package, "ecosystem": "pypi", "version": version}
+
+
+def signal_from_exception(exc: BaseException) -> Signal | None:
+    """The first HTTP error in the chain (outermost first), as a filtered `Signal`."""
+    for current in iter_chain(exc):
+        try:
+            signal = _signal(current)
+        except Exception:
+            signal = None
+        if signal is not None:
+            return signal
+    return None

apifacts_pytest-0.1.0/apifacts_pytest/plugin.py

@@ -0,0 +1,61 @@
+"""pytest hooks: a test failing on an HTTP error from a registered API gets a "Known facts" section.
+
+Nothing happens on a pass. On a failure: extract the signal; if the host is in the registry's
+services list, one `check()` (2 s timeout); render the facts into the report. Any error inside the
+plugin is swallowed: it never changes an outcome or interrupts the run.
+"""
+
+import pytest
+from apifacts.client.render import TITLE, render_section
+from apifacts.client.transport import Client
+
+from apifacts_pytest.client import make_client
+from apifacts_pytest.extract import signal_from_exception
+from apifacts_pytest.render import attach
+
+CLIENT = pytest.StashKey[Client]()
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("apifacts", "apifacts registry")
+    group.addoption(
+        "--apifacts-offline",
+        action="store_true",
+        default=False,
+        help="answer from the fact snapshot shipped with the package; no network",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    try:
+        client = make_client(config)
+    except Exception:
+        return
+    if client is not None:
+        config.stash[CLIENT] = client
+
+
+def annotate(report: pytest.TestReport, exc: BaseException, client: Client) -> None:
+    signal = signal_from_exception(exc)
+    if signal is None or not signal.complete:
+        return
+    host = client.registered_host(signal.host)
+    if host is None:
+        return  # not a registered API: nothing leaves the machine
+    if host != signal.host:
+        signal = signal.with_host(host)  # tenant subdomains are not sent
+    body = render_section(client.check(signal.payload()), signal)
+    if body:
+        attach(report, TITLE, body)
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_runtest_makereport(item: pytest.Item, call: pytest.CallInfo[None]):
+    report = yield
+    client = item.config.stash.get(CLIENT, None)
+    if client is not None and report.failed and call.excinfo is not None:
+        try:
+            annotate(report, call.excinfo.value, client)
+        except Exception:
+            pass
+    return report

apifacts_pytest-0.1.0/apifacts_pytest/render.py

@@ -0,0 +1,17 @@
+"""Putting the section into a pytest report.
+
+As a section of the traceback representation when there is one: it prints right after the
+traceback, is not filtered by `--show-capture`, and travels with the report (junitxml, xdist).
+"""
+
+import pytest
+
+SEPARATOR = "─"
+
+
+def attach(report: pytest.TestReport, title: str, body: str) -> None:
+    longrepr = report.longrepr
+    if hasattr(longrepr, "addsection"):
+        longrepr.addsection(title, body, SEPARATOR)
+    else:
+        report.sections.append((title, body))

apifacts_pytest-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "apifacts-pytest"
+dynamic = ["version"]
+description = "pytest plugin: a test failing on an HTTP error prints the known facts from the apifacts registry."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "apifacts>=0.1.0",
+    "pytest>=8.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.urls]
+Homepage = "https://apifacts.dev"
+Repository = "https://github.com/Illouminus/apifacts"
+Issues = "https://github.com/Illouminus/apifacts/issues"
+
+[project.entry-points.pytest11]
+apifacts = "apifacts_pytest.plugin"  # name used by `-p apifacts` / `-p no:apifacts`
+
+[dependency-groups]
+dev = [
+    "pytest-httpserver>=1.2.0",
+    "requests>=2.32.0",
+]
+
+[tool.uv.sources]
+apifacts = { path = "../..", editable = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "apifacts_pytest/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["apifacts_pytest"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-p", "pytester", "-p", "no:apifacts"]  # inner pytester runs load it from the entry point
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+src = [".", "tests"]  # apifacts_pytest is first-party here; apifacts is a dependency

apifacts_pytest-0.1.0/tests/conftest.py

@@ -0,0 +1,54 @@
+import shutil
+from pathlib import Path
+
+import pytest
+from apifacts.client.offline import Snapshot
+from apifacts.schema.yamlio import load_yaml, plain
+
+FIXTURES = Path(__file__).resolve().parents[3] / "tests" / "fixtures" / "valid"
+FACT_FILE = "fact-idempotency-key-reuse-different-params.yaml"
+SERVICES = {"services": [{"key": "stripe", "hosts": ["api.stripe.com"], "facts": 1}]}
+
+
+def answer() -> dict:
+    """What a spec-03 server returns for the stripe fixture fact."""
+    fact = plain(load_yaml(FIXTURES / FACT_FILE))
+    return {
+        "service": "stripe",
+        "matched_template": {"method": "POST", "path": "/v1/payment_intents"},
+        "facts": [{**fact, "fixes_rendered": ["(server sentence)"]}],
+        "observed": {"status_distribution_30d": {"200": 0.97, "400": 0.03}},
+        "registry": {"version": "2026-10-20", "facts_for_service": 1, "license": "CC-BY-4.0"},
+    }
+
+
+@pytest.fixture
+def plugin_env(monkeypatch, tmp_path):
+    """Isolate every run: own cache dir, no inherited apifacts settings."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "xdg-cache"))
+    for name in ("APIFACTS_DISABLE", "APIFACTS_SNAPSHOT", "APIFACTS_ENDPOINT"):
+        monkeypatch.delenv(name, raising=False)
+    return monkeypatch
+
+
+@pytest.fixture
+def registry(httpserver, plugin_env):
+    """A fake check() server: services list + one stripe fact."""
+    plugin_env.setenv("APIFACTS_ENDPOINT", httpserver.url_for("").rstrip("/"))
+    httpserver.expect_request("/v0/services", method="GET").respond_with_json(SERVICES)
+    return httpserver
+
+
+@pytest.fixture
+def snapshot_dir(tmp_path):
+    root = tmp_path / "snapshot"
+    (root / "services").mkdir(parents=True)
+    (root / "facts" / "stripe").mkdir(parents=True)
+    shutil.copy(FIXTURES / "service-stripe.yaml", root / "services" / "stripe.yaml")
+    shutil.copy(FIXTURES / FACT_FILE, root / "facts" / "stripe" / FACT_FILE)
+    assert Snapshot.load(root).hosts == {"api.stripe.com"}
+    return root
+
+
+def requests_to(httpserver, path):
+    return [req for req, _ in httpserver.log if req.path == path]