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.