grabmonkey 1.0.0__tar.gz

grabmonkey-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RexBytes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grabmonkey-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: grabmonkey
+Version: 1.0.0
+Summary: Dot-path access, mutation, and flattening for deeply nested dict/JSON data, with clear error messages.
+Author-email: GoodBoy <pythonic@rexbytes.com>
+License: MIT License
+        
+        Copyright (c) 2026 RexBytes
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/rexbytes/grabmonkey
+Project-URL: Issues, https://github.com/rexbytes/grabmonkey/issues
+Keywords: nested,dict,json,dotpath,path,access,flatten
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Dynamic: license-file
+
+# grabmonkey
+
+Dot-path access, mutation, and flattening for deeply nested dict/JSON data —
+with error messages that tell you exactly which level failed.
+
+Stop writing this:
+
+```python
+data.get("response", {}).get("results", [{}])[0].get("metadata", {}).get("created_at", "")
+```
+
+Write this:
+
+```python
+from grabmonkey import grab
+
+grab(data, "response.results[0].metadata.created_at", default="")
+```
+
+## Install
+
+```bash
+pip install grabmonkey
+```
+
+Requires Python 3.11+. No runtime dependencies.
+
+## Quick start
+
+```python
+from grabmonkey import grab, grab_many, put, delete, flatten, unflatten
+
+data = {"response": {"results": [{"metadata": {"id": 1, "created_at": "2026"}}]}}
+
+# Read, any depth
+grab(data, "response.results[0].metadata.created_at")   # "2026"
+
+# Safe default instead of an exception
+grab(data, "response.results[0].missing", default="")   # ""
+
+# Type coercion on access
+grab({"count": "42"}, "count", as_type=int)             # 42
+
+# Wildcards over lists
+grab({"items": [{"n": 1}, {"n": 2}]}, "items[*].n")     # [1, 2]
+
+# Batch access
+grab_many(data, {"id": "response.results[0].metadata.id"})   # {"id": 1}
+
+# Set and delete (mutates in place, creates intermediate containers)
+d = {}
+put(d, "a.b[2].c", 9)              # {"a": {"b": [None, None, {"c": 9}]}}
+delete(d, "a.b[2].c")              # {"a": {"b": [None, None, {}]}}
+delete(d, "a.b[2]", prune=True)    # {"a": {"b": [None, None]}}  (prune drops empties)
+
+# Flatten / unflatten
+flatten({"a": {"b": [1, 2]}})           # {"a.b[0]": 1, "a.b[1]": 2}
+unflatten({"a.b[0]": 1, "a.b[1]": 2})   # {"a": {"b": [1, 2]}}
+```
+
+## Clear errors
+
+```python
+grab(data, "response.results[0].nope")
+# grabmonkey.errors.PathError:
+# Path 'response.results[0].nope' failed at 'nope':
+# key not found in dict with keys ['metadata']
+```
+
+`PathError` (a `LookupError`) means a structural miss — the case `default=`
+absorbs. `PathSyntaxError` means a malformed path string. `CoercionError` means
+the value was found but `as_type` could not convert it. The last two are *not*
+absorbed by `default=`, on purpose.
+
+## Path syntax
+
+| Syntax | Meaning |
+|---|---|
+| `a.b.c` | dict key or object attribute |
+| `items[0]`, `items[-1]` | sequence index |
+| `items[*]` | every element of a sequence / value of a mapping |
+| `data['weird.key']` | quoted key for keys with dots/brackets/spaces |
+
+Works on dicts, lists, dataclasses, named tuples, and any object with
+attribute access. Strings and bytes are treated as leaf values, not navigable
+containers (see LIMITATIONS.md).
+
+## CLI
+
+Reads JSON from a file (`--input`) or stdin, prints JSON:
+
+```bash
+echo '{"user":{"name":"Alice"}}' | grabmonkey grab user.name   # "Alice"
+echo '{"a":{"b":1}}'             | grabmonkey flatten          # {"a.b": 1}
+grabmonkey grab metadata.id --input response.json
+```
+
+## Using with AI assistants
+
+See [SKILL.md](./SKILL.md) for an LLM-consumable reference (decision table,
+worked examples, anti-patterns). See [LIMITATIONS.md](./LIMITATIONS.md) for
+deliberate design tradeoffs.
+
+## License
+
+MIT

grabmonkey-1.0.0/README.md

@@ -0,0 +1,106 @@
+# grabmonkey
+
+Dot-path access, mutation, and flattening for deeply nested dict/JSON data —
+with error messages that tell you exactly which level failed.
+
+Stop writing this:
+
+```python
+data.get("response", {}).get("results", [{}])[0].get("metadata", {}).get("created_at", "")
+```
+
+Write this:
+
+```python
+from grabmonkey import grab
+
+grab(data, "response.results[0].metadata.created_at", default="")
+```
+
+## Install
+
+```bash
+pip install grabmonkey
+```
+
+Requires Python 3.11+. No runtime dependencies.
+
+## Quick start
+
+```python
+from grabmonkey import grab, grab_many, put, delete, flatten, unflatten
+
+data = {"response": {"results": [{"metadata": {"id": 1, "created_at": "2026"}}]}}
+
+# Read, any depth
+grab(data, "response.results[0].metadata.created_at")   # "2026"
+
+# Safe default instead of an exception
+grab(data, "response.results[0].missing", default="")   # ""
+
+# Type coercion on access
+grab({"count": "42"}, "count", as_type=int)             # 42
+
+# Wildcards over lists
+grab({"items": [{"n": 1}, {"n": 2}]}, "items[*].n")     # [1, 2]
+
+# Batch access
+grab_many(data, {"id": "response.results[0].metadata.id"})   # {"id": 1}
+
+# Set and delete (mutates in place, creates intermediate containers)
+d = {}
+put(d, "a.b[2].c", 9)              # {"a": {"b": [None, None, {"c": 9}]}}
+delete(d, "a.b[2].c")              # {"a": {"b": [None, None, {}]}}
+delete(d, "a.b[2]", prune=True)    # {"a": {"b": [None, None]}}  (prune drops empties)
+
+# Flatten / unflatten
+flatten({"a": {"b": [1, 2]}})           # {"a.b[0]": 1, "a.b[1]": 2}
+unflatten({"a.b[0]": 1, "a.b[1]": 2})   # {"a": {"b": [1, 2]}}
+```
+
+## Clear errors
+
+```python
+grab(data, "response.results[0].nope")
+# grabmonkey.errors.PathError:
+# Path 'response.results[0].nope' failed at 'nope':
+# key not found in dict with keys ['metadata']
+```
+
+`PathError` (a `LookupError`) means a structural miss — the case `default=`
+absorbs. `PathSyntaxError` means a malformed path string. `CoercionError` means
+the value was found but `as_type` could not convert it. The last two are *not*
+absorbed by `default=`, on purpose.
+
+## Path syntax
+
+| Syntax | Meaning |
+|---|---|
+| `a.b.c` | dict key or object attribute |
+| `items[0]`, `items[-1]` | sequence index |
+| `items[*]` | every element of a sequence / value of a mapping |
+| `data['weird.key']` | quoted key for keys with dots/brackets/spaces |
+
+Works on dicts, lists, dataclasses, named tuples, and any object with
+attribute access. Strings and bytes are treated as leaf values, not navigable
+containers (see LIMITATIONS.md).
+
+## CLI
+
+Reads JSON from a file (`--input`) or stdin, prints JSON:
+
+```bash
+echo '{"user":{"name":"Alice"}}' | grabmonkey grab user.name   # "Alice"
+echo '{"a":{"b":1}}'             | grabmonkey flatten          # {"a.b": 1}
+grabmonkey grab metadata.id --input response.json
+```
+
+## Using with AI assistants
+
+See [SKILL.md](./SKILL.md) for an LLM-consumable reference (decision table,
+worked examples, anti-patterns). See [LIMITATIONS.md](./LIMITATIONS.md) for
+deliberate design tradeoffs.
+
+## License
+
+MIT

grabmonkey-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "grabmonkey"
+version = "1.0.0"
+description = "Dot-path access, mutation, and flattening for deeply nested dict/JSON data, with clear error messages."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "GoodBoy", email = "pythonic@rexbytes.com" }]
+requires-python = ">=3.11"
+keywords = ["nested", "dict", "json", "dotpath", "path", "access", "flatten"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov", "hypothesis>=6.0"]
+
+[project.scripts]
+grabmonkey = "grabmonkey.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/rexbytes/grabmonkey"
+Issues   = "https://github.com/rexbytes/grabmonkey/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

grabmonkey-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

grabmonkey-1.0.0/src/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-1.0.0/src/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()}