understand-quickly 0.1.0__py3-none-any.whl

understand_quickly/__init__.py

@@ -0,0 +1,64 @@
+"""understand-quickly Python SDK.
+
+A thin client for the public registry of code-knowledge graphs at
+https://looptech-ai.github.io/understand-quickly/.
+
+>>> from understand_quickly import Registry
+>>> reg = Registry()
+>>> entries = reg.list(status="ok")
+"""
+
+from __future__ import annotations
+
+from .aclient import AsyncRegistry
+from .client import (
+    DEFAULT_REGISTRY_URL,
+    ENV_VAR,
+    Registry,
+    RegistryError,
+    RegistryHTTPError,
+    RegistryParseError,
+)
+from .types import (
+    Entry,
+    EntryStatus,
+    Graph,
+    SearchHit,
+    Stats,
+    StatsConcept,
+    StatsKind,
+    StatsLanguage,
+    StatsTotals,
+    TopKind,
+    WellKnown,
+    WellKnownRepo,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # clients
+    "Registry",
+    "AsyncRegistry",
+    # errors
+    "RegistryError",
+    "RegistryHTTPError",
+    "RegistryParseError",
+    # constants
+    "DEFAULT_REGISTRY_URL",
+    "ENV_VAR",
+    # types
+    "Entry",
+    "EntryStatus",
+    "Graph",
+    "SearchHit",
+    "Stats",
+    "StatsConcept",
+    "StatsKind",
+    "StatsLanguage",
+    "StatsTotals",
+    "TopKind",
+    "WellKnown",
+    "WellKnownRepo",
+]

understand_quickly/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m understand_quickly``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

understand_quickly/aclient.py

@@ -0,0 +1,217 @@
+"""Asynchronous client for the understand-quickly registry, backed by ``httpx``."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Iterable, Optional
+
+import httpx
+
+from .client import (
+    DEFAULT_CACHE_TTL_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    RegistryError,
+    RegistryHTTPError,
+    RegistryParseError,
+    USER_AGENT,
+    _decode_json,
+    _join,
+    _matches,
+    _normalize_repo_url,
+    _resolve_base_url,
+)
+from .types import Entry, Graph, Registry as RegistryDoc, SearchHit, Stats, WellKnown
+
+
+class AsyncRegistry:
+    """Async client mirroring :class:`understand_quickly.Registry`.
+
+    Use as an async context manager so the underlying ``httpx.AsyncClient``
+    is closed cleanly::
+
+        async with AsyncRegistry() as reg:
+            entries = await reg.list(status="ok")
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        *,
+        cache_ttl: float = DEFAULT_CACHE_TTL_SECONDS,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        client: Optional[httpx.AsyncClient] = None,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self.base_url = _resolve_base_url(base_url)
+        self.cache_ttl = float(cache_ttl)
+        self.timeout = float(timeout)
+        self._cache: dict[str, tuple[float, Any]] = {}
+        self._owns_client = client is None
+        if client is not None:
+            self._client = client
+        else:
+            kwargs: dict[str, Any] = {
+                "timeout": self.timeout,
+                "headers": {"Accept": "application/json", "User-Agent": USER_AGENT},
+            }
+            if transport is not None:
+                kwargs["transport"] = transport
+            self._client = httpx.AsyncClient(**kwargs)
+
+    # ---- lifecycle -------------------------------------------------------
+
+    async def __aenter__(self) -> "AsyncRegistry":
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying ``httpx.AsyncClient`` when we own it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    # ---- low-level fetch -------------------------------------------------
+
+    async def _fetch_json(self, url: str) -> Any:
+        now = time.monotonic()
+        if self.cache_ttl > 0:
+            cached = self._cache.get(url)
+            if cached is not None and (now - cached[0]) < self.cache_ttl:
+                return cached[1]
+        try:
+            resp = await self._client.get(url)
+        except httpx.HTTPError as exc:
+            raise RegistryError(f"GET {url} failed: {exc}") from exc
+        if resp.status_code < 200 or resp.status_code >= 300:
+            raise RegistryHTTPError(url, resp.status_code, resp.content)
+        data = _decode_json(url, resp.content)
+        if self.cache_ttl > 0:
+            self._cache[url] = (now, data)
+        return data
+
+    def clear_cache(self) -> None:
+        self._cache.clear()
+
+    # ---- documents -------------------------------------------------------
+
+    async def registry(self) -> RegistryDoc:
+        return await self._fetch_json(_join(self.base_url, "registry.json"))
+
+    async def well_known(self) -> WellKnown:
+        return await self._fetch_json(_join(self.base_url, ".well-known/repos.json"))
+
+    async def stats(self) -> Stats:
+        return await self._fetch_json(_join(self.base_url, "stats.json"))
+
+    # ---- high-level helpers ---------------------------------------------
+
+    async def list(
+        self,
+        *,
+        status: Optional[str] = None,
+        format: Optional[str] = None,
+        owner: Optional[str] = None,
+        tag: Optional[str] = None,
+    ) -> list[Entry]:
+        doc = await self.registry()
+        entries: Iterable[Entry] = doc.get("entries", []) or []
+        results: list[Entry] = []
+        for entry in entries:
+            if not _matches(entry, status=status, format=format, owner=owner):
+                continue
+            if tag is not None:
+                tags = entry.get("tags") or []
+                if tag not in tags:
+                    continue
+            results.append(entry)
+        return results
+
+    async def get_entry(self, entry_id: str) -> Optional[Entry]:
+        for entry in await self.list():
+            if entry.get("id") == entry_id:
+                return entry
+        return None
+
+    async def get_graph(self, entry_id: str) -> Graph:
+        entry = await self.get_entry(entry_id)
+        if entry is None:
+            raise RegistryError(f"no entry with id={entry_id!r}")
+        graph_url = entry.get("graph_url")
+        if not graph_url:
+            raise RegistryError(f"entry {entry_id!r} has no graph_url")
+        return await self._fetch_json(graph_url)
+
+    async def find_graph_for_repo(self, repo: str) -> Optional[Entry]:
+        norm = _normalize_repo_url(repo)
+        if norm is None:
+            return None
+        owner, repo_name = norm
+        for entry in await self.list():
+            e_owner = (entry.get("owner") or "").lower()
+            e_repo = (entry.get("repo") or "").lower()
+            if e_owner == owner and e_repo == repo_name:
+                return entry
+        return None
+
+    async def search(self, query: str, *, scope: str = "all") -> list[SearchHit]:
+        if not query:
+            return []
+        q = query.lower()
+        hits: list[SearchHit] = []
+
+        if scope in ("all", "concepts"):
+            try:
+                stats = await self.stats()
+            except RegistryError:
+                stats = {}
+            entry_lookup: dict[str, Entry] = {}
+            try:
+                entries = await self.list()
+                entry_lookup = {e.get("id", ""): e for e in entries if e.get("id")}
+            except RegistryError:
+                entry_lookup = {}
+            for concept in stats.get("concepts", []) or []:
+                term = (concept.get("term") or "").lower()
+                if q in term:
+                    samples = concept.get("samples") or []
+                    for sample in samples:
+                        hits.append(
+                            {
+                                "term": concept.get("term", ""),
+                                "entry_id": sample,
+                                "entry": entry_lookup.get(sample, {}),
+                                "samples": list(samples),
+                                "count": int(concept.get("entries", 0) or 0),
+                            }
+                        )
+
+        if scope in ("all", "entries"):
+            for entry in await self.list():
+                blob_parts: list[str] = []
+                for key in ("id", "description", "format"):
+                    val = entry.get(key)
+                    if isinstance(val, str):
+                        blob_parts.append(val)
+                for key in ("tags", "languages"):
+                    val = entry.get(key)
+                    if isinstance(val, list):
+                        blob_parts.extend(str(x) for x in val)
+                blob = "\n".join(blob_parts).lower()
+                if q in blob:
+                    hits.append(
+                        {
+                            "term": query,
+                            "entry_id": entry.get("id", ""),
+                            "entry": entry,
+                        }
+                    )
+        return hits
+
+
+__all__ = [
+    "AsyncRegistry",
+    "RegistryError",
+    "RegistryHTTPError",
+    "RegistryParseError",
+]

understand_quickly/cli.py

@@ -0,0 +1,160 @@
+"""``python -m understand_quickly`` — JSON-first command-line interface.
+
+Subcommands:
+- ``list``         List registry entries (filterable).
+- ``get-graph``    Fetch a graph body by entry id.
+- ``find``         Resolve a GitHub URL or ``owner/repo`` to its entry.
+- ``search``       Cross-graph concept + entry search.
+- ``stats``        Aggregate stats across the registry.
+
+JSON output by default; ``--pretty`` adds indented formatting (and table
+shaping for ``list``). Exit codes: ``0`` success, ``1`` not-found, ``2``
+HTTP/parse error, ``64`` usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Optional, Sequence
+
+from . import __version__
+from .client import Registry, RegistryError, RegistryHTTPError
+
+
+EXIT_OK = 0
+EXIT_NOT_FOUND = 1
+EXIT_ERROR = 2
+EXIT_USAGE = 64
+
+
+def _emit(data: Any, pretty: bool, *, fp: Any = None) -> None:
+    out = fp or sys.stdout
+    if pretty and isinstance(data, list) and data and isinstance(data[0], dict):
+        # Pretty-print a list of dicts as a compact table for `list`.
+        keys = ["id", "format", "status", "last_synced"]
+        rows = [[str(item.get(k, "")) for k in keys] for item in data]
+        widths = [max(len(k), *(len(r[i]) for r in rows)) for i, k in enumerate(keys)]
+        header = "  ".join(k.ljust(widths[i]) for i, k in enumerate(keys))
+        sep = "  ".join("-" * w for w in widths)
+        print(header, file=out)
+        print(sep, file=out)
+        for row in rows:
+            print("  ".join(row[i].ljust(widths[i]) for i in range(len(keys))), file=out)
+        return
+    if pretty:
+        json.dump(data, out, indent=2, sort_keys=False)
+        out.write("\n")
+    else:
+        json.dump(data, out)
+        out.write("\n")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="understand-quickly",
+        description="Thin client for the understand-quickly registry of code-knowledge graphs.",
+    )
+    parser.add_argument("--version", action="version", version=f"understand-quickly {__version__}")
+    parser.add_argument(
+        "--registry",
+        dest="registry_url",
+        default=None,
+        help="Override the registry base URL (defaults to UNDERSTAND_QUICKLY_REGISTRY env var).",
+    )
+    parser.add_argument(
+        "--pretty", action="store_true", help="Pretty-print human-friendly output."
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=30.0,
+        help="HTTP timeout in seconds (default: 30).",
+    )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Disable the in-memory TTL cache for this invocation.",
+    )
+
+    sub = parser.add_subparsers(dest="cmd", required=True, metavar="<command>")
+
+    p_list = sub.add_parser("list", help="List registry entries.")
+    p_list.add_argument("--status", default=None)
+    p_list.add_argument("--format", dest="fmt", default=None)
+    p_list.add_argument("--owner", default=None)
+    p_list.add_argument("--tag", default=None)
+
+    p_get = sub.add_parser("get-graph", help="Fetch the graph body for an entry id.")
+    p_get.add_argument("entry_id")
+
+    p_find = sub.add_parser("find", help="Find the entry for a GitHub URL or owner/repo slug.")
+    p_find.add_argument("repo")
+
+    p_search = sub.add_parser("search", help="Search entries and concepts.")
+    p_search.add_argument("query")
+    p_search.add_argument(
+        "--scope", choices=("all", "entries", "concepts"), default="all"
+    )
+
+    sub.add_parser("stats", help="Print the aggregate stats.json document.")
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = _build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        # argparse exits 2 on usage errors; remap to 64 for clarity.
+        return EXIT_USAGE if exc.code == 2 else int(exc.code or 0)
+
+    cache_ttl = 0.0 if args.no_cache else 60.0
+    try:
+        reg = Registry(args.registry_url, cache_ttl=cache_ttl, timeout=args.timeout)
+    except RegistryError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+    try:
+        if args.cmd == "list":
+            data = reg.list(status=args.status, format=args.fmt, owner=args.owner, tag=args.tag)
+            _emit(data, args.pretty)
+            return EXIT_OK
+        if args.cmd == "get-graph":
+            data = reg.get_graph(args.entry_id)
+            _emit(data, args.pretty)
+            return EXIT_OK
+        if args.cmd == "find":
+            entry = reg.find_graph_for_repo(args.repo)
+            if entry is None:
+                print(f"no entry matches {args.repo!r}", file=sys.stderr)
+                _emit(None, args.pretty)
+                return EXIT_NOT_FOUND
+            _emit(entry, args.pretty)
+            return EXIT_OK
+        if args.cmd == "search":
+            data = reg.search(args.query, scope=args.scope)
+            _emit(data, args.pretty)
+            return EXIT_OK
+        if args.cmd == "stats":
+            _emit(reg.stats(), args.pretty)
+            return EXIT_OK
+    except RegistryHTTPError as exc:
+        print(f"http error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+    except RegistryError as exc:
+        msg = str(exc)
+        print(f"error: {msg}", file=sys.stderr)
+        if msg.startswith("no entry"):
+            return EXIT_NOT_FOUND
+        return EXIT_ERROR
+
+    parser.print_help(sys.stderr)
+    return EXIT_USAGE
+
+
+if __name__ == "__main__":  # pragma: no cover — exercised via subprocess in tests
+    raise SystemExit(main())