glom

The glom scope is a dictionary of extra values passed to the top-level glom call. These values can be accessed within the spec using the S object, which supports attribute-style dot-access for its keys.

Basic Usage

Pass a scope dictionary to glom and access its keys via S.

from glom import glom, T, S

count_spec = T.count(S.search)
glom(['a', 'c', 'a', 'b'], count_spec, scope={'search': 'a'})
# Output: 2

Updating the scope with S() and A

Scopes are dynamic. You can save values from the target into the scope using S or A:

• S(key=spec): Evaluates spec and saves the result to key in the scope.
• A.key: A shorthand to assign the current target to key in the scope.

from glom import glom, S, A

target = {'data': {'val': 9}}
# Saving target value to scope
spec = (S(value=T['data']['val']), {'val': S['value']})
glom(target, spec)
# Output: {'val': 9}

# Using A as a shortcut for the current target
spec_alt = ('data.val', A.value, {'val': S.value})
glom(target, spec_alt)
# Output: {'val': 9}

Persistent state with Vars and S.globals

By default, changes to the scope are local to the current spec. To persist state across different parts of a spec, use a Vars object.

• S.globals: A pre-created Vars object available throughout the entire glom call.
• Vars: A mutable namespace that allows child scopes to store state that persists beyond their local scope.

from glom import glom, A, S

# Using S.globals to persist a value
last_spec = ([A.globals.last], S.globals.last)
glom([3, 1, 4, 1, 5], last_spec)
# Output: 5

When implementing complex Specifier Types, follow these patterns to ensure compatibility and robustness:

1. Use the Scope for Recursion: Instead of calling the global glom() function, access it via scope['glom']. This ensures your specifier works correctly even if the user has overridden the glom runtime.
2. Leverage the TargetRegistry: To support new target types or operations, use scope[TargetRegistry].get_handler(operator_name, target, path=scope[Path]). Standard operators include "get", "iterate", "keys", "assign", and "delete".
3. Implement Subspecs: Many specifiers use an __init__ method that accepts a subspec (often defaulting to T). This allows you to fetch a specific part of the data before applying your operation (e.g., Sum(subspec=T)).
4. Error Handling: If a target does not support an operation, raise a descriptive error. You may consider inheriting from glom.GlomError for custom exceptions.

from glom import glom, Path, T
from glom.core import TargetRegistry, UnregisteredTarget

class Sum(object):
    def __init__(self, subspec=T, init=int):
        self.subspec = subspec
        self.init = init

    def glomit(self, target, scope):
        # Use scope['glom'] for subspec execution
        if self.subspec is not T:
            target = scope['glom'](target, self.subspec, scope)

        # Use TargetRegistry to find the 'iterate' handler
        try:
            iterate = scope[TargetRegistry].get_handler('iterate', target, path=scope[Path])
        except UnregisteredTarget as ut:
            raise TypeError(f'can only sum on iterable targets, not {type(target).__name__}')

        iterator = iterate(target)
        return self._sum(iterator)

    def _sum(self, iterator):
        ret = self.init()
        for v in iterator:
            ret += v
        return ret

If you are coming from other data manipulation tools, glom can be understood through several conceptual analogies:

• List Comprehensions: Like Python list comprehensions, glom uses square brackets for list processing (e.g., [lambda x: x % 2]). However, glom requires a callable or another glom spec to enable deferred processing and can return glom.SKIP to exclude items from a list.
• Object Templating: Similar to Jinja, Django, or Mustache, but instead of working on strings or HTML, glom works on Python objects (dicts, functions, primitives, etc.). It is essentially an "object templating" system.
• Query Languages (SQL/GraphQL): glom acts as a Python query language for Python objects. Unlike SQL (which targets tables) or GraphQL (which targets graphs), glom can restructure the shape of the data while fetching and transforming it.
• Data Validation (jsonschema/schema): While validation libraries focus on parsing and structuring, glom excels at the next step: translating valid, structured objects (like database models) into other formats, such as JSON-serializable objects.
• jq: The glom CLI functions similarly to jq, but uses Python as the query language instead of a custom syntax.
• XPath/XSLT: glom draws inspiration from the functional capabilities of XPath/XSLT but aims to be less verbose and less "pure."

The core engine of glom is a recursive loop that processes specs based on their type:

• String or Path: Performs a deep-get on the target.
• Callable: Calls the function on the target.
• Dict: Creates a new dictionary where each key maps to the result of a glom() call on the corresponding subspec.
• List: Runs the first element of the list (the subspec) on every element in the target's iterator.
• Tuple: Chains the specs together, running each subsequent spec on the result of the previous one.

def glom(target, spec):
    if isinstance(spec, (str, Path)):
        return _get_path(target, spec)
    elif callable(spec):
        return spec(target)
    elif isinstance(spec, dict):
        ret = {}
        for field, subspec in spec.items():
           ret[field] = glom(target, subspec)
        return ret
    elif isinstance(spec, list):
        subspec = spec[0]
        iterator = _get_iterator(target)
        return [glom(t, subspec) for t in iterator]
    elif isinstance(spec, tuple):
        res = target
        for subspec in spec:
            res = glom(res, subspec)
        return res
    else:
        raise TypeError('expected one of the above types')