pyintent 0.1.0__py3-none-any.whl

pyintent/_perf.py

@@ -0,0 +1,49 @@
+"""Performance declaration for a spec.
+
+In v0.1 ``Perf`` is *stored only* — pyintent records the declared complexity but
+does not measure or verify it. Measurement is planned for v0.2.
+"""
+
+from __future__ import annotations
+
+from ._errors import PyIntentSpecError
+
+_ALLOWED = ("time", "space")
+
+
+class Perf:
+    """Declared algorithmic complexity, e.g. ``Perf(time="O(log n)", space="O(1)")``."""
+
+    __slots__ = ("time", "space")
+
+    def __init__(self, **kwargs: str) -> None:
+        unknown = set(kwargs) - set(_ALLOWED)
+        if unknown:
+            raise PyIntentSpecError(
+                f"Perf() got unexpected keyword(s): {', '.join(sorted(unknown))}. "
+                f"Allowed: {', '.join(_ALLOWED)}"
+            )
+        time = kwargs.get("time")
+        space = kwargs.get("space")
+        if time is None and space is None:
+            raise PyIntentSpecError("Perf() requires at least one of time= or space=")
+        for name, val in (("time", time), ("space", space)):
+            if val is not None and (not isinstance(val, str) or not val.strip()):
+                raise PyIntentSpecError(
+                    f"Perf {name}= must be a non-empty string, got {val!r}"
+                )
+        self.time = time
+        self.space = space
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.time is not None:
+            parts.append(f"time={self.time!r}")
+        if self.space is not None:
+            parts.append(f"space={self.space!r}")
+        return f"Perf({', '.join(parts)})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Perf):
+            return NotImplemented
+        return self.time == other.time and self.space == other.space

pyintent/_spec.py

@@ -0,0 +1,375 @@
+"""The ``@spec`` decorator and its data model.
+
+``@spec`` attaches a :class:`PyIntentSpec` to the target as ``__pyintent_spec__``
+and returns the target **unchanged** — there is zero runtime overhead. All
+validation happens eagerly at decoration time so a malformed spec fails on import.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+from ._effects import Effect, EffectKind
+from ._errors import PyIntentSpecError
+from ._parser import Example, parse_example
+from ._perf import Perf
+
+SPEC_ATTR = "__pyintent_spec__"
+
+_IMPURE_KINDS = {
+    EffectKind.READS,
+    EffectKind.WRITES,
+    EffectKind.NETWORK,
+    EffectKind.IO,
+    EffectKind.ASYNC,
+}
+
+
+class SpecLevel(Enum):
+    FUNCTION = "function"
+    METHOD = "method"
+    CLASSMETHOD = "classmethod"
+    STATICMETHOD = "staticmethod"
+    PROPERTY = "property"
+    ABSTRACT = "abstract method"
+    CLASS = "class"
+    MODULE = "module"
+    PACKAGE = "package"
+
+
+#: Callable levels that accept call-time conditions and examples.
+_CALLABLE_LEVELS = {
+    SpecLevel.FUNCTION,
+    SpecLevel.METHOD,
+    SpecLevel.CLASSMETHOD,
+    SpecLevel.STATICMETHOD,
+    SpecLevel.ABSTRACT,
+    SpecLevel.PROPERTY,
+}
+
+#: Which kwargs each level accepts (``intent`` is always required, handled apart).
+_ALLOWED_FIELDS: dict[SpecLevel, set[str]] = {
+    SpecLevel.FUNCTION: {"where", "ensures", "effects", "perf", "ex"},
+    SpecLevel.METHOD: {"where", "ensures", "effects", "perf", "ex"},
+    SpecLevel.CLASSMETHOD: {"where", "ensures", "effects", "perf", "ex"},
+    SpecLevel.STATICMETHOD: {"where", "ensures", "effects", "perf", "ex"},
+    SpecLevel.ABSTRACT: {"where", "ensures", "effects", "perf", "ex"},
+    SpecLevel.PROPERTY: {"ensures", "effects", "perf", "ex"},
+    SpecLevel.CLASS: {"effects", "invariants"},
+    SpecLevel.MODULE: {"effects", "invariants"},
+    SpecLevel.PACKAGE: {"effects", "invariants", "modules"},
+}
+
+
+@dataclass(frozen=True)
+class Invariant:
+    """A class/module/package invariant.
+
+    ``is_expr`` is True when the text compiles as a Python expression (and is
+    therefore checkable); otherwise it is treated as natural-language docs.
+    """
+
+    text: str
+    is_expr: bool
+
+
+@dataclass
+class PyIntentSpec:
+    level: SpecLevel
+    intent: str
+    target_name: str
+    is_async: bool = False
+    where: list[str] = field(default_factory=list)
+    ensures: list[str] = field(default_factory=list)
+    effects: list[Effect] = field(default_factory=list)
+    perf: Perf | None = None
+    examples: list[Example] = field(default_factory=list)
+    invariants: list[Invariant] = field(default_factory=list)
+    modules: list[str] = field(default_factory=list)
+
+    @property
+    def declares_pure(self) -> bool:
+        return any(e.kind is EffectKind.PURE for e in self.effects)
+
+    @property
+    def is_verifiable_pure(self) -> bool:
+        """True when property-based testing is safe (no impure declared effects)."""
+        return not ({e.kind for e in self.effects} & _IMPURE_KINDS)
+
+    @property
+    def thrown_exceptions(self) -> tuple[type[BaseException], ...]:
+        result: list[type[BaseException]] = []
+        for e in self.effects:
+            if e.kind is EffectKind.THROWS:
+                result.extend(e.exceptions)
+        return tuple(result)
+
+
+# --------------------------------------------------------------------------- #
+# Validation helpers
+# --------------------------------------------------------------------------- #
+def _require_intent(intent: object) -> str:
+    if not isinstance(intent, str) or not intent.strip():
+        raise PyIntentSpecError("intent= is required and must be a non-empty string")
+    return intent
+
+
+def _validate_conditions(name: str, conditions: object) -> list[str]:
+    if conditions is None:
+        return []
+    if not isinstance(conditions, (list, tuple)):
+        raise PyIntentSpecError(f"{name}= must be a list of strings")
+    result: list[str] = []
+    for c in conditions:
+        if not isinstance(c, str) or not c.strip():
+            raise PyIntentSpecError(f"each {name} entry must be a non-empty string, got {c!r}")
+        try:
+            compile(c, f"<{name}>", "eval")
+        except (SyntaxError, ValueError) as e:
+            msg = e.msg if isinstance(e, SyntaxError) else str(e)
+            raise PyIntentSpecError(
+                f"{name} condition {c!r} is not a valid Python expression: {msg}"
+            ) from e
+        result.append(c)
+    return result
+
+
+def _validate_effects(effects: object) -> list[Effect]:
+    if effects is None:
+        return []
+    if not isinstance(effects, (list, tuple)):
+        raise PyIntentSpecError("effects= must be a list of Effect objects")
+    for e in effects:
+        if not isinstance(e, Effect):
+            raise PyIntentSpecError(
+                f"effects must be Effect objects (pure, reads(...), writes(...), "
+                f"network(...), io, async_, throws(...)); got {e!r}"
+            )
+    return list(effects)
+
+
+def _validate_perf(perf: object) -> Perf | None:
+    if perf is None:
+        return None
+    if not isinstance(perf, Perf):
+        raise PyIntentSpecError("perf= must be a Perf object, e.g. Perf(time='O(n)')")
+    return perf
+
+
+def _validate_examples(ex: object) -> list[Example]:
+    if ex is None:
+        return []
+    if not isinstance(ex, (list, tuple)):
+        raise PyIntentSpecError("ex= must be a list of example strings")
+    return [parse_example(e) for e in ex]
+
+
+def parse_invariant(text: object) -> Invariant:
+    if not isinstance(text, str) or not text.strip():
+        raise PyIntentSpecError("each invariant must be a non-empty string")
+    try:
+        compile(text, "<invariant>", "eval")
+        is_expr = True
+    except SyntaxError:
+        is_expr = False
+    return Invariant(text=text, is_expr=is_expr)
+
+
+def _validate_invariants(invariants: object) -> list[Invariant]:
+    if invariants is None:
+        return []
+    if not isinstance(invariants, (list, tuple)):
+        raise PyIntentSpecError("invariants= must be a list of strings")
+    return [parse_invariant(i) for i in invariants]
+
+
+def _reject_disallowed(level: SpecLevel, provided: dict[str, Any]) -> None:
+    allowed = _ALLOWED_FIELDS[level]
+    for name, value in provided.items():
+        if value and name not in allowed:
+            allowed_list = ", ".join(sorted(allowed)) or "(none)"
+            raise PyIntentSpecError(
+                f"{name}= is not valid on a {level.value} spec. "
+                f"Allowed fields: intent, {allowed_list}."
+            )
+
+
+# --------------------------------------------------------------------------- #
+# Target introspection
+# --------------------------------------------------------------------------- #
+def _underlying(target: Any) -> Any:
+    if isinstance(target, (classmethod, staticmethod)):
+        return target.__func__
+    if isinstance(target, property):
+        return target.fget
+    return target
+
+
+def _detect_level(target: Any) -> SpecLevel:
+    if isinstance(target, classmethod):
+        return SpecLevel.CLASSMETHOD
+    if isinstance(target, staticmethod):
+        return SpecLevel.STATICMETHOD
+    if isinstance(target, property):
+        return SpecLevel.PROPERTY
+    if isinstance(target, type):
+        return SpecLevel.CLASS
+    if getattr(target, "__isabstractmethod__", False):
+        return SpecLevel.ABSTRACT
+    if inspect.isfunction(target):
+        qualname = getattr(target, "__qualname__", "")
+        if "." in qualname:
+            parent = qualname.rsplit(".", 1)[0]
+            if not parent.endswith("<locals>"):
+                return SpecLevel.METHOD
+        return SpecLevel.FUNCTION
+    raise PyIntentSpecError(
+        f"@spec can only decorate functions, methods, or classes; got {target!r}"
+    )
+
+
+def _target_name(target: Any, underlying: Any) -> str:
+    if isinstance(target, type):
+        return target.__qualname__
+    name = getattr(underlying, "__qualname__", None) or getattr(underlying, "__name__", None)
+    return name or repr(target)
+
+
+def _attach(target: Any, underlying: Any, ps: PyIntentSpec) -> None:
+    holder = underlying if underlying is not None else target
+    try:
+        setattr(holder, SPEC_ATTR, ps)
+    except (AttributeError, TypeError) as e:  # pragma: no cover
+        raise PyIntentSpecError(
+            f"could not attach spec to {ps.target_name}: {e}"
+        ) from e
+
+
+# --------------------------------------------------------------------------- #
+# The decorator
+# --------------------------------------------------------------------------- #
+def spec(
+    *,
+    intent: str,
+    where: list[str] | None = None,
+    ensures: list[str] | None = None,
+    effects: list[Effect] | None = None,
+    perf: Perf | None = None,
+    ex: list[str] | None = None,
+    invariants: list[str] | None = None,
+) -> Callable[[Any], Any]:
+    """Attach an intent specification to a function, method, or class.
+
+    ``@spec`` must be the **outermost** decorator. It returns the target
+    **unchanged** — there is zero runtime overhead. All validation happens
+    eagerly at decoration time so a malformed spec fails on import.
+
+    Parameters
+    ----------
+    intent:
+        Required. One-line description of what the target does and why.
+    where:
+        Preconditions — Python expression strings evaluated over the input
+        parameters.  Example: ``["n >= 0", "isinstance(n, int)"]``.
+    ensures:
+        Postconditions — Python expression strings evaluated over input
+        parameters and ``result`` (the return value).
+        Example: ``["result >= 0", "result == abs(x)"]``.
+    effects:
+        Declared side-effects.  Use the helpers: ``pure``, ``reads(...)``,
+        ``writes(...)``, ``network(...)``, ``io``, ``async_``,
+        ``throws(...)``.  Example: ``[reads("db"), throws(NotFoundError)]``.
+    perf:
+        Advisory complexity declaration.  Example: ``Perf(time="O(n log n)")``.
+        Recorded but not measured in v0.1.
+    ex:
+        Runnable examples in ``"(args) -> expected"`` format.
+        Example: ``["(1, 2) -> 3", "(0,) -> raises ValueError", "() -> _"]``.
+        Values are evaluated in the target module's global namespace.
+    invariants:
+        Class/module-level invariants (plain text or Python expressions).
+        Valid only on class, module, and package specs.
+
+    Returns
+    -------
+    Callable[[Any], Any]
+        A decorator that attaches the spec and returns the target unchanged.
+
+    Raises
+    ------
+    PyIntentSpecError
+        If ``intent`` is empty, any expression is syntactically invalid, an
+        unsupported field is used for the target level, or an ``ex`` entry
+        is malformed.
+
+    See Also
+    --------
+    ``pyintent prompt`` : print the full spec-authoring reference guide.
+    ``get_spec``        : retrieve a spec attached to a target.
+    """
+    intent = _require_intent(intent)
+
+    def decorate(target: Any) -> Any:
+        level = _detect_level(target)
+        underlying = _underlying(target)
+        if underlying is None:
+            raise PyIntentSpecError(
+                "@spec on a property requires a getter (the property has no fget)"
+            )
+
+        _reject_disallowed(
+            level,
+            {
+                "where": where,
+                "ensures": ensures,
+                "perf": perf,
+                "ex": ex,
+                "invariants": invariants,
+            },
+        )
+
+        is_async = bool(
+            inspect.iscoroutinefunction(underlying)
+            or inspect.isasyncgenfunction(underlying)
+        )
+
+        ps = PyIntentSpec(
+            level=level,
+            intent=intent,
+            target_name=_target_name(target, underlying),
+            is_async=is_async,
+            where=_validate_conditions("where", where),
+            ensures=_validate_conditions("ensures", ensures),
+            effects=_validate_effects(effects),
+            perf=_validate_perf(perf),
+            examples=_validate_examples(ex),
+            invariants=_validate_invariants(invariants),
+        )
+        _attach(target, underlying, ps)
+        return target
+
+    return decorate
+
+
+def get_spec(obj: Any) -> PyIntentSpec | None:
+    """Return the :class:`PyIntentSpec` attached to ``obj``, or ``None``.
+
+    Works for functions, methods, classmethods, staticmethods, properties,
+    and classes decorated with :func:`spec`.
+
+    Parameters
+    ----------
+    obj:
+        Any Python object that may have a spec attached.
+
+    Returns
+    -------
+    PyIntentSpec | None
+        The attached spec, or ``None`` if ``obj`` was not decorated with
+        ``@spec``.
+    """
+    underlying = _underlying(obj)
+    return getattr(underlying, SPEC_ATTR, None)

pyintent/cli.py

@@ -0,0 +1,240 @@
+"""``pyintent`` command-line interface.
+
+Commands
+--------
+* ``pyintent init``                 write the agent guide into prompt files
+* ``pyintent prompt``               print the agent guide to stdout
+* ``pyintent check  PATH``          validate spec structure (imports modules)
+* ``pyintent verify PATH [--json]`` run the verifiers
+
+Exit codes: ``0`` all good, ``1`` verification/spec failures, ``2`` usage or
+load error (could not import a target, malformed spec at import time).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from ._errors import PyIntentSpecError
+from ._loader import import_file, iter_python_files
+from ._module_spec import MODULE_ATTR
+from ._spec import SpecLevel, get_spec
+from . import prompt as _prompt
+from .verifier import ALL_VERIFIERS, run_all
+from .verifier._result import Status
+
+_STATUS_STYLE = {
+    Status.PASS: ("PASS", "green"),
+    Status.FAIL: ("FAIL", "red"),
+    Status.ERROR: ("ERR ", "red"),
+    Status.SKIPPED: ("SKIP", "yellow"),
+}
+
+
+# --------------------------------------------------------------------------- #
+# config
+# --------------------------------------------------------------------------- #
+def _load_config(start: Path) -> dict:
+    try:
+        import tomllib
+    except ModuleNotFoundError:  # pragma: no cover - py<3.11
+        return {}
+    for directory in [start, *start.parents]:
+        cfg = directory / "pyproject.toml"
+        if cfg.is_file():
+            try:
+                data = tomllib.loads(cfg.read_text(encoding="utf-8"))
+            except Exception:
+                return {}
+            return data.get("tool", {}).get("pyintent", {}) or {}
+    return {}
+
+
+def _collect_modules(path: Path):
+    """Import every target file under ``path``. Returns (modules, load_errors)."""
+    modules = []
+    errors: list[tuple[Path, BaseException]] = []
+    for f in iter_python_files(path):
+        try:
+            modules.append((f, import_file(f)))
+        except PyIntentSpecError as e:
+            errors.append((f, e))
+        except BaseException as e:  # noqa: BLE001 - report, keep going
+            errors.append((f, e))
+    return modules, errors
+
+
+# --------------------------------------------------------------------------- #
+# reporting
+# --------------------------------------------------------------------------- #
+def _print_results(results, *, show_detail=True) -> dict[Status, int]:
+    counts: dict[Status, int] = {s: 0 for s in Status}
+    for r in results:
+        counts[r.status] += 1
+        label, color = _STATUS_STYLE[r.status]
+        tag = click.style(f"[{label}]", fg=color, bold=True)
+        loc = click.style(r.target, bold=True)
+        extra = f"  {r.label}" if r.label else ""
+        summ = f"  {r.summary}" if r.summary else ""
+        click.echo(f"{tag} {r.verifier:<10} {loc}{extra}{summ}")
+        if show_detail and r.status in (Status.FAIL, Status.ERROR) and r.detail:
+            for line in r.detail.splitlines():
+                click.echo(click.style("        " + line, fg="bright_black"))
+    return counts
+
+
+def _summary_line(counts: dict[Status, int]) -> str:
+    parts = [
+        click.style(f"{counts[Status.PASS]} passed", fg="green"),
+        click.style(f"{counts[Status.FAIL]} failed", fg="red"),
+        click.style(f"{counts[Status.ERROR]} errored", fg="red"),
+        click.style(f"{counts[Status.SKIPPED]} skipped", fg="yellow"),
+    ]
+    return "  ".join(parts)
+
+
+# --------------------------------------------------------------------------- #
+# commands
+# --------------------------------------------------------------------------- #
+@click.group()
+@click.version_option(package_name="pyintent", message="%(version)s")
+def main() -> None:
+    """pyintent — verify that implementations satisfy their @spec intent."""
+
+
+@main.command()
+@click.option("--root", default=".", type=click.Path(file_okay=False),
+              help="Project root to write prompt files into.")
+def init(root: str) -> None:
+    """Write the pyintent authoring guide into agent prompt files."""
+    actions = _prompt.write_prompt_files(root)
+    for rel, action in actions.items():
+        click.echo(f"  {action:<9} {rel}")
+    click.echo(click.style("pyintent guide written. Point your AI tools here.", fg="green"))
+
+
+@main.command()
+def prompt() -> None:
+    """Print the pyintent authoring guide to stdout."""
+    click.echo(_prompt.get_reference())
+
+
+def _iter_specs(module):
+    """Yield (level, qualified_name, spec_or_None) for top-level defs in module."""
+    import inspect
+
+    modname = getattr(module, "__name__", "")
+    for name, obj in vars(module).items():
+        if name.startswith("__") and name.endswith("__"):
+            continue
+        if inspect.isfunction(obj) and getattr(obj, "__module__", None) == modname:
+            yield SpecLevel.FUNCTION, name, get_spec(obj)
+        elif inspect.isclass(obj) and getattr(obj, "__module__", None) == modname:
+            yield SpecLevel.CLASS, name, get_spec(obj)
+            for mname, mobj in vars(obj).items():
+                if mname.startswith("__") and mname.endswith("__"):
+                    continue
+                inner = mobj
+                if isinstance(mobj, (staticmethod, classmethod)):
+                    inner = mobj.__func__
+                elif isinstance(mobj, property):
+                    inner = mobj.fget
+                if inner is not None and (inspect.isfunction(inner)):
+                    yield SpecLevel.METHOD, f"{name}.{mname}", get_spec(inner)
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--require-specs", "require_specs", is_flag=True, default=False,
+              help="Fail if public functions/methods lack a @spec.")
+@click.option("--all", "require_all", is_flag=True, default=False,
+              help="With --require-specs, also require class and module specs.")
+def check(path: str, require_specs: bool, require_all: bool) -> None:
+    """Validate spec structure by importing PATH (no execution)."""
+    target = Path(path)
+    cfg = _load_config(target if target.is_dir() else target.parent)
+    cfg_rs = cfg.get("require_specs")
+    if not require_specs and cfg_rs:
+        require_specs = True
+        require_all = require_all or (cfg_rs == "all" or cfg_rs is True)
+
+    level = "all" if (require_specs and require_all) else ("public" if require_specs else None)
+
+    modules, errors = _collect_modules(target)
+
+    if errors:
+        for f, e in errors:
+            kind = "spec error" if isinstance(e, PyIntentSpecError) else type(e).__name__
+            click.echo(click.style(f"[{kind}] {f}: {e}", fg="red"))
+        sys.exit(2)
+
+    spec_count = 0
+    missing: list[str] = []
+    for f, module in modules:
+        for lvl, qual, sp in _iter_specs(module):
+            if sp is not None:
+                spec_count += 1
+            elif level:
+                if lvl is SpecLevel.CLASS and level != "all":
+                    continue
+                missing.append(f"{f}::{qual} ({lvl.value})")
+        if level == "all" and getattr(module, MODULE_ATTR, None) is None:
+            missing.append(f"{f}::<module> (module)")
+
+    click.echo(f"Imported {len(modules)} file(s); found {spec_count} spec(s).")
+    if missing:
+        click.echo(click.style(f"{len(missing)} definition(s) missing a @spec:", fg="red"))
+        for m in missing:
+            click.echo(f"  - {m}")
+        sys.exit(1)
+    click.echo(click.style("All specs valid.", fg="green"))
+
+
+@main.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--json", "as_json", is_flag=True, help="Emit machine-readable JSON.")
+@click.option("--only", type=click.Choice(ALL_VERIFIERS), multiple=True,
+              help="Run only these verifiers (repeatable).")
+def verify(path: str, as_json: bool, only: tuple[str, ...]) -> None:
+    """Run pyintent verifiers over PATH and report pass/fail."""
+    target = Path(path)
+    which = set(only) if only else None
+
+    modules, errors = _collect_modules(target)
+    if errors:
+        if as_json:
+            click.echo(json.dumps({
+                "ok": False,
+                "load_errors": [{"file": str(f), "error": str(e)} for f, e in errors],
+            }, indent=2))
+        else:
+            for f, e in errors:
+                click.echo(click.style(f"[load error] {f}: {e}", fg="red"))
+        sys.exit(2)
+
+    all_results = []
+    for _f, module in modules:
+        all_results.extend(run_all(module, which))
+
+    if as_json:
+        payload = {
+            "ok": all(r.status is not Status.FAIL and r.status is not Status.ERROR
+                      for r in all_results),
+            "results": [r.to_dict() for r in all_results],
+        }
+        click.echo(json.dumps(payload, indent=2))
+    else:
+        counts = _print_results(all_results)
+        click.echo("")
+        click.echo(_summary_line(counts))
+
+    failed = sum(1 for r in all_results if r.status in (Status.FAIL, Status.ERROR))
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()