Internal Utilities

The utilities documented here are all importable directly from flatland.util, and may be useful for implementing custom schema types and validators using similar semantics to Flatland, or if you’re hacking on Flatland internals yourself. Typical users, however, need not know about these utilities.

flatland.util.base

lazy_property

An @property that is only calculated once.

The results of the decorated function are stored in the instance dictionary after the first access. Subsequent accesses are serviced out of the __dict__ by Python at native attribute access speed.

assignable_property

A @property, computed by default but assignable on a per-instance basis.

Similar to property, except that the attribute may be assigned to and assignments may be deleted.

May be used as a decorator.

assignable_class_property

A read/write property for access on a class or an instance.

Similar to assignable_property, except that access as a class attribute will also return a computed value.

The decorated function will be passed two arguments: instance and class (the same signature as the descriptor __get__ protocol). Instance will be None if the attribute access was against the class.

Note that assignments at the class level are not intercepted by this property. They will replace the property on the class.

May be used as a decorator.

class_cloner

A class-copying classmethod.

Calls the decorated method as a classmethod, passing a copy of the class. The copy will be a direct subclass of the class the method is invoked on.

The class_cloner is only visible at the class level. Instance access is proxied to the instance dictionary.

class as_mapping(target)

Bases: object

Provide a mapping view of an instance.

Similar to vars(), but effective on extension types and will invoke descriptors on access.

class adict

Bases: dict

Allow dict keys to be accessed with getattr().

re_ucompile(pattern, flags=0)

Compile a regex with re.UNICODE on by default.

re_uescape(pattern)

A unicode-friendly version of re.escape.

luhn10(number)

Return True if the number passes the Luhn checksum algorithm.

to_pairs(dictlike)

Yield (key, value) pairs from any dict-like object.

Implements an optimized version of the dict.update() definition of “dictlike”.

keyslice_pairs(pairs, include=None, omit=None, rename=None, key=None)

Filter (key, value) pairs by key and return a subset.

Parameters:

• pairs – an iterable of (key, value) pairs (2-tuples).
• include – optional, a sequence of key values. If supplied, only pairs whose key is a member of this sequence will be returned.
• omit – optional, a sequence of key values. If supplied, all pairs will be returned, save those whose key is a member of this sequence.
• rename – optional, a mapping or sequence of 2-tuples specifying a key-to-key translation. A pair whose key has been renamed by this translation will always be emitted, regardless of include or omit rules. The mapping will be converted to a dict internally, and keys must be hashable.
• key – optional, a function of one argument that is used to extract a comparison key from the first item of each pair. Similar to the key parameter to Python’s sort and sorted. Useful for transforming unicode keys to bytestrings with `key=str, adding or removing prefixes en masse, etc.

Returns:

yields (key, value) pairs.

named_int_factory(name, value, doc='')

Return a unique integer value with a str() and repr() of name.

autodocument_from_superclasses(cls)

Fill in missing documentation on overridden methods.

Can be used as a class decorator.

class symbol

Bases: object

A constant symbol.

>>> symbol('foo') is symbol('foo')
True
>>> symbol('foo')
foo

A slight refinement of the MAGICCOOKIE=object() pattern. The primary advantage of symbol() is its repr(). They are also singletons.

Repeated calls of symbol(‘name’) will all return the same instance.

flatland.util.deferred

class deferred_module(module, deferred, **attributes)

Bases: module

A module whose __all__ members are loaded on first access.

classmethod shadow(module_name, deferred, **attributes)

Replace module_name in sys.modules with a deferred clone.