pyintent 0.1.0__py3-none-any.whl

pyintent/__init__.py

@@ -0,0 +1,56 @@
+"""pyintent — verify that implementations satisfy intent specifications.
+
+A pure verifier: it checks, it never generates. See ``pyintent prompt`` for the
+full spec-authoring reference.
+"""
+
+from __future__ import annotations
+
+from ._effects import (
+    Effect,
+    EffectKind,
+    async_,
+    io,
+    network,
+    pure,
+    reads,
+    throws,
+    writes,
+)
+from ._errors import PyIntentError, PyIntentSpecError
+from ._module_spec import module_spec, package_spec
+from ._parser import Example
+from ._perf import Perf
+from ._spec import (
+    Invariant,
+    PyIntentSpec,
+    SpecLevel,
+    get_spec,
+    spec,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "spec",
+    "get_spec",
+    "module_spec",
+    "package_spec",
+    "Perf",
+    "pure",
+    "reads",
+    "writes",
+    "network",
+    "io",
+    "async_",
+    "throws",
+    "Effect",
+    "EffectKind",
+    "PyIntentSpec",
+    "SpecLevel",
+    "Invariant",
+    "Example",
+    "PyIntentError",
+    "PyIntentSpecError",
+    "__version__",
+]

pyintent/_discovery.py

@@ -0,0 +1,105 @@
+"""Find every spec attached to a module's functions, classes, and methods."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any
+
+from ._module_spec import MODULE_ATTR
+from ._spec import PyIntentSpec, SpecLevel, get_spec
+
+
+@dataclass
+class SpecTarget:
+    """A discovered spec plus everything a verifier needs to act on it."""
+
+    qualname: str
+    spec: PyIntentSpec
+    globalns: dict[str, Any]
+    module_name: str
+    filename: str | None = None
+    invoke: Any | None = None  # the callable to execute, when runnable
+    owner: type | None = None  # the owning class, for methods
+
+
+def discover_in_module(module: ModuleType) -> list[SpecTarget]:
+    targets: list[SpecTarget] = []
+    globalns = vars(module)
+    modname = getattr(module, "__name__", "<module>")
+    filename = getattr(module, "__file__", None)
+
+    mod_spec = globalns.get(MODULE_ATTR)
+    if isinstance(mod_spec, PyIntentSpec):
+        targets.append(
+            SpecTarget(
+                qualname=modname,
+                spec=mod_spec,
+                globalns=globalns,
+                module_name=modname,
+                filename=filename,
+            )
+        )
+
+    for name, obj in list(globalns.items()):
+        if inspect.isfunction(obj):
+            sp = get_spec(obj)
+            if sp is not None and getattr(obj, "__module__", None) == modname:
+                targets.append(
+                    SpecTarget(
+                        qualname=obj.__qualname__,
+                        spec=sp,
+                        globalns=globalns,
+                        module_name=modname,
+                        filename=filename,
+                        invoke=obj,
+                    )
+                )
+        elif inspect.isclass(obj) and getattr(obj, "__module__", None) == modname:
+            csp = get_spec(obj)
+            if csp is not None:
+                targets.append(
+                    SpecTarget(
+                        qualname=obj.__qualname__,
+                        spec=csp,
+                        globalns=globalns,
+                        module_name=modname,
+                        filename=filename,
+                        owner=obj,
+                    )
+                )
+            targets.extend(_discover_in_class(obj, globalns, modname, filename))
+
+    return targets
+
+
+def _discover_in_class(
+    cls: type, globalns: dict[str, Any], modname: str, filename: str | None
+) -> list[SpecTarget]:
+    targets: list[SpecTarget] = []
+    for name, member in list(vars(cls).items()):
+        sp = get_spec(member)
+        if sp is None:
+            continue
+        invoke: Any | None = None
+        if sp.level is SpecLevel.CLASSMETHOD:
+            invoke = getattr(cls, name)  # bound to cls
+        elif sp.level is SpecLevel.STATICMETHOD:
+            invoke = member.__func__
+        elif sp.level is SpecLevel.PROPERTY:
+            invoke = member.fget
+        elif sp.level in (SpecLevel.METHOD, SpecLevel.ABSTRACT):
+            invoke = member
+        targets.append(
+            SpecTarget(
+                qualname=sp.target_name,
+                spec=sp,
+                globalns=globalns,
+                module_name=modname,
+                filename=filename,
+                invoke=invoke,
+                owner=cls,
+            )
+        )
+    return targets

pyintent/_effects.py

@@ -0,0 +1,166 @@
+"""Effect declarations for a spec.
+
+An effect describes how a function interacts with the world. Effects are plain
+immutable value objects, validated at construction time. In v0.1 only ``pure``,
+``async_`` and ``throws`` are *verified* (see ``verifier/effects.py``); the rest
+are declaration-only and recorded for documentation and future versions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from ._errors import PyIntentSpecError
+
+
+class EffectKind(Enum):
+    PURE = "pure"
+    READS = "reads"
+    WRITES = "writes"
+    NETWORK = "network"
+    IO = "io"
+    ASYNC = "async"
+    THROWS = "throws"
+
+
+@dataclass(frozen=True)
+class Effect:
+    """A single declared effect. Construct via the helpers below, not directly."""
+
+    kind: EffectKind
+    resource: str | None = None
+    exceptions: tuple[type[BaseException], ...] = field(default=())
+
+    def __repr__(self) -> str:
+        if self.kind in (EffectKind.READS, EffectKind.WRITES, EffectKind.NETWORK):
+            return f"{self.kind.value}({self.resource!r})"
+        if self.kind is EffectKind.THROWS:
+            names = ", ".join(e.__name__ for e in self.exceptions)
+            return f"throws({names})"
+        return self.kind.value
+
+
+def _require_resource(fn_name: str, resource: object) -> str:
+    if not isinstance(resource, str) or not resource.strip():
+        raise PyIntentSpecError(
+            f"{fn_name}() requires a non-empty string naming the resource, "
+            f"e.g. {fn_name}('db'); got {resource!r}"
+        )
+    return resource
+
+
+#: The function has no observable side effects and is deterministic.
+#: **Actively verified** by the effects verifier via AST analysis.
+#: Calls to impure builtins (``print``, ``open``, ``input``, …) or modules
+#: (``os``, ``sys``, ``random``, ``requests``, …) and ``global``/``nonlocal``
+#: writes are reported as violations.
+pure = Effect(EffectKind.PURE)
+
+#: The function performs filesystem / stdout / stdin style I/O.
+#: Declaration-only in v0.1 — recorded for documentation, not yet enforced.
+io = Effect(EffectKind.IO)
+
+#: The function is a coroutine defined with ``async def``.
+#: **Actively verified**: the effects verifier checks that the function really
+#: is a coroutine function.
+async_ = Effect(EffectKind.ASYNC)
+
+
+def reads(resource: str) -> Effect:
+    """Declare that the function reads from a named resource.
+
+    This effect is **declaration-only** in v0.1 — it is recorded for
+    documentation but not actively verified.
+
+    Parameters
+    ----------
+    resource:
+        Non-empty string naming the resource, e.g. ``"db"``, ``"config"``.
+
+    Examples
+    --------
+    ::
+
+        @spec(intent="fetch user", effects=[reads("db")])
+        def get_user(user_id: int) -> User: ...
+    """
+    return Effect(EffectKind.READS, resource=_require_resource("reads", resource))
+
+
+def writes(resource: str) -> Effect:
+    """Declare that the function writes to a named resource.
+
+    This effect is **declaration-only** in v0.1 — it is recorded for
+    documentation but not actively verified.
+
+    Parameters
+    ----------
+    resource:
+        Non-empty string naming the resource, e.g. ``"db"``, ``"cache"``.
+
+    Examples
+    --------
+    ::
+
+        @spec(intent="save user", effects=[writes("db")])
+        def save_user(user: User) -> None: ...
+    """
+    return Effect(EffectKind.WRITES, resource=_require_resource("writes", resource))
+
+
+def network(service: str) -> Effect:
+    """Declare that the function calls an external network service.
+
+    This effect is **declaration-only** in v0.1 — it is recorded for
+    documentation but not actively verified.
+
+    Parameters
+    ----------
+    service:
+        Non-empty string naming the service, e.g. ``"stripe"``, ``"sendgrid"``.
+
+    Examples
+    --------
+    ::
+
+        @spec(intent="charge card", effects=[network("stripe")])
+        def charge(amount: int) -> str: ...
+    """
+    return Effect(EffectKind.NETWORK, resource=_require_resource("network", service))
+
+
+def throws(*exceptions: type[BaseException]) -> Effect:
+    """Declare the exception types the function may raise as part of its contract.
+
+    **Actively verified** by the effects verifier: the AST is checked to ensure
+    every explicitly raised exception type is listed here.
+
+    Parameters
+    ----------
+    *exceptions:
+        One or more exception classes (subclasses of :class:`BaseException`).
+
+    Raises
+    ------
+    PyIntentSpecError
+        If no arguments are given, or any argument is not an exception class.
+
+    Examples
+    --------
+    ::
+
+        @spec(intent="parse int", effects=[throws(ValueError)])
+        def parse_int(s: str) -> int:
+            return int(s)
+    """
+    if not exceptions:
+        raise PyIntentSpecError(
+            "throws() requires at least one exception type, e.g. throws(ValueError)"
+        )
+    for exc in exceptions:
+        if not (isinstance(exc, type) and issubclass(exc, BaseException)):
+            raise PyIntentSpecError(
+                f"throws() arguments must be exception classes, got {exc!r}"
+            )
+    return Effect(EffectKind.THROWS, exceptions=tuple(exceptions))

pyintent/_errors.py

@@ -0,0 +1,15 @@
+"""Exception types raised by pyintent."""
+
+from __future__ import annotations
+
+
+class PyIntentError(Exception):
+    """Base class for every error pyintent raises."""
+
+
+class PyIntentSpecError(PyIntentError):
+    """A spec is malformed.
+
+    Raised eagerly at decoration / construction time (never during verification)
+    so that a bad spec fails as soon as the module is imported.
+    """

pyintent/_loader.py

@@ -0,0 +1,56 @@
+"""Import Python files by path so their specs register (used by CLI and plugin)."""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Iterator
+
+_SKIP_DIRS = {
+    "__pycache__", ".git", ".venv", "venv", "node_modules",
+    ".mypy_cache", ".pytest_cache", "build", "dist", ".tox", ".eggs",
+}
+
+
+def import_file(path: str | Path) -> ModuleType:
+    """Import a single ``.py`` file as a uniquely-named module.
+
+    Scope (v0.1): this loads files as standalone modules under a synthetic name,
+    with the file's directory prepended to ``sys.path``. That is reliable for
+    self-contained scripts and flat layouts, but **explicit relative imports**
+    (``from . import x``) inside the target file are not resolved, since the file
+    is not imported as part of its package. For package-aware verification,
+    import the package normally and run the verifier against its modules.
+    """
+    p = Path(path).resolve()
+    modname = "pyintent_target_" + re.sub(r"\W", "_", str(p.with_suffix("")))
+    if modname in sys.modules:
+        return sys.modules[modname]
+
+    parent = str(p.parent)
+    if parent not in sys.path:
+        sys.path.insert(0, parent)
+
+    spec = importlib.util.spec_from_file_location(modname, str(p))
+    if spec is None or spec.loader is None:
+        raise ImportError(f"could not create import spec for {p}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[modname] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def iter_python_files(root: str | Path) -> Iterator[Path]:
+    """Yield ``.py`` files under ``root`` (or just ``root`` if it is a file)."""
+    p = Path(root)
+    if p.is_file():
+        if p.suffix == ".py":
+            yield p
+        return
+    for child in sorted(p.rglob("*.py")):
+        if any(part in _SKIP_DIRS for part in child.parts):
+            continue
+        yield child

pyintent/_module_spec.py

@@ -0,0 +1,68 @@
+"""Module- and package-level specs.
+
+Assign the result to ``__pyintent__`` in a module (or a package ``__init__.py``)::
+
+    from pyintent import module_spec, reads
+
+    __pyintent__ = module_spec(
+        intent     = "Order persistence and retrieval.",
+        invariants = ["every public function validates its inputs"],
+        effects    = [reads("db")],
+    )
+"""
+
+from __future__ import annotations
+
+from ._effects import Effect
+from ._errors import PyIntentSpecError
+from ._spec import (
+    PyIntentSpec,
+    SpecLevel,
+    _reject_disallowed,
+    _require_intent,
+    _validate_effects,
+    _validate_invariants,
+)
+
+MODULE_ATTR = "__pyintent__"
+
+
+def module_spec(
+    *,
+    intent: str,
+    invariants: list[str] | None = None,
+    effects: list[Effect] | None = None,
+) -> PyIntentSpec:
+    """Build a module-level spec. Assign it to ``__pyintent__``."""
+    intent = _require_intent(intent)
+    return PyIntentSpec(
+        level=SpecLevel.MODULE,
+        intent=intent,
+        target_name="<module>",
+        invariants=_validate_invariants(invariants),
+        effects=_validate_effects(effects),
+    )
+
+
+def package_spec(
+    *,
+    intent: str,
+    modules: list[str] | None = None,
+    invariants: list[str] | None = None,
+    effects: list[Effect] | None = None,
+) -> PyIntentSpec:
+    """Build a package-level spec. Assign it to ``__pyintent__`` in ``__init__.py``."""
+    intent = _require_intent(intent)
+    if modules is not None:
+        if not isinstance(modules, (list, tuple)) or not all(
+            isinstance(m, str) and m.strip() for m in modules
+        ):
+            raise PyIntentSpecError("modules= must be a list of non-empty module-name strings")
+    return PyIntentSpec(
+        level=SpecLevel.PACKAGE,
+        intent=intent,
+        target_name="<package>",
+        invariants=_validate_invariants(invariants),
+        effects=_validate_effects(effects),
+        modules=list(modules) if modules else [],
+    )

pyintent/_parser.py

@@ -0,0 +1,198 @@
+"""Parser for ``ex`` example strings.
+
+Grammar (informal)::
+
+    example  := args "->" expected
+    args     := "(" python-tuple ")"          # literal tuple; () means no args
+    expected := "_"                            # returns anything, raises nothing
+              | "raises" dotted-name           # must raise this exception type
+              | python-expression              # must == this value
+
+The *format* is validated eagerly at decoration time (so a malformed ``ex``
+fails at import). The actual values are evaluated lazily at verification time
+against the target's module globals, so domain objects and enums resolve
+correctly.
+
+For methods, ``ex`` tuples exclude ``self`` / ``cls``. For properties, the
+input tuple is empty: ``"() -> value"``.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from ._errors import PyIntentSpecError
+
+
+class _Wildcard:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "_"
+
+
+#: Sentinel: the call must return *something* without raising.
+WILDCARD = _Wildcard()
+
+
+@dataclass(frozen=True)
+class Raises:
+    """Expected outcome: the call must raise ``exc_name``."""
+
+    exc_name: str
+
+    def resolve(self, globalns: Mapping[str, Any]) -> type[BaseException]:
+        try:
+            exc = eval(self.exc_name, dict(globalns))  # noqa: S307 - dev-authored
+        except Exception as e:  # pragma: no cover - surfaced to user
+            raise PyIntentSpecError(
+                f"could not resolve exception {self.exc_name!r} in example: {e}"
+            ) from e
+        if not (isinstance(exc, type) and issubclass(exc, BaseException)):
+            raise PyIntentSpecError(
+                f"example 'raises {self.exc_name}' does not name an exception type"
+            )
+        return exc
+
+
+@dataclass(frozen=True)
+class ReturnsValue:
+    """Expected outcome: the call must return a value equal to ``value_src``."""
+
+    value_src: str
+
+    def resolve(self, globalns: Mapping[str, Any]) -> Any:
+        try:
+            return eval(self.value_src, dict(globalns))  # noqa: S307 - dev-authored
+        except Exception as e:  # pragma: no cover - surfaced to user
+            raise PyIntentSpecError(
+                f"could not evaluate expected value {self.value_src!r}: {e}"
+            ) from e
+
+
+Expected = _Wildcard | Raises | ReturnsValue
+
+
+@dataclass(frozen=True)
+class Example:
+    """A single parsed ``ex`` case."""
+
+    raw: str
+    args_src: str
+    expected: Expected
+
+    def eval_args(self, globalns: Mapping[str, Any]) -> tuple[Any, ...]:
+        try:
+            value = eval(self.args_src, dict(globalns))  # noqa: S307 - dev-authored
+        except Exception as e:  # pragma: no cover - surfaced to user
+            raise PyIntentSpecError(
+                f"could not evaluate example args {self.args_src!r}: {e}"
+            ) from e
+        if not isinstance(value, tuple):
+            raise PyIntentSpecError(
+                f"example args must evaluate to a tuple, got {type(value).__name__}"
+            )
+        return value
+
+
+def _split_on_arrow(text: str) -> tuple[str, str]:
+    """Split on the first top-level ``->`` outside of strings and brackets."""
+    depth = 0
+    quote: str | None = None
+    i, n = 0, len(text)
+    while i < n:
+        c = text[i]
+        if quote is not None:
+            if c == "\\":
+                i += 2
+                continue
+            if c == quote:
+                quote = None
+            i += 1
+            continue
+        if c in "\"'":
+            quote = c
+        elif c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+        elif c == "-" and depth == 0 and i + 1 < n and text[i + 1] == ">":
+            return text[:i], text[i + 2 :]
+        i += 1
+    raise PyIntentSpecError(
+        f"example {text!r} is missing the '->' separator "
+        f"(expected '(args) -> result')"
+    )
+
+
+def _validate_args_tuple(args_src: str, raw: str) -> str:
+    args_src = args_src.strip()
+    if not args_src:
+        raise PyIntentSpecError(
+            f"example {raw!r} has no argument tuple before '->' "
+            f"(use '()' for no arguments)"
+        )
+    try:
+        node = ast.parse(args_src, mode="eval")
+    except (SyntaxError, ValueError) as e:
+        msg = e.msg if isinstance(e, SyntaxError) else str(e)
+        raise PyIntentSpecError(
+            f"example args {args_src!r} are not valid Python: {msg}"
+        ) from e
+    if not isinstance(node.body, ast.Tuple):
+        raise PyIntentSpecError(
+            f"example args must be a tuple, got {args_src!r}. "
+            f"For a single argument add a trailing comma, e.g. '(42,) -> ...'."
+        )
+    return args_src
+
+
+def _parse_expected(expected_src: str, raw: str) -> Expected:
+    expected_src = expected_src.strip()
+    if not expected_src:
+        raise PyIntentSpecError(
+            f"example {raw!r} has nothing after '->' "
+            f"(use '_' for 'returns without raising')"
+        )
+    if expected_src == "_":
+        return WILDCARD
+    if expected_src == "raises" or expected_src.startswith("raises "):
+        exc_name = expected_src[len("raises") :].strip()
+        if not exc_name:
+            raise PyIntentSpecError(
+                f"example {raw!r}: 'raises' must be followed by an exception type"
+            )
+        try:
+            name_node = ast.parse(exc_name, mode="eval")
+        except (SyntaxError, ValueError) as e:
+            msg = e.msg if isinstance(e, SyntaxError) else str(e)
+            raise PyIntentSpecError(
+                f"example {raw!r}: invalid exception name {exc_name!r}: {msg}"
+            ) from e
+        if not isinstance(name_node.body, (ast.Name, ast.Attribute)):
+            raise PyIntentSpecError(
+                f"example {raw!r}: 'raises' must name an exception type, got {exc_name!r}"
+            )
+        return Raises(exc_name)
+    try:
+        ast.parse(expected_src, mode="eval")
+    except (SyntaxError, ValueError) as e:
+        msg = e.msg if isinstance(e, SyntaxError) else str(e)
+        raise PyIntentSpecError(
+            f"example {raw!r}: expected value {expected_src!r} is not valid Python: {msg}"
+        ) from e
+    return ReturnsValue(expected_src)
+
+
+def parse_example(raw: str) -> Example:
+    """Parse and format-validate one ``ex`` string. Raises ``PyIntentSpecError``."""
+    if not isinstance(raw, str):
+        raise PyIntentSpecError(
+            f"each ex entry must be a string like '(1, 2) -> 3', got {raw!r}"
+        )
+    left, right = _split_on_arrow(raw)
+    args_src = _validate_args_tuple(left, raw)
+    expected = _parse_expected(right, raw)
+    return Example(raw=raw, args_src=args_src, expected=expected)