grabmonkey 1.0.0__py3-none-any.whl

grabmonkey/__init__.py

@@ -0,0 +1,29 @@
+"""grabmonkey: dot-path access, mutation, and flattening for nested data.
+
+Public API (import from the package root):
+
+    from grabmonkey import grab, grab_many, put, delete, flatten, unflatten
+    from grabmonkey import GrabError, PathSyntaxError, PathError, CoercionError
+"""
+
+from __future__ import annotations
+
+from .access import grab, grab_many
+from .errors import CoercionError, GrabError, PathError, PathSyntaxError
+from .flatten import flatten, unflatten
+from .mutate import delete, put
+
+__all__ = [
+    "grab",
+    "grab_many",
+    "put",
+    "delete",
+    "flatten",
+    "unflatten",
+    "GrabError",
+    "PathSyntaxError",
+    "PathError",
+    "CoercionError",
+]
+
+__version__ = "0.1.0"

grabmonkey/access.py

@@ -0,0 +1,218 @@
+"""Read access: :func:`grab` and :func:`grab_many`.
+
+This module exists to walk a parsed path against in-memory data and either
+return the resolved value or raise a :class:`PathError` whose message names the
+exact segment that failed and why. It treats mappings as key lookups,
+sequences as positional indexing, and anything else as attribute access, so the
+same path works against dicts, lists, dataclasses, named tuples, and plain
+objects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Callable, Mapping as MappingT
+
+from .coerce import coerce_value
+from .errors import PathError
+from .path import (
+    Index,
+    Key,
+    Token,
+    Wildcard,
+    _is_simple_key,
+    _quote_key,
+    parse_path,
+    render_path,
+)
+
+_MISSING = object()
+
+# How many dict keys to list before truncating, in a "key not found" message.
+_MAX_KEYS_SHOWN = 12
+
+
+def _describe_keys(mapping: Mapping[Any, Any]) -> str:
+    keys = list(mapping.keys())
+    shown = ", ".join(repr(k) for k in keys[:_MAX_KEYS_SHOWN])
+    if len(keys) > _MAX_KEYS_SHOWN:
+        shown += f", …(+{len(keys) - _MAX_KEYS_SHOWN} more)"
+    return "[" + shown + "]"
+
+
+def _segment_label(tok: Token) -> str:
+    # Render the failing segment the same way render_path would, so the label is
+    # a literal substring of the rendered path (quoted keys included).
+    if isinstance(tok, Key):
+        return f"'{tok.name}'" if _is_simple_key(tok.name) else _quote_key(tok.name)
+    if isinstance(tok, Index):
+        return f"[{tok.index}]"
+    return "[*]"
+
+
+def _fail(tokens: list[Token], k: int, reason: str) -> PathError:
+    rendered = render_path(tokens[: k + 1])
+    return PathError(
+        f"Path {rendered!r} failed at {_segment_label(tokens[k])}: {reason}"
+    )
+
+
+def _is_seq(value: Any) -> bool:
+    return isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray))
+
+
+def _step(current: Any, tokens: list[Token], k: int) -> Any:
+    tok = tokens[k]
+    if isinstance(tok, Key):
+        if isinstance(current, Mapping):
+            if tok.name in current:
+                return current[tok.name]
+            raise _fail(
+                tokens, k,
+                f"key not found in dict with keys {_describe_keys(current)}",
+            )
+        if current is None:
+            raise _fail(tokens, k, "value is None, cannot look up a key")
+        if isinstance(current, (str, bytes, bytearray)):
+            # str/bytes/bytearray are treated as leaf values, not navigable
+            # containers (see LIMITATIONS.md). Stop here with a clear message
+            # rather than returning a bound method like str.upper.
+            raise _fail(
+                tokens, k,
+                f"reached a {type(current).__name__} leaf, cannot look up a key "
+                f"(str/bytes are leaf values, not containers)",
+            )
+        # Anything else (objects, dataclasses, named tuples) is tried as an
+        # attribute. Named tuples are Sequences, so this must come after the
+        # str/bytes guard but apply to sequences too.
+        try:
+            return getattr(current, tok.name)
+        except AttributeError:
+            raise _fail(
+                tokens, k,
+                f"attribute not found on {type(current).__name__} object",
+            ) from None
+
+    if isinstance(tok, Index):
+        if isinstance(current, Mapping):
+            if tok.index in current:
+                return current[tok.index]
+            raise _fail(
+                tokens, k,
+                f"integer key {tok.index} not found in dict with keys "
+                f"{_describe_keys(current)}",
+            )
+        if current is None:
+            raise _fail(tokens, k, "value is None, cannot index")
+        if _is_seq(current):
+            try:
+                return current[tok.index]
+            except IndexError:
+                raise _fail(
+                    tokens, k,
+                    f"index {tok.index} out of range for "
+                    f"{type(current).__name__} of length {len(current)}",
+                ) from None
+        raise _fail(
+            tokens, k,
+            f"expected a sequence to index, got {type(current).__name__}",
+        )
+
+    raise AssertionError(f"unhandled token type: {tok!r}")  # pragma: no cover
+
+
+def _iter_wildcard(current: Any, tokens: list[Token], k: int):
+    if isinstance(current, Mapping):
+        return list(current.values())
+    if _is_seq(current):
+        return list(current)
+    if current is None:
+        raise _fail(tokens, k, "value is None, cannot expand wildcard '[*]'")
+    raise _fail(
+        tokens, k,
+        f"expected a sequence or mapping to expand '[*]', got "
+        f"{type(current).__name__}",
+    )
+
+
+def _traverse(current: Any, tokens: list[Token], start: int = 0) -> Any:
+    k = start
+    while k < len(tokens):
+        tok = tokens[k]
+        if isinstance(tok, Wildcard):
+            elements = _iter_wildcard(current, tokens, k)
+            results = []
+            for element in elements:
+                try:
+                    results.append(_traverse(element, tokens, k + 1))
+                except PathError:
+                    # Elements that lack the remaining sub-path are skipped, not
+                    # padded; see LIMITATIONS.md ("wildcard skips misses").
+                    continue
+            return results
+        current = _step(current, tokens, k)
+        k += 1
+    return current
+
+
+def grab(
+    data: Any,
+    path: str,
+    *,
+    default: Any = _MISSING,
+    as_type: Callable[[Any], Any] | None = None,
+) -> Any:
+    """Resolve ``path`` against ``data`` and return the value.
+
+    ``default``
+        Returned instead of raising when the path does not resolve
+        (:class:`PathError`). Absent by default, so a miss raises. A
+        :class:`PathSyntaxError` (malformed path) and a :class:`CoercionError`
+        (bad ``as_type``) are *not* absorbed by ``default``.
+    ``as_type``
+        One-argument callable applied to the resolved value. For a wildcard
+        path it is applied to each matched element. The ``default`` is returned
+        as-is and is never coerced.
+
+    Wildcards (``items[*].name``) return a list; elements that lack the
+    sub-path are skipped (see LIMITATIONS.md).
+    """
+    tokens = parse_path(path)
+    try:
+        value = _traverse(data, tokens)
+    except PathError:
+        if default is not _MISSING:
+            return default
+        raise
+
+    if as_type is not None:
+        rendered = render_path(tokens)
+        depth = sum(1 for t in tokens if isinstance(t, Wildcard))
+        value = _coerce_result(value, as_type, rendered, depth)
+    return value
+
+
+def _coerce_result(value: Any, as_type: Callable[[Any], Any], rendered: str, depth: int) -> Any:
+    if depth == 0:
+        return coerce_value(value, as_type, rendered)
+    return [_coerce_result(item, as_type, rendered, depth - 1) for item in value]
+
+
+def grab_many(
+    data: Any,
+    paths: MappingT[str, str],
+    *,
+    default: Any = _MISSING,
+) -> dict[str, Any]:
+    """Resolve several paths at once.
+
+    ``paths`` maps result keys to path strings; the return dict has the same
+    keys mapped to resolved values. ``default`` (one value for all paths) is
+    applied per path exactly as in :func:`grab`.
+    """
+    if not isinstance(paths, Mapping):
+        raise TypeError(
+            f"grab_many expects a mapping of name -> path, got "
+            f"{type(paths).__name__}"
+        )
+    return {name: grab(data, p, default=default) for name, p in paths.items()}

grabmonkey/cli.py

@@ -0,0 +1,170 @@
+"""Command-line interface.
+
+This module is a thin argument-parser and return-code wrapper around the
+library: it loads JSON from a file or stdin, calls one library function, and
+prints the result as JSON. All real behaviour lives in the library modules so
+the CLI and the Python API never drift apart.
+
+Exit codes: 0 success, 1 path/coercion failure against the data, 2 usage or
+syntax error (bad path, unparseable input).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Callable
+
+from .access import grab, grab_many
+from .errors import CoercionError, PathError, PathSyntaxError
+from .flatten import flatten, unflatten
+from .mutate import delete, put
+
+def _cli_bool(value: Any) -> bool:
+    """Parse a CLI boolean by recognised token, not Python truthiness.
+
+    ``bool("false")`` is ``True`` in Python; that footgun is wrong for a CLI, so
+    only explicit tokens are accepted and anything else raises (surfacing as a
+    coercion error / exit 1).
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        low = value.strip().lower()
+        if low in ("true", "1", "yes", "y", "on"):
+            return True
+        if low in ("false", "0", "no", "n", "off", ""):
+            return False
+    raise ValueError(f"not a recognised boolean: {value!r}")
+
+
+_TYPES: dict[str, Callable[[Any], Any]] = {
+    "int": int,
+    "float": float,
+    "str": str,
+    "bool": _cli_bool,
+    "json": lambda v: v,
+}
+
+_MISSING = object()
+
+
+def _read_input(path: str | None) -> str:
+    if path is None or path == "-":
+        return sys.stdin.read()
+    with open(path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def _dump(value: Any) -> str:
+    return json.dumps(value, indent=2, ensure_ascii=False, sort_keys=False)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="grabmonkey",
+        description="Dot-path access for nested JSON.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_input(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--input", "-i", help="JSON file to read (default: stdin)")
+
+    g = sub.add_parser("grab", help="read a value at a path")
+    g.add_argument("path")
+    add_input(g)
+    g.add_argument("--default", help="value (parsed as JSON) to return on a miss")
+    g.add_argument("--type", choices=sorted(_TYPES), help="coerce the resolved value")
+
+    gm = sub.add_parser("grab-many", help="read many paths given as name=path pairs")
+    gm.add_argument("pairs", nargs="+", help="name=path arguments")
+    add_input(gm)
+
+    p = sub.add_parser("put", help="set a value at a path and print the result")
+    p.add_argument("path")
+    p.add_argument("value", help="value to set, parsed as JSON")
+    add_input(p)
+
+    d = sub.add_parser("delete", help="delete a value at a path and print the result")
+    d.add_argument("path")
+    add_input(d)
+    d.add_argument("--prune", action="store_true", help="remove emptied ancestors")
+    d.add_argument("--missing-ok", action="store_true", help="ignore a missing path")
+
+    f = sub.add_parser("flatten", help="flatten nested JSON to a flat dict")
+    add_input(f)
+    f.add_argument("--sep", default=".", help="separator for keys (default '.')")
+
+    u = sub.add_parser("unflatten", help="rebuild nested JSON from a flat dict")
+    add_input(u)
+    u.add_argument("--sep", default=".", help="separator for keys (default '.')")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        data = json.loads(_read_input(args.input))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"grabmonkey: could not read input: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        result = _dispatch(args, data)
+    except json.JSONDecodeError as exc:
+        # A --default / put / delete VALUE argument that is not valid JSON is a
+        # usage error, like unparseable input: exit 2, no traceback.
+        print(f"grabmonkey: invalid JSON in argument: {exc}", file=sys.stderr)
+        return 2
+    except PathSyntaxError as exc:
+        print(f"grabmonkey: {exc}", file=sys.stderr)
+        return 2
+    except (PathError, CoercionError) as exc:
+        print(f"grabmonkey: {exc}", file=sys.stderr)
+        return 1
+
+    print(_dump(result))
+    return 0
+
+
+def _dispatch(args: argparse.Namespace, data: Any) -> Any:
+    if args.command == "grab":
+        default = json.loads(args.default) if args.default is not None else _MISSING
+        as_type = _TYPES[args.type] if args.type else None
+        kwargs: dict[str, Any] = {}
+        if default is not _MISSING:
+            kwargs["default"] = default
+        if as_type is not None:
+            kwargs["as_type"] = as_type
+        return grab(data, args.path, **kwargs)
+
+    if args.command == "grab-many":
+        mapping = {}
+        for pair in args.pairs:
+            if "=" not in pair:
+                raise PathSyntaxError(f"expected name=path, got {pair!r}")
+            name, _, path = pair.partition("=")
+            mapping[name] = path
+        return grab_many(data, mapping)
+
+    if args.command == "put":
+        return put(data, args.path, json.loads(args.value))
+
+    if args.command == "delete":
+        return delete(data, args.path, prune=args.prune, missing_ok=args.missing_ok)
+
+    if args.command == "flatten":
+        return flatten(data, sep=args.sep)
+
+    if args.command == "unflatten":
+        return unflatten(data, sep=args.sep)
+
+    raise AssertionError(f"unhandled command: {args.command}")  # pragma: no cover
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

grabmonkey/coerce.py

@@ -0,0 +1,32 @@
+"""Type coercion for resolved values.
+
+This module exists so ``grab(..., as_type=int)`` has one well-defined failure
+mode: any value that resolves but cannot be passed through ``as_type`` raises
+:class:`CoercionError` (a ``ValueError`` subclass) with the offending value and
+its type in the message, rather than letting a raw ``TypeError``/``ValueError``
+escape with no path context.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .errors import CoercionError
+
+
+def coerce_value(value: Any, as_type: Callable[[Any], Any], rendered_path: str) -> Any:
+    """Return ``as_type(value)``, re-raising failures as :class:`CoercionError`.
+
+    ``as_type`` is any one-argument callable (``int``, ``float``, ``str``, a
+    custom parser). Only ``TypeError`` and ``ValueError`` are translated; any
+    other exception from ``as_type`` propagates unchanged.
+    """
+    try:
+        return as_type(value)
+    except (TypeError, ValueError) as exc:
+        type_name = getattr(as_type, "__name__", repr(as_type))
+        raise CoercionError(
+            f"Path {rendered_path!r} resolved to {value!r} "
+            f"({type(value).__name__}), which could not be coerced via "
+            f"{type_name}: {exc}"
+        ) from exc

grabmonkey/errors.py

@@ -0,0 +1,45 @@
+"""Exception hierarchy for grabmonkey.
+
+This module exists so callers can distinguish *why* an access failed without
+parsing message strings. A malformed path string (a programmer error) is a
+``PathSyntaxError``; a structurally valid path that does not resolve against
+the data (a runtime miss, the case ``default=`` is meant to absorb) is a
+``PathError``; a value that resolved but could not be coerced to the requested
+type is a ``CoercionError``. All three derive from ``GrabError`` so a caller
+can catch the whole family with one ``except``.
+"""
+
+from __future__ import annotations
+
+
+class GrabError(Exception):
+    """Base class for every error raised by grabmonkey."""
+
+
+class PathSyntaxError(GrabError, ValueError):
+    """The path string itself is malformed (unclosed bracket, empty segment).
+
+    This is a programmer error and is *never* absorbed by ``default=``: a
+    default substitutes for data that is absent, not for a path you cannot
+    parse.
+    """
+
+
+class PathError(GrabError, LookupError):
+    """A structurally valid path did not resolve against the data.
+
+    Raised when a dict key is missing, a list index is out of range, an
+    intermediate value is ``None``, or a segment expects a container type the
+    data does not provide. Subclasses :class:`LookupError` (the common base of
+    ``KeyError`` and ``IndexError``) so existing ``except LookupError`` blocks
+    keep working. This is the error ``default=`` absorbs.
+    """
+
+
+class CoercionError(GrabError, ValueError):
+    """A value resolved but could not be coerced to the requested ``as_type``.
+
+    Distinct from :class:`PathError` on purpose: the data was *found*, so
+    silently returning ``default`` would hide a real type problem in the
+    source. ``default=`` does not absorb this error.
+    """