Lists — flatland 0.8.1 documentation

# Lists

Instances of `List` hold other elements and operate like Python lists. Lists are configured with a `member_schema`, such as an `Integer`. Each list member will be an instance of that type. The `List.of()` schema constructor will set `member_schema`:

    >>> from flatland import List, Integer
    >>> Numbers = List.of(Integer)
    >>> Numbers.member_schema
    <class 'flatland.schema.scalars.Integer'>

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

    >>> ones = Numbers()
    >>> ones.append(1)
    >>> ones.value
    [1]
    >>> another_one = Integer()
    >>> another_one.set(1)
    True
    >>> ones.append(another_one)
    >>> ones.value
    [1, 1]

List extends `Sequence` and adds positional naming to its elements. Elements are addressable via their list index in `find()` and their index in the list is reflected in their flattened name:

Example:

    >>> from flatland import List, String
    >>> Names = List.named('names').of(String.named('name'))
    >>> names = Names([u'a', u'b'])
    >>> names.value
    [u'a', u'b']
    >>> names.flatten()
    [(u'names_0_name', u'a'), (u'names_1_name', u'b')]
    >>> names[1].value
    u'b'
    >>> names.find_one('1').value
    u'b'

## Validation

If `descent_validators` is defined, these validators will be run first, before member elements are validated.

If `validators` is defined, these validators will be run after member elements are validated.

## `List`

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

  Bases: `flatland.schema.containers.Sequence`

  An ordered, homogeneous Sequence.

  `slot_type`

    alias of `ListSlot`

  `member_schema` = ()

    An `Element` class for member elements.

    See also the `of()` schema configuration method.

  `maximum_set_flat_members` = 1024

    Maximum list members set in a `set_flat()` operation.

    Once this maximum of child members has been added, subsequent data will be dropped. This ceiling prevents denial of service attacks when processing Lists with `prune_empty` set to False; without it remote attackers can trivially exhaust memory by specifying one low and one very high index.

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

  `pop`([index]) → item -- remove and return item at index (default last).

    Raises IndexError if list is empty or index is out of range.

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

  `sort`(cmp=None, key=None, reverse=False)

    L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

  `reverse`()

    L.reverse() – reverse IN PLACE

  `set_default`()

    set() the element to the schema default.

    List’s set_default supports two modes for `default` values:

    - If default is an integer, the List will be filled with that many elements. Each element will then have `set_default()` called on it.
    - Otherwise if default has a value, the list will be `set()` with it.