API

class Scalar(value=Unspecified, **kw)

The base implementation of simple values such as a string or number.

Scalar subclasses are responsible for translating the most common data types in and out of Python-native form: strings, numbers, dates, times, Boolean values, etc. Any data which can be represented by a single (name, value) pair is a likely Scalar.

Scalar subclasses have two responsibilities: provide a method to adapt a value to native Python form, and provide a method to serialize the native form to a string.

This class is abstract.

class Number(value=Unspecified, **kw)

Base for numeric fields.

Subclasses provide type_ and format attributes for adapt() and serialize().

class Temporal(value=Unspecified, **kw)

Base for datetime-based date and time fields.

type_

Abstract. The native type for element values, will be called with positional arguments per used below.

regex

Abstract. A regular expression to parse datetime values from a string. Must supply named groupings.

used

Abstract. A sequence of regex match group names. These matches will be converted to ints and supplied to the type_ constructor in the order specified.

format

Abstract. A Python string format for serializing the native value. The format will be supplied a dict containing all attributes of the native type.

class Container(value=Unspecified, **kw)

Holds other schema items.

Base class for elements that can contain other elements, such as List and Dict.

Parameters:

• descent_validators – optional, a sequence of validators that will be run before contained elements are validated.

• validators – optional, a sequence of validators that will be run after contained elements are validated.

• **kw – other arguments common to Element.

class Sequence(value=Unspecified, **kw)

Abstract base of sequence-like Containers.

Instances of Sequence hold other elements and operate like Python lists. Each sequence member will be an instance of member_schema.

Python list methods and operators may be passed instances of member_schema or plain Python values. Using plain values is a shorthand for creating an member_schema instance and set()ting it with the value:

>>> from flatland import Array, Integer
>>> Numbers = Array.of(Integer)
>>> ones = Numbers()
>>> ones.append(1)
>>> ones
[<Integer None; value=1>]
>>> another_one = Integer()
>>> another_one.set(1)
True
>>> ones.append(another_one)
>>> ones
[<Integer None; value=1>, <Integer None; value=1>]

class Mapping(value=Unspecified, **kw)

Base of mapping-like Containers.

class Compound(value=Unspecified, **kw)

A mapping container that acts like a scalar value.

Compound fields are dictionary-like fields that can assemble a u and value from their children, and can decompose a structured value passed to a set() into values for its children.

A simple example is a logical calendar date field composed of 3 separate Integer component fields, year, month and day. The Compound can wrap the 3 parts up into a single logical field that handles datetime.date values. Set a date on the logical field and its component fields will be set with year, month and day; alter the int value of the year component field and the logical field updates the date to match.

Compound is an abstract class. Subclasses must implement compose() and explode().

Composites run validation after their children.