glom Modes

Note

Be sure to read “Writing a custom Specifier Type” before diving into the deep details below.

A glom “mode” determines how Python built-in data structures are evaluated. Think of it like a dialect for how dict, tuple, list, etc., are interpreted in a spec. Modes do not change the behavior of T, or many other core specifiers. Modes are one of the keys to keeping glom specs short and readable.

A mode is used similar to a spec: whatever Python data structure is passed to the mode type constructor will be evaluated under that mode. Once set, the mode remains in place until it is overridden by another mode.

glom only has a few modes:

1. Auto - The default glom behavior, used for data transformation, with the spec acting as a template.

2. Fill - A variant of the default transformation behavior; preferring to “fill” containers instead of iterating, chaining, etc.

3. Match - Treats the spec as a pattern, checking that the target matches.

Adding a new mode is relatively rare, but when it comes up this document includes relevant details.

Writing custom Modes

A mode is a spec which sets scope[MODE] to a function which accepts target, spec, and scope and returns a result, a signature very similar to the top-level glom() method itself.

For example, here is an abbreviated version of the Fill mode:

class Fill(object):
    def __init__(self, spec):
        self.spec = spec

    def glomit(self, target, scope):
        scope[MODE] = _fill
        return scope[glom](target, self.spec, scope)

def _fill(target, spec, scope):
    recurse = lambda val: scope[glom](target, val, scope)
    if type(spec) is dict:
        return {recurse(key): recurse(val)
                for key, val in spec.items()}
    if type(spec) in (list, tuple, set, frozenset):
        result = [recurse(val) for val in spec]
        if type(spec) is list:
            return result
        return type(spec)(result)
    if callable(spec):
         return spec(target)
    return spec

Like any other Specifier Type, Fill has a glomit() method, and this method sets the MODE key in the glom scope to our _fill function. The name itself doesn’t matter, but the signature must match exactly: (target, spec, scope).

As mentioned above, custom modes are relatively rare for glom. If you write one, let us know!