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.
