pyintent 0.1.0__py3-none-any.whl

pyintent/plugin.py

@@ -0,0 +1,155 @@
+"""pytest plugin — surface pyintent checks as ordinary pytest items.
+
+Registered via the ``pytest11`` entry point but **opt-in**: it does nothing
+unless you enable it with ``--pyintent`` on the command line or ``pyintent =
+true`` under ``[tool.pytest.ini_options]`` (or ``[pytest]``). This keeps a mere
+install of pyintent from changing how unrelated ``pytest`` runs behave —
+without the opt-in, pyintent never imports your application files.
+
+When enabled, for every non-test ``.py`` file that contains specs it collects:
+
+* one item per ``ex`` case,
+* one item per function with ``ensures`` (property test),
+* one item per file for the type check.
+
+Effects/perf are intentionally **not** pytest items (run ``pyintent verify``
+for those). Test files are left to pytest's own collector to avoid importing a
+module twice.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+
+import pytest
+
+from ._discovery import discover_in_module
+from ._loader import import_file
+from .verifier._result import Status
+from .verifier.examples import verify_example_case
+from .verifier.properties import verify_properties
+from .verifier.types import verify_types
+
+
+def pytest_addoption(parser) -> None:
+    group = parser.getgroup("pyintent")
+    group.addoption(
+        "--pyintent", action="store_true", default=False,
+        help="Collect pyintent @spec checks (examples/properties/types) as pytest items.",
+    )
+    parser.addini(
+        "pyintent", "Collect pyintent @spec checks as pytest items.",
+        type="bool", default=False,
+    )
+
+
+def _enabled(config) -> bool:
+    try:
+        if config.getoption("--pyintent"):
+            return True
+    except (ValueError, KeyError):
+        pass
+    return bool(config.getini("pyintent"))
+
+
+def _pkg_dir() -> str:
+    return os.path.dirname(os.path.abspath(__file__))
+
+
+def _looks_like_specs(path: Path) -> bool:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+    if "pyintent" not in text:
+        return False
+    return "@spec(" in text or "module_spec(" in text or "package_spec(" in text
+
+
+def pytest_collect_file(file_path: Path, parent):  # type: ignore[override]
+    if not _enabled(parent.config):
+        return None
+    if file_path.suffix != ".py":
+        return None
+
+    # Never collect pyintent's own source or installed third-party code.
+    resolved = str(file_path.resolve())
+    if resolved.startswith(_pkg_dir()) or "site-packages" in resolved:
+        return None
+
+    # Leave files matching pytest's own python_files patterns to pytest.
+    patterns = parent.config.getini("python_files") or ["test_*.py", "*_test.py"]
+    if any(fnmatch.fnmatch(file_path.name, pat) for pat in patterns):
+        return None
+
+    if not _looks_like_specs(file_path):
+        return None
+
+    return PyIntentFile.from_parent(parent, path=file_path)
+
+
+class _CheckFailure(Exception):
+    """Carries a failing/erroring CheckResult to repr_failure."""
+
+    def __init__(self, result) -> None:
+        super().__init__(result.summary)
+        self.result = result
+
+
+class PyIntentFile(pytest.File):
+    def collect(self):
+        try:
+            module = import_file(self.path)
+        except Exception as exc:  # noqa: BLE001
+            raise self.CollectError(f"pyintent: failed to import {self.path}: {exc}") from exc
+
+        targets = discover_in_module(module)
+        for t in targets:
+            sp = t.spec
+            base = sp.target_name
+            for ex in sp.examples:
+                yield PyIntentItem.from_parent(
+                    self, name=f"{base}::ex[{ex.raw}]",
+                    thunk=lambda t=t, ex=ex: verify_example_case(t, ex),
+                )
+            if sp.ensures:
+                yield PyIntentItem.from_parent(
+                    self, name=f"{base}::properties",
+                    thunk=lambda t=t: _first(verify_properties(t)),
+                )
+
+        yield PyIntentItem.from_parent(
+            self, name=f"{self.path.stem}::types",
+            thunk=lambda: _first(verify_types(str(self.path))),
+        )
+
+
+def _first(results):
+    from .verifier._result import CheckResult
+    if results:
+        return results[0]
+    return CheckResult("", "", Status.SKIPPED, summary="nothing to check")
+
+
+class PyIntentItem(pytest.Item):
+    def __init__(self, *, name, parent, thunk):
+        super().__init__(name, parent)
+        self._thunk = thunk
+
+    def runtest(self) -> None:
+        result = self._thunk()
+        if result.status is Status.SKIPPED:
+            pytest.skip(result.summary or "skipped")
+        if result.status in (Status.FAIL, Status.ERROR):
+            raise _CheckFailure(result)
+
+    def repr_failure(self, excinfo, style=None):  # type: ignore[override]
+        if isinstance(excinfo.value, _CheckFailure):
+            r = excinfo.value.result
+            return r.detail or r.summary or "pyintent check failed"
+        return super().repr_failure(excinfo)
+
+    def reportinfo(self):
+        return self.path, 0, self.name

pyintent/prompt.py

@@ -0,0 +1,142 @@
+"""The canonical pyintent authoring guide + writers for AI-tool prompt files.
+
+``init`` writes this reference into the well-known prompt files that coding
+agents read (AGENTS.md, CLAUDE.md, Copilot, Cursor). ``prompt`` prints it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+REFERENCE = '''\
+# pyintent — writing specifications
+
+`pyintent` is a **pure verifier**. You (the AI implementer) write the
+implementation; the human (or you) writes `@spec` decorators describing
+*intent*. pyintent then checks that your implementation satisfies the spec.
+pyintent NEVER generates or edits implementation code, and NEVER calls an LLM.
+
+Your job: **make the implementation satisfy every `@spec`.** Run
+`pyintent verify <path>` (or `pytest --pyintent`) and fix real code until checks
+pass. Do not weaken a spec to make it pass unless explicitly told to.
+
+## The decorator
+
+```python
+from pyintent import spec, pure, reads, writes, network, io, async_, throws, Perf
+
+@spec(
+    intent="One-line description of what this does and why.",
+    where=["n >= 0"],                 # preconditions (Python expressions)
+    ensures=["result >= 0",           # postconditions; `result` = return value
+             "result == n * 2"],
+    effects=[pure],                   # see effects below
+    ex=["(0,) -> 0",                  # runnable examples; see format below
+        "(3,) -> 6",
+        "(-1,) -> raises ValueError"],
+    perf=Perf(time="O(n)"),           # optional, advisory
+)
+def double_nonneg(n: int) -> int:
+    if n < 0:
+        raise ValueError("n must be >= 0")
+    return n * 2
+```
+
+`@spec` must be the **outermost** decorator and returns the target unchanged —
+it only attaches metadata, so it never changes runtime behaviour.
+
+## Example format: `"(args) -> expected"`
+
+- Left side is a tuple of call arguments: `"(1, 2)"`, `"('hi',)"` (one-element
+  tuples need the trailing comma), `"()"` for no args.
+- `->` separates input from expected output.
+- Right side is one of:
+  - a Python literal/expression evaluated in the target's module: `42`, `[1,2]`,
+    `"ok"`, `MyEnum.A`
+  - `raises ExceptionType` — the call must raise that type (or a subclass)
+  - `_` — wildcard: any return value is accepted (only that it does not raise)
+- Arguments and expected values are evaluated at verify time in the module's
+  namespace, so you may reference names defined in the module.
+
+## Effects (checked where possible)
+
+- `pure` — no I/O, no global state, no randomness. **Verified** by AST: calls
+  into `os/sys/random/requests/httpx/socket/subprocess/urllib/time/...` and
+  builtins `print/open/input/exec/eval` are violations, as are `global`/
+  `nonlocal` writes. (Shallow: it does not follow calls into helpers.)
+- `async_` — **verified**: the function must be `async def`.
+- `throws(ExcA, ExcB)` — **verified** by AST: every exception type you `raise`
+  explicitly must be declared here.
+- `reads(...)`, `writes(...)`, `network(...)`, `io` — recorded as documentation
+  in v0.1 (declaration-only, not yet enforced).
+
+A function may declare multiple effects, e.g. `effects=[reads("db"), throws(KeyError)]`.
+
+## Properties (`where` + `ensures`)
+
+For **pure** functions, pyintent uses Hypothesis to generate inputs from your
+type hints, filters them through `where`, and asserts every `ensures`
+expression. `ensures` may reference parameters and `result`. Effectful or
+un-annotatable functions are skipped (not failed).
+
+## Methods, classes, modules
+
+- On methods, examples exclude `self`/`cls` from the argument tuple. Instance
+  methods and properties are **skipped** for example/property execution in v0.1
+  (planned for v0.2); their specs are still validated structurally.
+- Properties: use `()` as the example input and do not use `where`.
+- `@spec` on a **class** records invariants (documentation in v0.1).
+- `module_spec(...)` / `package_spec(...)` record module/package intent.
+- Abstract methods may carry a `@spec` to define the contract subclasses must meet.
+
+## Workflow
+
+1. Read the specs. 2. Implement. 3. Run `pyintent verify <path>` (or
+`pytest --pyintent`). 4. Read failures (they show expected vs actual). 5. Fix the implementation.
+6. Repeat until green. Treat the spec as the source of truth.
+'''
+
+
+def get_reference() -> str:
+    return REFERENCE
+
+
+_HEADER = "<!-- pyintent:begin -->"
+_FOOTER = "<!-- pyintent:end -->"
+_BLOCK = f"{_HEADER}\n{REFERENCE}\n{_FOOTER}\n"
+
+#: Files coding agents commonly read, relative to project root.
+PROMPT_FILES = (
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".github/copilot-instructions.md",
+    ".cursor/rules/pyintent.md",
+)
+
+
+def _upsert(path: Path, block: str) -> str:
+    """Insert or replace the pyintent block in ``path``. Returns action taken."""
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(block, encoding="utf-8")
+        return "created"
+
+    text = path.read_text(encoding="utf-8")
+    if _HEADER in text and _FOOTER in text:
+        pre = text[: text.index(_HEADER)]
+        post = text[text.index(_FOOTER) + len(_FOOTER):]
+        path.write_text(pre + block.rstrip("\n") + post, encoding="utf-8")
+        return "updated"
+
+    sep = "" if text.endswith("\n\n") else ("\n" if text.endswith("\n") else "\n\n")
+    path.write_text(text + sep + block, encoding="utf-8")
+    return "appended"
+
+
+def write_prompt_files(root: str | Path = ".") -> dict[str, str]:
+    """Write/refresh the pyintent guide into all known prompt files."""
+    root = Path(root)
+    actions: dict[str, str] = {}
+    for rel in PROMPT_FILES:
+        actions[rel] = _upsert(root / rel, _BLOCK)
+    return actions

pyintent/verifier/__init__.py

@@ -0,0 +1,64 @@
+"""Verifier orchestration.
+
+``run_all`` discovers every spec in a module and runs the selected verifiers.
+``types`` runs once per source file; the other verifiers run per callable.
+"""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+from .._spec import SpecLevel
+from .._discovery import SpecTarget, discover_in_module
+from ._result import CheckResult, Status
+from .effects import verify_effects
+from .examples import verify_examples
+from .properties import verify_properties
+from .types import verify_types
+
+ALL_VERIFIERS = ("examples", "properties", "types", "effects")
+
+#: Levels with no executable verification in v0.1 (specs stored only).
+_NON_EXECUTABLE = {SpecLevel.CLASS, SpecLevel.MODULE, SpecLevel.PACKAGE}
+
+
+def run_targets(targets: list[SpecTarget], which: set[str] | None = None) -> list[CheckResult]:
+    which = set(which) if which else set(ALL_VERIFIERS)
+    results: list[CheckResult] = []
+
+    for t in targets:
+        if t.spec.level in _NON_EXECUTABLE:
+            continue
+        if "examples" in which:
+            results.extend(verify_examples(t))
+        if "properties" in which:
+            results.extend(verify_properties(t))
+        if "effects" in which:
+            results.extend(verify_effects(t))
+
+    if "types" in which:
+        seen: set[str] = set()
+        for t in targets:
+            if t.filename and t.filename not in seen:
+                seen.add(t.filename)
+                results.extend(verify_types(t.filename))
+
+    return results
+
+
+def run_all(module: ModuleType, which: set[str] | None = None) -> list[CheckResult]:
+    return run_targets(discover_in_module(module), which)
+
+
+__all__ = [
+    "ALL_VERIFIERS",
+    "CheckResult",
+    "Status",
+    "SpecTarget",
+    "run_all",
+    "run_targets",
+    "verify_examples",
+    "verify_properties",
+    "verify_effects",
+    "verify_types",
+]

pyintent/verifier/_result.py

@@ -0,0 +1,42 @@
+"""The result type produced by every verifier."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Status(Enum):
+    PASS = "pass"
+    FAIL = "fail"
+    SKIPPED = "skipped"
+    ERROR = "error"  # the verifier could not run (e.g. bad spec value)
+
+
+@dataclass
+class CheckResult:
+    verifier: str  # "examples" | "properties" | "types" | "effects"
+    target: str  # qualname of the spec'd thing
+    status: Status
+    summary: str = ""  # one-line outcome
+    detail: str = ""  # full, paste-ready detail for a repair prompt
+    label: str = ""  # sub-identifier, e.g. the ex case raw string
+
+    @property
+    def ok(self) -> bool:
+        return self.status in (Status.PASS, Status.SKIPPED)
+
+    @property
+    def name(self) -> str:
+        base = f"{self.target}::{self.verifier}"
+        return f"{base}[{self.label}]" if self.label else base
+
+    def to_dict(self) -> dict:
+        return {
+            "verifier": self.verifier,
+            "target": self.target,
+            "status": self.status.value,
+            "summary": self.summary,
+            "detail": self.detail,
+            "label": self.label,
+        }

pyintent/verifier/effects.py

@@ -0,0 +1,169 @@
+"""Effects verifier — shallow AST checks of declared effects.
+
+In v0.1 three effects are checked:
+
+* ``pure``    — no calls into known impure modules/builtins, no global/nonlocal writes
+* ``async_``  — the function really is a coroutine
+* ``throws``  — every explicitly raised exception type is declared
+
+All other effects are recorded as declaration-only. The purity check is
+intentionally shallow (it does not follow calls into helpers) and reports the
+specific offending lines.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+
+from .._effects import EffectKind
+from .._discovery import SpecTarget
+from ._result import CheckResult, Status
+
+_IMPURE_BUILTINS = {"print", "open", "input", "exec", "eval", "breakpoint"}
+_IMPURE_ROOTS = {
+    "os", "sys", "random", "requests", "httpx", "socket",
+    "subprocess", "urllib", "time", "shutil",
+}
+
+
+def _root_name(node: ast.AST) -> str | None:
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    if isinstance(node, ast.Name):
+        return node.id
+    return None
+
+
+class _PurityVisitor(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.violations: list[tuple[int, str]] = []
+
+    def visit_Global(self, node: ast.Global) -> None:
+        self.violations.append((node.lineno, "global statement"))
+
+    def visit_Nonlocal(self, node: ast.Nonlocal) -> None:
+        self.violations.append((node.lineno, "nonlocal statement"))
+
+    def visit_Call(self, node: ast.Call) -> None:
+        f = node.func
+        if isinstance(f, ast.Name) and f.id in _IMPURE_BUILTINS:
+            self.violations.append((node.lineno, f"call to {f.id}()"))
+        elif isinstance(f, ast.Attribute):
+            root = _root_name(f)
+            if root in _IMPURE_ROOTS:
+                self.violations.append((node.lineno, f"call into '{root}'"))
+        self.generic_visit(node)
+
+
+class _RaiseCollector(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.raised: list[tuple[int, str]] = []
+
+    def visit_Raise(self, node: ast.Raise) -> None:
+        exc = node.exc
+        if exc is None:  # bare re-raise
+            return
+        target = exc.func if isinstance(exc, ast.Call) else exc
+        name = None
+        if isinstance(target, ast.Name):
+            name = target.id
+        elif isinstance(target, ast.Attribute):
+            name = target.attr
+        if name:
+            self.raised.append((node.lineno, name))
+        self.generic_visit(node)
+
+
+def _get_ast(target: SpecTarget) -> ast.AST | None:
+    fn = target.invoke
+    if fn is None:
+        return None
+    try:
+        src = textwrap.dedent(inspect.getsource(fn))
+    except (OSError, TypeError):
+        return None
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return None
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            return node
+    return None
+
+
+def verify_effects(target: SpecTarget) -> list[CheckResult]:
+    sp = target.spec
+    name = sp.target_name
+    kinds = {e.kind for e in sp.effects}
+    if not kinds:
+        return []
+
+    results: list[CheckResult] = []
+    fn_ast = None
+    if kinds & {EffectKind.PURE, EffectKind.THROWS}:
+        fn_ast = _get_ast(target)
+
+    if EffectKind.PURE in kinds:
+        results.append(_check_pure(name, fn_ast))
+    if EffectKind.ASYNC in kinds:
+        results.append(_check_async(name, sp.is_async))
+    if EffectKind.THROWS in kinds:
+        results.append(_check_throws(name, sp, fn_ast))
+
+    declared_only = kinds - {EffectKind.PURE, EffectKind.ASYNC, EffectKind.THROWS}
+    if declared_only:
+        labels = ", ".join(sorted(k.value for k in declared_only))
+        results.append(
+            CheckResult("effects", name, Status.SKIPPED,
+                        summary=f"declaration-only in v0.1: {labels}")
+        )
+    return results
+
+
+def _check_pure(name: str, fn_ast) -> CheckResult:
+    if fn_ast is None:
+        return CheckResult("effects", name, Status.SKIPPED,
+                           summary="could not read source for purity check", label="pure")
+    v = _PurityVisitor()
+    v.visit(fn_ast)
+    if not v.violations:
+        return CheckResult("effects", name, Status.PASS, summary="pure", label="pure")
+    lines = "\n".join(f"  line {ln}: {what}" for ln, what in v.violations)
+    detail = f"{name} is declared pure but performs side effects:\n{lines}"
+    return CheckResult("effects", name, Status.FAIL,
+                       summary=f"declared pure but has {len(v.violations)} side effect(s)",
+                       detail=detail, label="pure")
+
+
+def _check_async(name: str, is_async: bool) -> CheckResult:
+    if is_async:
+        return CheckResult("effects", name, Status.PASS, summary="async", label="async")
+    return CheckResult("effects", name, Status.FAIL,
+                       summary="declared async_ but is not a coroutine function",
+                       detail=f"{name} declares async_ but was not defined with 'async def'.",
+                       label="async")
+
+
+def _check_throws(name: str, sp, fn_ast) -> CheckResult:
+    if fn_ast is None:
+        return CheckResult("effects", name, Status.SKIPPED,
+                           summary="could not read source for throws check", label="throws")
+    declared = {e.__name__ for e in sp.thrown_exceptions}
+    c = _RaiseCollector()
+    c.visit(fn_ast)
+    undeclared = [(ln, nm) for ln, nm in c.raised if nm not in declared]
+    if not undeclared:
+        return CheckResult("effects", name, Status.PASS,
+                           summary=f"raises only declared: {', '.join(sorted(declared))}",
+                           label="throws")
+    lines = "\n".join(f"  line {ln}: raises {nm} (not in throws(...))" for ln, nm in undeclared)
+    detail = (
+        f"{name} raises exception types not declared in throws(...):\n{lines}\n"
+        f"  declared: {', '.join(sorted(declared)) or '(none)'}"
+    )
+    return CheckResult("effects", name, Status.FAIL,
+                       summary=f"{len(undeclared)} undeclared raise(s)",
+                       detail=detail, label="throws")