glom

glom gives Python code a single, declarative way to reach into deeply nested data — dicts inside lists inside objects — without chains of .get() calls, try/except KeyError, or manual recursion. A “spec” built from ordinary Python literals (strings, dicts, lists) plus composable helpers like T, Path, Coalesce, and Or describes exactly what to pull out and how to reshape it, and glom(target, spec) walks the target and returns the result in one call. When something goes wrong, glom raises a PathAccessError that names the exact key or index where access failed, instead of an opaque TypeError or KeyError several stack frames deep.

Beyond simple access, glom extends the same spec language to validation (Match, Check, M), in-place mutation (Assign, Delete), reduction (Sum, Fold, Flatten, Merge), and streaming/lazy targets (Iter) — plus a command-line glom tool for exploring and restructuring JSON, YAML, or TOML data straight from the shell. It ships as a pure-Python package tested across CPython 3.7 through 3.14 and PyPy3.

What You Get

• A single glom(target, spec) entrypoint that resolves dotted paths, nested dict/list access, and multi-key extraction in one declarative call
• Composable spec primitives — T, Path, Coalesce, Or/And, Call, Invoke — that build up complex transformations from small, reusable pieces
• A typed error hierarchy (PathAccessError, PathAssignError, CoalesceError) that reports the exact path segment where access or validation failed
• Built-in validation vocabulary (Match, Check, M) and in-place mutation helpers (Assign, Delete) that reuse the same spec language as read access
• A glom command-line tool for restructuring JSON, YAML, or TOML data from the shell without writing a script
• Streaming/lazy support via Iter for processing data too large to hold in memory at once

Common Use Cases

• Pulling specific fields out of deeply nested API or config JSON responses without writing brittle chained .get() calls
• Reshaping one nested data structure into a different nested shape for a downstream API, template, or report
• Validating the shape of untrusted or third-party JSON payloads using Match/Check before the rest of the application touches them
• Producing clear, path-specific error messages when a data pipeline hits malformed or unexpected nested input
• Ad-hoc exploration and restructuring of JSON/YAML/TOML files from the command line via the bundled glom CLI

Under The Hood

Architecture The library is organized around one central evaluator in glom/core.py (~90KB) that defines the glom() function, the Path/T autospec objects for expressing access paths as Python expressions, a ChainMap-backed Scope that threads state through nested spec resolution, and the GlomError exception hierarchy. Companion modules — matching.py (M/Or/And/Match for validation), mutation.py (Assign/Delete for in-place edits), reduction.py (Sum/Fold/Flatten/Merge), streaming.py (Iter for lazy targets), grouping.py (Group), and cli.py (the shell interface) — each register their own spec types into the core dispatch mechanism rather than duplicating traversal logic, giving the codebase a plugin-like layering around a single recursive evaluator. Because every companion module depends on the core scope/dispatch contract, changes to that contract in core.py would ripple through the entire package.

Tech Stack glom is 100% pure Python with no compiled extensions. It depends on boltons (>=19.3.0) for sentinel values and iteration helpers, attrs for structured spec classes, and face (>=20.1.1, from the same author) for the CLI’s argument parsing; optional extras pull in PyYAML and tomli for YAML/TOML target formats. Packaging still uses a classic setup.py/setuptools layout rather than a pyproject.toml-based build, versioned via CalVer (YY.MM.MICRO). Testing runs through tox across CPython 3.7–3.14 and PyPy3, with coverage tracked via coverage.py and uploaded to Codecov; docs are built with Sphinx and hosted on Read the Docs.

Code Quality The test suite spans roughly 180 dedicated test functions across 15+ files (test_basic, test_match, test_mutation, test_streaming, test_error, test_cli, and more), supplemented by around 100 doctest examples embedded directly in core.py and executed via --doctest-modules in the tox config — giving extensive coverage of both unit behavior and documented examples. CI runs the full matrix across 11 Python/OS combinations on every push. Error handling is explicit and typed rather than swallowed, with a dedicated GlomError subclass hierarchy naming the failure path. No py.typed marker or mypy configuration was found, so static type-checking support for consumers is limited despite the strong runtime test discipline.

API Design The core idea — one glom(target, spec) call where the spec is built from ordinary Python literals plus composable objects — lets a single declarative expression replace what would otherwise be a chain of try/except blocks or manual recursive walks. The same spec vocabulary extends naturally into validation (Match/Check) and mutation (Assign/Delete) rather than introducing separate DSLs for each concern, and the bundled CLI reuses that vocabulary from the shell. Documentation is unusually thorough for a library this size — a dedicated tutorial, FAQ, full API reference, and an interactive “glompad” browser playground — and error messages are deliberately structured to show the exact path segment where something went wrong.