api-parity-py 0.0.2__tar.gz

api_parity_py-0.0.2/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Rust
+target/
+# Library workspace — don't pin Cargo.lock
+Cargo.lock
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+*.swp

api_parity_py-0.0.2/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: api-parity-py
+Version: 0.0.2
+Summary: Python plugin for api-parity (reference walker + port annotations).
+Requires-Python: >=3.10

api_parity_py-0.0.2/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "api-parity-py"
+version = "0.0.2"
+description = "Python plugin for api-parity (reference walker + port annotations)."
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+api-parity-py = "api_parity_py.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/api_parity_py"]

api_parity_py-0.0.2/src/api_parity_py/__init__.py

@@ -0,0 +1,5 @@
+"""api-parity-py: Python plugin for api-parity (reference + port)."""
+
+from .parity import Status, parity, parity_impl, parity_ref
+
+__all__ = ["Status", "parity", "parity_impl", "parity_ref"]

api_parity_py-0.0.2/src/api_parity_py/__main__.py

@@ -0,0 +1,148 @@
+"""CLI: ``api-parity-py <kind> [--mode walker|annotation] <target> [-o PATH]``.
+
+Supported combos:
+  reference walker     walk a package's public API (default for reference)
+  reference annotation collect ``@parity_ref`` decorators in a package
+  port      walker     walk a package and synthesize implemented port entries
+  port      annotation collect ``@parity_impl`` / ``@parity`` decorators
+                       (default for port)
+"""
+
+import argparse
+import importlib
+import json
+import sys
+from pathlib import Path
+
+from . import walk
+from .parity import collect_port_entries, collect_reference_entries
+
+EXIT_USAGE = 64
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="api-parity-py")
+    ap.add_argument("kind", choices=("reference", "port"))
+    ap.add_argument(
+        "--mode",
+        choices=("walker", "annotation"),
+        default=None,
+        help="how entries are produced (defaults: reference→walker, port→annotation)",
+    )
+    ap.add_argument(
+        "target",
+        help="package name (or comma-separated names, e.g. "
+        "'pyspark.sql.connect,pyspark.sql.session')",
+    )
+    ap.add_argument(
+        "--version-from",
+        default=None,
+        help="module to read `__version__` from (e.g. `pyspark`)",
+    )
+    ap.add_argument(
+        "-o",
+        "--output",
+        default="-",
+        help="output file path, or `-` for stdout (default)",
+    )
+    args = ap.parse_args()
+
+    mode = args.mode or _default_mode(args.kind)
+    envelope = _build_envelope(
+        kind=args.kind,
+        mode=mode,
+        target=args.target,
+        version_from=args.version_from,
+    )
+    if envelope is None:
+        sys.stderr.write(
+            f"api-parity-py: ({args.kind}, mode={mode}) is not yet implemented\n"
+        )
+        return EXIT_USAGE
+
+    text = json.dumps(envelope, indent=2)
+    if args.output == "-":
+        sys.stdout.write(text + "\n")
+    else:
+        Path(args.output).write_text(text + "\n")
+    return 0
+
+
+def _default_mode(kind: str) -> str:
+    return "annotation" if kind == "port" else "walker"
+
+
+def _build_envelope(
+    *,
+    kind: str,
+    mode: str,
+    target: str,
+    version_from: str | None,
+) -> dict | None:
+    if kind == "reference" and mode == "walker":
+        return walk.walk_package(target, version_from=version_from)
+    if kind == "reference" and mode == "annotation":
+        return _collect_annotations(target, version_from, kind="reference")
+    if kind == "port" and mode == "annotation":
+        return _collect_annotations(target, version_from, kind="port")
+    if kind == "port" and mode == "walker":
+        return _walker_as_port(target, version_from)
+    return None
+
+
+def _import_target_packages(target: str) -> list[str]:
+    """Import every submodule of every requested package so decorators run."""
+    packages = [p.strip() for p in target.split(",") if p.strip()]
+    for pkg in packages:
+        walk._preload_submodules(pkg)
+    return packages
+
+
+def _read_version(version_from: str | None) -> str | None:
+    if not version_from:
+        return None
+    try:
+        mod = importlib.import_module(version_from)
+        return getattr(mod, "__version__", None)
+    except Exception:
+        return None
+
+
+def _collect_annotations(
+    target: str, version_from: str | None, *, kind: str,
+) -> dict:
+    packages = _import_target_packages(target)
+    if kind == "port":
+        entries = collect_port_entries()
+    else:
+        entries = collect_reference_entries()
+    return {
+        "schema_version": 1,
+        "kind": kind,
+        "language": "python",
+        "version": _read_version(version_from),
+        "source": ",".join(packages),
+        "entries": entries,
+    }
+
+
+def _walker_as_port(target: str, version_from: str | None) -> dict:
+    """Treat every walked public API as `status=implemented`. Useful for
+    py-vs-py comparisons where neither side is annotated."""
+    ref = walk.walk_package(target, version_from=version_from)
+    entries = []
+    for e in ref["entries"]:
+        impl = e["path"]
+        entries.append({
+            "path": e["path"],
+            "implementation": impl,
+            "status": "implemented",
+            "since": None,
+            "issue": None,
+            "comment": None,
+        })
+    return {**ref, "kind": "port", "entries": entries}
+
+
+if __name__ == "__main__":
+    sys.exit(main())

api_parity_py-0.0.2/src/api_parity_py/parity.py

@@ -0,0 +1,212 @@
+"""Annotation API for Python plugins.
+
+Three decorators:
+
+- ``@parity_impl(path=..., status=...)`` on a class. Sets a parent path
+  for its methods; if both ``path`` and ``status`` are given, also
+  registers a class-level port entry.
+- ``@parity(path=..., status=...)`` on a method. A leading ``.`` makes
+  the path relative to the enclosing ``@parity_impl``'s path. Free
+  functions (no enclosing class) are supported with absolute paths.
+- ``@parity_ref(path=..., kind=...)`` on a class / method / function.
+  For declaring a reference inventory in code (rare; usually a walker
+  is better).
+
+Decorators write to module-level registries that the CLI dumps in
+``port`` / ``reference`` mode with ``--mode annotation``.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Callable
+
+_PORT_ENTRIES: list[dict] = []
+_REFERENCE_ENTRIES: list[dict] = []
+
+
+class Status(str, Enum):
+    IMPLEMENTED = "implemented"
+    PARTIAL = "partial"
+    UNIMPLEMENTED = "unimplemented"
+
+
+def _normalize_status(status: Any) -> str:
+    if isinstance(status, Status):
+        return status.value
+    if isinstance(status, str) and status in {s.value for s in Status}:
+        return status
+    raise TypeError(
+        f"status must be a Status enum or one of {{implemented, partial, unimplemented}}, "
+        f"got {status!r}"
+    )
+
+
+def _validate_port_args(status: str, comment: str | None) -> None:
+    if status == Status.UNIMPLEMENTED.value and not comment:
+        raise ValueError(
+            "status=Unimplemented requires a comment explaining why"
+        )
+
+
+def parity(
+    path: str,
+    status: Status | str,
+    *,
+    since: str | None = None,
+    issue: int | None = None,
+    comment: str | None = None,
+) -> Callable:
+    """Method-level / free-function port annotation.
+
+    Inside a ``@parity_impl`` class, a leading ``.`` in ``path`` is
+    rewritten as ``parent_path + child`` when the class decorator runs.
+    For free functions the path must be absolute.
+    """
+    status_str = _normalize_status(status)
+    _validate_port_args(status_str, comment)
+    meta = {
+        "path": path,
+        "status": status_str,
+        "since": since,
+        "issue": issue,
+        "comment": comment,
+    }
+
+    def decorate(fn: Callable) -> Callable:
+        if path.startswith("."):
+            # Relative path: stash meta so the enclosing `parity_impl`
+            # sweep can resolve it against the parent path.
+            fn._parity_meta = meta  # type: ignore[attr-defined]
+            return fn
+        # Absolute path: register immediately. Works for free functions
+        # and for class methods whose path is unrelated to their enclosing
+        # type. We don't stash meta — that would cause `parity_impl` to
+        # double-register the same entry.
+        impl = f"{fn.__module__}.{fn.__qualname__}"
+        _PORT_ENTRIES.append({**meta, "implementation": impl})
+        return fn
+
+    return decorate
+
+
+def parity_impl(
+    path: Any = None,
+    status: Status | str | None = None,
+    *,
+    since: str | None = None,
+    issue: int | None = None,
+    comment: str | None = None,
+) -> Callable:
+    """Class-level port annotation.
+
+    Two call forms:
+
+    - ``@parity_impl(path="...", status=...)`` — with args, registers a
+      class-level entry and provides a parent path for relative children.
+    - ``@parity_impl`` — bare, no args. Sweeps the class for relative
+      ``@parity`` children but registers no class-level entry (and a
+      child with a leading-``.`` path is an error in this form).
+
+    Either way, the class's ``__dict__`` is swept and any
+    ``@parity``-decorated method with relative path gets joined with the
+    parent's ``path`` and registered.
+    """
+    # Bare-decorator form: Python passes the class as the first arg.
+    if isinstance(path, type) and status is None:
+        return parity_impl()(path)
+
+    parent_path = path
+    parent_status = _normalize_status(status) if status is not None else None
+    if parent_status is not None:
+        _validate_port_args(parent_status, comment)
+
+    def decorate(cls: type) -> type:
+        # Class-level entry, if both path and status given.
+        if parent_path and parent_status:
+            _PORT_ENTRIES.append({
+                "path": parent_path,
+                "implementation": f"{cls.__module__}.{cls.__qualname__}",
+                "status": parent_status,
+                "since": since,
+                "issue": issue,
+                "comment": comment,
+            })
+
+        # Sweep methods. We look at __dict__ rather than dir() so we
+        # only see things defined on this class (not inherited), and so
+        # properties / classmethods come back as their raw descriptor
+        # (which is what the @parity decorator attached the meta to).
+        for name, value in cls.__dict__.items():
+            inner = value
+            if isinstance(value, (classmethod, staticmethod)):
+                inner = value.__func__
+            elif isinstance(value, property):
+                inner = value.fget
+            meta = getattr(inner, "_parity_meta", None)
+            if not meta:
+                continue
+            child_path = meta["path"]
+            if child_path.startswith("."):
+                if not parent_path:
+                    raise ValueError(
+                        f"@parity({child_path!r}) on {cls.__qualname__}.{name} "
+                        f"requires the enclosing @parity_impl to declare a path"
+                    )
+                full_path = f"{parent_path}{child_path}"
+            else:
+                full_path = child_path
+            _PORT_ENTRIES.append({
+                "path": full_path,
+                "implementation": f"{cls.__module__}.{cls.__qualname__}.{name}",
+                "status": meta["status"],
+                "since": meta["since"],
+                "issue": meta["issue"],
+                "comment": meta["comment"],
+            })
+        return cls
+
+    return decorate
+
+
+def parity_ref(path: str, kind: str) -> Callable:
+    """Code-level reference entry. Apply to a class / method / function."""
+    if kind not in {"class", "method", "property", "function"}:
+        raise ValueError(
+            f"kind must be one of class/method/property/function, got {kind!r}"
+        )
+    entry = {"path": path, "kind": kind}
+
+    def decorate(target: Any) -> Any:
+        _REFERENCE_ENTRIES.append(entry)
+        return target
+
+    return decorate
+
+
+def collect_port_entries() -> list[dict]:
+    """Return all port entries registered so far, sorted+deduped by path."""
+    return _sort_dedup(_PORT_ENTRIES, key=("path",))
+
+
+def collect_reference_entries() -> list[dict]:
+    """Return all reference entries registered so far, sorted+deduped."""
+    return _sort_dedup(_REFERENCE_ENTRIES, key=("path", "kind"))
+
+
+def reset_registries() -> None:
+    """Clear both registries. Intended for tests."""
+    _PORT_ENTRIES.clear()
+    _REFERENCE_ENTRIES.clear()
+
+
+def _sort_dedup(entries: list[dict], key: tuple[str, ...]) -> list[dict]:
+    seen: set[tuple] = set()
+    out: list[dict] = []
+    for e in sorted(entries, key=lambda d: tuple(d.get(k) or "" for k in key)):
+        k = tuple(e.get(field) for field in key)
+        if k in seen:
+            continue
+        seen.add(k)
+        out.append(e)
+    return out

api_parity_py-0.0.2/src/api_parity_py/walk.py

@@ -0,0 +1,242 @@
+"""Walk a Python package and emit a reference-side envelope (see SCHEMA.md).
+
+# Algorithm
+
+1. Preload every submodule of each requested package, so classes defined
+   in lazy-imported modules show up in `sys.modules` and forward-reference
+   strings are resolvable.
+2. Walk the loaded modules. For each module under one of the requested
+   packages, list its public classes — but only the ones *defined* there
+   (i.e. `cls.__module__ == mod_name`), so re-exports don't double-count.
+3. For each class, recurse into nested classes (e.g. `SparkSession.Builder`)
+   and emit one entry per public method/property. Class-level data attrs
+   (`MAX_MESSAGE_LENGTH = 128`) and nested classes are handled separately.
+4. Module-level free functions are emitted with `kind = "function"`.
+
+# Path keying
+
+Each entry's `path` is `cls.__module__ + "." + cls.__qualname__` (for a
+class) or `<class path>.<member>` (for a member). `__qualname__` includes
+nesting, so `SparkSession.Builder` keeps its dotted lexical structure.
+
+This means `pyspark.sql.session.SparkSession` and
+`pyspark.sql.connect.session.SparkSession` are distinct entries — both
+classes are tracked, no qualname collision, no priority/preference flag.
+"""
+
+import importlib
+import inspect
+import pkgutil
+import sys
+from collections import Counter
+
+# `inspect.getmembers(object)` brings in `__init__`, `__doc__`, etc.; we
+# strip those by name to keep the public API list focused on real surface.
+_OBJECT_MEMBERS = frozenset(name for name, _ in inspect.getmembers(object))
+# Subclasses of these are "data shapes", not API surface. Filtering by
+# class hierarchy avoids clutter from `Row` (a tuple subclass), exception
+# types, etc.
+_DATA_BASES = (tuple, list, dict, BaseException)
+
+
+def _preload_submodules(package_name: str) -> None:
+    """Import every submodule of `package_name` into `sys.modules`.
+
+    Without this, classes defined in lazy-loaded submodules would never be
+    seen by the discovery walk, and string-form forward-reference type
+    annotations (`'SparkConnectClient'`) wouldn't resolve.
+
+    Submodules whose import raises (e.g. because an optional dep like
+    pandas isn't installed) are collected and summarized on stderr so an
+    incomplete walk is visibly incomplete instead of silently truncated.
+    """
+    try:
+        pkg = importlib.import_module(package_name)
+    except Exception as e:
+        sys.stderr.write(
+            f"api-parity-py: failed to import top-level package "
+            f"{package_name!r}: {type(e).__name__}: {e}\n"
+        )
+        return
+    pkg_path = getattr(pkg, "__path__", None)
+    if pkg_path is None:
+        return
+
+    failures: list[tuple[str, BaseException]] = []
+    total = 0
+    for _, mod_name, _ in pkgutil.walk_packages(pkg_path, prefix=package_name + "."):
+        total += 1
+        try:
+            importlib.import_module(mod_name)
+        except Exception as e:
+            failures.append((mod_name, e))
+
+    if failures:
+        _report_skipped(package_name, total, failures)
+
+
+def _report_skipped(
+    package_name: str,
+    total: int,
+    failures: list[tuple[str, BaseException]],
+) -> None:
+    """Print a grouped, terse summary of import failures to stderr."""
+    reasons: Counter[str] = Counter()
+    examples: dict[str, str] = {}
+    for mod, err in failures:
+        first_line = str(err).splitlines()[0][:120] if str(err) else ""
+        key = f"{type(err).__name__}: {first_line}" if first_line else type(err).__name__
+        reasons[key] += 1
+        examples.setdefault(key, mod)
+
+    sys.stderr.write(
+        f"api-parity-py: {package_name}: "
+        f"skipped {len(failures)}/{total} submodule(s) — inventory will be incomplete\n"
+    )
+    for reason, count in reasons.most_common():
+        sys.stderr.write(f"  - [{count}x] {reason}\n")
+        sys.stderr.write(f"      e.g. {examples[reason]}\n")
+
+
+def _raw_attr(cls: type, name: str) -> object:
+    """Return the raw descriptor for `name` on `cls`, walking the MRO.
+
+    We can't use `getattr(cls, name)` to detect properties — that triggers
+    descriptor invocation and gives us the resolved value (e.g. a `Builder`
+    instance) instead of the descriptor itself. Looking up via `__dict__`
+    on each MRO class returns the raw `property` / `classmethod` object.
+    """
+    for klass in cls.__mro__:
+        if name in klass.__dict__:
+            return klass.__dict__[name]
+    return None
+
+
+def _member_kind(cls: type, name: str, value: object) -> str | None:
+    """Classify a class member, or `None` to drop it from the inventory.
+
+    `isinstance(raw, property)` catches `property` subclasses like pyspark's
+    `classproperty`. Nested classes return None — they're emitted as their
+    own top-level entries by the recursion in `_collect_class`. Callable
+    values (functions, classmethods after descriptor invocation, etc.)
+    become methods.
+    """
+    raw = _raw_attr(cls, name)
+    if isinstance(raw, property):
+        return "property"
+    if isinstance(value, type):
+        return None
+    if callable(value):
+        return "method"
+    # Plain class attributes (constants, default values) are not API surface.
+    return None
+
+
+def _is_api_class(obj: object) -> bool:
+    return isinstance(obj, type) and not issubclass(obj, _DATA_BASES)
+
+
+def _collect_class(cls: type, entries: list[dict]) -> None:
+    """Record `cls` and its members, then recurse into nested classes."""
+    full = f"{cls.__module__}.{cls.__qualname__}"
+    # Cheap dedup: re-exports may cause us to revisit a class. We bail
+    # before doing redundant member walks.
+    if any(e["path"] == full and e["kind"] == "class" for e in entries):
+        return
+    entries.append({"path": full, "kind": "class"})
+
+    for name, value in inspect.getmembers(cls):
+        if name.startswith("_") or name in _OBJECT_MEMBERS:
+            continue
+        kind = _member_kind(cls, name, value)
+        if kind is None:
+            continue
+        entries.append({"path": f"{full}.{name}", "kind": kind})
+
+    # Nested classes: their `__module__` matches the outer class's, and
+    # their `__qualname__` is prefixed with `<outer>.` — those two checks
+    # together filter out unrelated classes that happen to be exposed as
+    # attributes (e.g. types pulled in for type hints).
+    for name, obj in inspect.getmembers(cls):
+        if name.startswith("_") or not _is_api_class(obj):
+            continue
+        if obj.__module__ != cls.__module__:
+            continue
+        if not obj.__qualname__.startswith(cls.__qualname__ + "."):
+            continue
+        _collect_class(obj, entries)
+
+
+def _discover(packages: list[str]) -> list[dict]:
+    """Walk every loaded module under `packages`, emit entries."""
+    entries: list[dict] = []
+    for mod_name, mod in list(sys.modules.items()):
+        if mod is None:
+            continue
+        if not any(mod_name == p or mod_name.startswith(p + ".") for p in packages):
+            continue
+
+        # Top-level classes, recursing into their nested classes.
+        for name, obj in inspect.getmembers(mod):
+            if name.startswith("_") or not _is_api_class(obj):
+                continue
+            # Skip re-exports: only record a class in its defining module.
+            # Without this, `pyspark.sql.SparkSession` (re-export from
+            # `pyspark.sql.session`) would be listed twice with different
+            # paths.
+            if obj.__module__ != mod_name:
+                continue
+            _collect_class(obj, entries)
+
+        # Module-level free functions (e.g. `pyspark.sql.functions.col`).
+        for name, obj in inspect.getmembers(mod, inspect.isfunction):
+            if name.startswith("_"):
+                continue
+            if obj.__module__ != mod_name:
+                continue
+            entries.append({
+                "path": f"{obj.__module__}.{obj.__qualname__}",
+                "kind": "function",
+            })
+
+    # Sort + dedup by (path, kind). Stability matters because the JSON
+    # output is part of the contract — diffing two versions should produce
+    # minimal noise.
+    seen: set[tuple[str, str]] = set()
+    out: list[dict] = []
+    for e in sorted(entries, key=lambda e: (e["path"], e["kind"])):
+        key = (e["path"], e["kind"])
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(e)
+    return out
+
+
+def walk_package(target: str, *, version_from: str | None = None) -> dict:
+    """Build a reference envelope for one or more comma-separated packages.
+
+    `version_from` names a module to import for its `__version__` (e.g.
+    `"pyspark"`). If unimportable or missing the attribute, version is
+    left null; this is informational metadata, not part of the join key.
+    """
+    packages = [p.strip() for p in target.split(",") if p.strip()]
+    for pkg in packages:
+        _preload_submodules(pkg)
+
+    version = None
+    if version_from:
+        try:
+            mod = importlib.import_module(version_from)
+            version = getattr(mod, "__version__", None)
+        except Exception:
+            pass
+
+    return {
+        "schema_version": 1,
+        "kind": "reference",
+        "language": "python",
+        "version": version,
+        "source": ",".join(packages),
+        "entries": _discover(packages),
+    }

api_parity_py-0.0.2/tests/conftest.py

@@ -0,0 +1,6 @@
+"""Add `tests/fixtures/` to `sys.path` so `tinypkg` is importable."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent / "fixtures"))

api_parity_py-0.0.2/tests/fixtures/portpkg/__init__.py

@@ -0,0 +1,3 @@
+"""Synthetic package exercising every decorator path."""
+
+from .core import Widget, Naked, free_fn, Declared  # noqa: F401

api_parity_py-0.0.2/tests/fixtures/portpkg/core.py

@@ -0,0 +1,42 @@
+"""Annotated classes/functions used by the port + reference annotation tests."""
+
+from api_parity_py import Status, parity, parity_impl, parity_ref
+
+
+@parity_impl(path="ext.widget.Widget", status=Status.IMPLEMENTED, since="1.0")
+class Widget:
+    @parity(path=".foo", status=Status.IMPLEMENTED)
+    def foo(self):
+        return 1
+
+    @parity(path=".bar", status=Status.PARTIAL, comment="missing batch mode")
+    def bar(self):
+        return 2
+
+    @parity(
+        path=".baz",
+        status=Status.UNIMPLEMENTED,
+        comment="todo",
+        issue=42,
+    )
+    def baz(self):
+        raise NotImplementedError
+
+
+@parity_impl
+class Naked:
+    """No class-level entry; child uses an absolute path."""
+
+    @parity(path="ext.naked.absolute_only", status=Status.IMPLEMENTED)
+    def whatever(self):
+        return 0
+
+
+@parity(path="ext.free.solo", status=Status.PARTIAL, comment="wip")
+def free_fn():
+    return None
+
+
+@parity_ref(path="ext.spec.Declared", kind="class")
+class Declared:
+    pass

api_parity_py-0.0.2/tests/fixtures/tinypkg/__init__.py

@@ -0,0 +1,7 @@
+"""Synthetic test package — re-exports a class and a function from
+submodules to verify the walker's "skip re-exports" rule."""
+
+from .core import Widget
+from .extras import helper
+
+__all__ = ["Widget", "helper"]

api_parity_py-0.0.2/tests/fixtures/tinypkg/core.py

@@ -0,0 +1,40 @@
+"""Core module of the synthetic test package.
+
+Each member is here to exercise one branch of the walker:
+  - `foo`: regular method
+  - `bar`: property (must be detected via raw __dict__ lookup, not getattr)
+  - `bake`: classmethod (callable, but the raw descriptor is a classmethod)
+  - `_private`: underscore-prefixed → must be skipped
+  - `Inner`: nested class → must be emitted with dotted qualname
+  - `RowLike`: tuple subclass → must be filtered as a data shape
+"""
+
+
+class Widget:
+    """Public widget."""
+
+    CONSTANT = 42  # plain class attribute — not API surface, must be skipped
+
+    def foo(self) -> int:
+        return 1
+
+    @property
+    def bar(self) -> str:
+        return "bar"
+
+    @classmethod
+    def bake(cls) -> "Widget":
+        return cls()
+
+    def _private(self) -> None:
+        pass
+
+    class Inner:
+        """Nested class — its qualname is `Widget.Inner`."""
+
+        def baz(self) -> None:
+            pass
+
+
+class RowLike(tuple):
+    """tuple subclass — counted as a data shape, must be excluded."""

api_parity_py-0.0.2/tests/fixtures/tinypkg/extras.py

@@ -0,0 +1,10 @@
+"""Extras module — exists to verify free-function emission and the
+underscore-skip rule for module-level callables."""
+
+
+def helper(x: int) -> int:
+    return x
+
+
+def _hidden() -> None:
+    """Underscore-prefixed → must be skipped."""

api_parity_py-0.0.2/tests/test_cli.py

@@ -0,0 +1,82 @@
+"""End-to-end acceptance tests for `api-parity-py`.
+
+One test per (kind, mode) cell — each invokes the CLI via `cli.main()`
+with a monkeypatched `argv`, parses stdout, and asserts the envelope
+shape against the synthetic fixtures.
+"""
+
+import json
+import sys
+
+import pytest
+
+from api_parity_py import __main__ as cli
+from api_parity_py.parity import reset_registries
+
+
+def _purge(*roots: str) -> None:
+    """Drop cached fixture modules so re-imports re-run their decorators."""
+    for name in list(sys.modules):
+        if name in roots or any(name.startswith(r + ".") for r in roots):
+            del sys.modules[name]
+
+
+@pytest.fixture(autouse=True)
+def _isolate():
+    reset_registries()
+    _purge("tinypkg", "portpkg")
+    yield
+    reset_registries()
+    _purge("tinypkg", "portpkg")
+
+
+def _run(*argv: str, capsys) -> dict:
+    """Invoke the CLI and return the parsed-JSON stdout envelope."""
+    import sys as _sys
+    _sys.argv = ["api-parity-py", *argv]
+    rc = cli.main()
+    assert rc == 0, capsys.readouterr().err
+    out = capsys.readouterr().out
+    return json.loads(out)
+
+
+def test_reference_walker_against_tinypkg(capsys):
+    """`reference` defaults to mode=walker — walks tinypkg's public API."""
+    env = _run("reference", "tinypkg", capsys=capsys)
+    assert env["schema_version"] == 1
+    assert env["kind"] == "reference"
+    assert env["language"] == "python"
+    paths = {e["path"] for e in env["entries"]}
+    assert "tinypkg.core.Widget" in paths
+    assert "tinypkg.core.Widget.foo" in paths
+    assert "tinypkg.extras.helper" in paths
+
+
+def test_port_annotation_against_portpkg(capsys):
+    """`port` defaults to mode=annotation — collects @parity_impl/@parity."""
+    env = _run("port", "portpkg", capsys=capsys)
+    assert env["kind"] == "port"
+    paths = {e["path"] for e in env["entries"]}
+    assert "ext.widget.Widget" in paths
+    assert "ext.widget.Widget.foo" in paths
+    assert "ext.free.solo" in paths
+
+
+def test_reference_annotation_against_portpkg(capsys):
+    """`reference --mode=annotation` collects @parity_ref decorators."""
+    env = _run("reference", "--mode=annotation", "portpkg", capsys=capsys)
+    assert env["kind"] == "reference"
+    paths = {e["path"] for e in env["entries"]}
+    assert "ext.spec.Declared" in paths
+
+
+def test_port_walker_against_tinypkg(capsys):
+    """`port --mode=walker` synthesizes implemented port entries from a walk.
+
+    Useful for py↔py comparisons where neither side is annotated."""
+    env = _run("port", "--mode=walker", "tinypkg", capsys=capsys)
+    assert env["kind"] == "port"
+    assert env["entries"], "expected at least one synthesized port entry"
+    for e in env["entries"]:
+        assert e["status"] == "implemented"
+        assert e["implementation"] == e["path"]

api_parity_py-0.0.2/tests/test_parity.py

@@ -0,0 +1,115 @@
+"""Tests for the @parity / @parity_impl / @parity_ref decorators."""
+
+import pytest
+
+from api_parity_py import Status, parity, parity_impl
+from api_parity_py.parity import (
+    collect_port_entries,
+    collect_reference_entries,
+    reset_registries,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolate_registries():
+    """Each test starts with empty registries and restores nothing — tests
+    should not depend on residual state from earlier tests."""
+    reset_registries()
+    yield
+    reset_registries()
+
+
+def _import_fixture():
+    """Re-import portpkg so its module-level decorators run again into the
+    freshly-reset registries."""
+    import sys
+
+    for name in list(sys.modules):
+        if name == "portpkg" or name.startswith("portpkg."):
+            del sys.modules[name]
+    import portpkg  # noqa: F401
+
+
+def test_class_level_entry_and_relative_children():
+    _import_fixture()
+    entries = collect_port_entries()
+    by_path = {e["path"]: e for e in entries}
+
+    # Class-level entry: implementation = qualified class name, optional
+    # fields propagate from the impl-level args.
+    cls = by_path["ext.widget.Widget"]
+    assert cls["implementation"].endswith(".Widget")
+    assert cls["status"] == "implemented"
+    assert cls["since"] == "1.0"
+
+    # Method with no comment: comment is None, not inherited from parent.
+    foo = by_path["ext.widget.Widget.foo"]
+    assert foo["implementation"].endswith(".Widget.foo")
+    assert foo["status"] == "implemented"
+    assert foo["comment"] is None
+
+    # Unimplemented requires a comment; the issue field round-trips.
+    baz = by_path["ext.widget.Widget.baz"]
+    assert baz["status"] == "unimplemented"
+    assert baz["comment"] == "todo"
+    assert baz["issue"] == 42
+
+
+def test_parity_impl_without_args_keeps_absolute_children():
+    """`@parity_impl` with no args registers no class entry, but a child
+    with an absolute path still works and gets the qualified-class
+    implementation prefix."""
+    _import_fixture()
+    entries = collect_port_entries()
+    naked = [e for e in entries if e["path"] == "ext.naked.absolute_only"]
+    assert len(naked) == 1
+    assert naked[0]["implementation"].endswith(".Naked.whatever")
+
+
+def test_free_function_uses_absolute_path():
+    _import_fixture()
+    entries = collect_port_entries()
+    solo = next(e for e in entries if e["path"] == "ext.free.solo")
+    assert solo["status"] == "partial"
+    assert solo["comment"] == "wip"
+    assert solo["implementation"].endswith(".free_fn")
+
+
+def test_parity_ref_registers_reference_entry():
+    _import_fixture()
+    refs = collect_reference_entries()
+    assert {"path": "ext.spec.Declared", "kind": "class"} in refs
+
+
+def test_unimplemented_without_comment_raises():
+    """The validator runs at decoration time, so the failure surfaces
+    where the bad annotation lives — not at registry-dump time."""
+    with pytest.raises(ValueError, match="comment"):
+        @parity(path="x.y", status=Status.UNIMPLEMENTED)
+        def _f():
+            pass
+
+
+def test_relative_path_without_parent_raises():
+    """A leading-`.` path needs an enclosing `@parity_impl` with a path."""
+    with pytest.raises(ValueError, match="enclosing @parity_impl"):
+        @parity_impl  # no args = no parent path
+        class _Nope:
+            @parity(path=".child", status=Status.IMPLEMENTED)
+            def child(self):
+                pass
+
+
+def test_invalid_status_type_raises():
+    with pytest.raises(TypeError, match="Status"):
+        @parity(path="x.y", status="bogus")
+        def _f():
+            pass
+
+
+def test_collect_returns_sorted_unique():
+    _import_fixture()
+    entries = collect_port_entries()
+    paths = [e["path"] for e in entries]
+    assert paths == sorted(paths)
+    assert len(paths) == len(set(paths))

api_parity_py-0.0.2/tests/test_walk.py

@@ -0,0 +1,111 @@
+"""Tests for `walk.walk_package` against a synthetic `tinypkg` fixture."""
+
+import pytest
+
+from api_parity_py import walk
+
+
+def _envelope() -> dict:
+    return walk.walk_package("tinypkg")
+
+
+def _path_kinds(env: dict) -> set[tuple[str, str]]:
+    return {(e["path"], e["kind"]) for e in env["entries"]}
+
+
+def _paths(env: dict) -> set[str]:
+    return {e["path"] for e in env["entries"]}
+
+
+def test_envelope_metadata_matches_schema():
+    """Top-level envelope keys are spelled exactly as SCHEMA.md requires."""
+    env = _envelope()
+    assert env["schema_version"] == 1
+    assert env["kind"] == "reference"
+    assert env["language"] == "python"
+    assert env["source"] == "tinypkg"
+    assert isinstance(env["entries"], list)
+
+
+def test_widget_class_and_members_are_emitted():
+    """Regular method, property, and classmethod all appear with the
+    correct `kind`. The property must be detected via raw-attribute
+    lookup (a `getattr` on the class would invoke the descriptor)."""
+    pk = _path_kinds(_envelope())
+    assert ("tinypkg.core.Widget", "class") in pk
+    assert ("tinypkg.core.Widget.foo", "method") in pk
+    assert ("tinypkg.core.Widget.bar", "property") in pk
+    assert ("tinypkg.core.Widget.bake", "method") in pk
+
+
+def test_underscore_and_data_attrs_excluded():
+    """Underscore-prefixed members and plain class attributes are not
+    API surface and must be omitted from the inventory."""
+    paths = _paths(_envelope())
+    assert "tinypkg.core.Widget._private" not in paths
+    assert "tinypkg.core.Widget.CONSTANT" not in paths
+
+
+def test_nested_class_emitted_with_dotted_qualname():
+    """Nested classes use `cls.__qualname__`, so `Widget.Inner` keeps its
+    lexical structure in the path. Their members get the same treatment."""
+    pk = _path_kinds(_envelope())
+    assert ("tinypkg.core.Widget.Inner", "class") in pk
+    assert ("tinypkg.core.Widget.Inner.baz", "method") in pk
+
+
+def test_data_shape_subclass_filtered_out():
+    """`RowLike(tuple)` is a data container, not API surface. The walker
+    filters subclasses of `(tuple, list, dict, BaseException)`."""
+    paths = _paths(_envelope())
+    assert "tinypkg.core.RowLike" not in paths
+
+
+def test_free_function_kind_is_function():
+    """Module-level free functions are tagged `kind="function"`, distinct
+    from class methods (which use `kind="method"`)."""
+    pk = _path_kinds(_envelope())
+    assert ("tinypkg.extras.helper", "function") in pk
+
+
+def test_underscore_free_function_excluded():
+    paths = _paths(_envelope())
+    assert "tinypkg.extras._hidden" not in paths
+
+
+def test_reexports_not_duplicated():
+    """`tinypkg/__init__.py` re-exports `Widget` and `helper`. They must
+    only appear under their *defining* module to keep the join key
+    unambiguous on the differ side."""
+    paths = _paths(_envelope())
+    assert "tinypkg.Widget" not in paths
+    assert "tinypkg.helper" not in paths
+
+
+def test_entries_are_sorted_and_deduped():
+    """Output stability is part of the wire contract — diffs across two
+    runs of the walker must be minimal noise."""
+    entries = _envelope()["entries"]
+    keys = [(e["path"], e["kind"]) for e in entries]
+    assert keys == sorted(keys)
+    assert len(keys) == len(set(keys))
+
+
+def test_submodule_import_failures_surface_on_stderr(capsys, monkeypatch):
+    """A missing optional dep silently dropped submodules used to make an
+    incomplete walk look complete. The walker now prints a grouped stderr
+    summary so the user notices."""
+    original = walk.importlib.import_module
+
+    def flaky(name: str, *a, **kw):
+        # Make every submodule import after the top-level package raise.
+        if name.startswith("tinypkg.") and name != "tinypkg":
+            raise ImportError("simulated missing dep: pandas")
+        return original(name, *a, **kw)
+
+    monkeypatch.setattr(walk.importlib, "import_module", flaky)
+    walk._preload_submodules("tinypkg")
+    err = capsys.readouterr().err
+    assert "skipped" in err
+    assert "tinypkg" in err
+    assert "simulated missing dep: pandas" in err