API — flatland 0.8.1 documentation

# API

class `Scalar`(value=Unspecified, **kw)

  Bases: `flatland.schema.base.Element`

  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.

  `set`(obj)

    Process obj and assign the native and text values.

    Returns: | True if adaptation of obj was successful.

    Attempts to adapt the given object and assigns this element’s `value` and `u` attributes in tandem.

    If adaptation succeeds, `.value` will contain the `adapted` native Python value and `.u` will contain a text `serialized` version of it. A native value of `None` will be represented as `u''` in `.u`.

    If adaptation fails, `.value` will be `None` and `.u` will contain `str(obj)` (or unicode), or `u''` for none.

  `adapt`(obj)

    Given any object obj, try to coerce it into native format.

    Returns: | the native format or raises AdaptationError on failure.

    This abstract method is called by `set()`.

  `serialize`(obj)

    Given any object obj, coerce it into a text representation.

    Returns: | Must return a Unicode text object, always.

    No special effort is made to coerce values not of native or a compatible type.

    This semi-abstract method is called by `set()`. The base implementation returns `str(obj)` (or unicode).

  `set_default`()

    set() the element to the schema default.

class `Number`(value=Unspecified, **kw)

  Bases: `flatland.schema.scalars.Scalar`

  Base for numeric fields.

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

  `type_` = None

    The Python type for values, such as `int` or `float`.

  `signed` = True

    If true, allow negative numbers. Default `True`.

  `format` = u'%s'

    The `text` serialization format.

  `adapt`(value)

    Generic numeric coercion.

    Returns: | an instance of `type_` or `None`

    Attempt to convert value using the class’s `type_` callable.

  `serialize`(value)

    Generic numeric serialization.

    Returns: | Unicode text formatted with `format` or the `str()` (or unicode) of value if value is not of `type_`

    Converts value to a string using Python’s string formatting function and the `format` as the template. The value is provided to the format as a single, positional format argument.

class `Temporal`(value=Unspecified, **kw)

  Bases: `flatland.schema.scalars.Scalar`

  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.

  `adapt`(value)

    Coerces value to a native type.

    If value is an instance of `type_`, returns it unchanged. If a string, attempts to parse it and construct a `type` as described in the attribute documentation.

  `serialize`(value)

    Serializes value to string.

    If value is an instance of `type`, formats it as described in the attribute documentation. Otherwise returns `str(value)` (or unicode).

class `Container`(value=Unspecified, **kw)

  Bases: `flatland.schema.base.Element`

  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`.

  `descent_validators` = ()

    Todo

    doc descent_validators

  `descent_validated_by`(*validators)

    Return a class with descent validators set to *validators.

    Parameters: | *validators – one or more validator functions, replacing any descent validators present on the class.
    Returns: | a new class

  `including_descent_validators`(*validators, **kw)

    Return a class with additional descent *validators.

    Parameters: | *validators – one or more validator functions position – defaults to -1. By default, additional validators are placed after existing descent validators. Use 0 for before, or any other list index to splice in validators at that point.
    Returns: | a new class

class `Sequence`(value=Unspecified, **kw)

  Bases: `flatland.schema.containers.Container`, `list`

  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>]

  `member_schema` = None

    An `Element` class for sequence members.

  `prune_empty` = True

    If true, skip missing index numbers in `set_flat()`. Default True.

    See `Sequences`_ for more information.

  `of`(*schema)

    Declare the class to hold a sequence of *schema.

    Params *schema: | one or more `Element` classes
    Returns: | cls

    Configures the `member_schema` of cls to hold instances of *schema.

        >>> from flatland import Array, String
        >>> Names = Array.of(String.named('name'))
        >>> Names.member_schema
        <class 'flatland.schema.scalars.String'>
        >>> el = Names(['Bob', 'Biff'])
        >>> el
        [<String u'name'; value=u'Bob'>, <String u'name'; value=u'Biff'>]

    If more than one `Element` is specified in *schema, an anonymous `Dict` is created to hold them.

        >>> from flatland import Integer
        >>> Points = Array.of(Integer.named('x'), Integer.named('y'))
        >>> Points.member_schema
        <class 'flatland.schema.containers.Dict'>
        >>> el = Points([dict(x=1, y=2)])
        >>> point = el[0]
        >>> point['x']
        <Integer u'x'; value=1>
        >>> point['y']
        <Integer u'y'; value=2>

  `set`(iterable)

    Assign the native and Unicode value.

    Attempts to adapt the given iterable and assigns this element’s `value` and `u` attributes in tandem. Returns True if the adaptation was successful. See `Element.set()`.

    Set must be supplied a Python sequence or iterable:

        >>> from flatland import Integer, List
        >>> Numbers = List.of(Integer)
        >>> nums = Numbers()
        >>> nums.set([1, 2, 3, 4])
        True
        >>> nums.value
        [1, 2, 3, 4]

  `set_default`()

    set() the element to the schema default.

  `append`(value)

    Append value to end.

    If value is not an instance of `member_schema`, it will be wrapped in a new element of that type before appending.

  `extend`(iterable)

    Append iterable values to the end.

    If values of iterable are not instances of `member_schema`, they will be wrapped in a new element of that type before extending.

  `insert`(index, value)

    Insert value at index.

    If value is not an instance of `member_schema`, it will be wrapped in a new element of that type before inserting.

  `remove`(value)

    Remove member with value value.

    If value is not an instance of `member_schema`, it will be wrapped in a new element of that type before searching for a matching element to remove.

  `index`(value)

    Return first index of value.

    If value is not an instance of `member_schema`, it will be wrapped in a new element of that type before searching for a matching element in the sequence.

  `count`(value)

    Return number of occurrences of value.

    If value is not an instance of `member_schema`, it will be wrapped in a new element of that type before searching for matching elements in the sequence.

class `Mapping`(value=Unspecified, **kw)

  Bases: `flatland.schema.containers.Container`, `dict`

  Base of mapping-like Containers.

  `field_schema` = ()

    Todo

    doc field_schema

  `may_contain`(key)

    Return True if the element schema allows a field named key.

  `clear`() → None. Remove all items from D.
  `popitem`() → (k, v), remove and return some (key, value) pair as a

    2-tuple; but raise KeyError if D is empty.

  `pop`(k[, d]) → v, remove specified key and return the corresponding value.

    If key is not found, d is returned if given, otherwise KeyError is raised

  `update`(*dictish, **kwargs)

    Update with keys from dict-like *dictish and **kwargs

  `setdefault`(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  `get`(k[, d]) → D[k] if k in D, else d. d defaults to None.
  `set`(value)

    Todo

    doc set()

  `set_default`()

    set() the element to the schema default.

  `u`

    A string repr of the element.

  `value`

    The element as a regular Python dictionary.

  `is_empty`

    Mappings are never empty.

class `Compound`(value=Unspecified, **kw)

  Bases: `flatland.schema.containers.Mapping`, `flatland.schema.scalars.Scalar`

  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.

  `compose`()

    Return a text, native tuple built from children’s state.

    Returns: | a 2-tuple of text representation, native value. These correspond to the `serialize_element()` and `adapt_element()` methods of `Scalar` objects.

    For example, a compound date field may return a ‘-‘ delimited string of year, month and day digits and a `datetime.date`.

  `explode`(value)

    Given a compound value, assign values to children.

    Parameters: | value – a value to be adapted and exploded

    For example, a compound date field may read attributes from a `datetime.date` value and `set()` them on child fields.

    The decision to perform type checking on value is completely up to you and you may find you want different rules for different compound types.

  `serialize`(value)

    Not implemented for Compound types.

  `set`(value)

    Todo

    doc set()

  `is_empty`

    True if all subfields are empty.