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 el() 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.el('.1').value
u'b'
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.
Return a class with name = name
| Parameter: | name – a string or None. str will be converted to unicode. |
|---|---|
| Returns: | a new class |
Declare the class to hold a sequence of *schema.
| Params *schema: | one or more flatland.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)])
>>> el
[{u'y': <Integer u'y'; value=2>, u'x': <Integer u'x'; value=1>}]
Return a class with attributes set from **overrides.
| Parameter: | **overrides – new values for any attributes already present on the class. A TypeError is raised for unknown attributes. |
|---|---|
| Returns: | a new class |
Return a new element with its value initialized from field defaults.
| Parameter: | **kw – passed through to the element_type. |
|---|
This is a convenience constructor for:
element = cls(**kw)
element.set_default()
Return a new element with its value initialized from pairs.
| Parameter: | **kw – passed through to the element_type. |
|---|
This is a convenience constructor for:
element = cls(**kw)
element.set_flat(pairs)
If true, skip missing index numbers in set_flat(). Default True.
See `Sequences`_ for more information.
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.
Bases: flatland.schema.containers.Sequence
An ordered, homogeneous Sequence.
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.
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.
Return a class with descent validators set to *validators.
| Parameter: | *validators – one or more validator functions, replacing any descent validators present on the class. |
|---|---|
| Returns: | a new class |
Find a child element by string path.
| Parameters: |
|
|---|---|
| Returns: | an Element or raises KeyError. |
>>> first_address = form.el('contact.addresses.0')
>>> first_address.el('street1')
<String u'street1'; value=None>
Given a relative path as above, el() searches for a matching path among the element’s children.
If path begins with sep, the path is considered fully qualified and the search is resolved from the Element.root. The leading sep will always match the root node, regardless of its name.
>>> form.el('.contact.addresses.0.city')
<String u'city'; value=None>
>>> first_address.el('.contact.addresses.0.city')
<String u'city'; value=None>
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.
Find child elements by string path.
| Parameters: |
|
|---|---|
| Returns: | a list of Element instances, an Element if single is true, or raises LookupError. |
>>> cities = form.find('/contact/addresses[:]/city')
>>> [el.value for el in cities]
[u'Kingsport', u'Dunwich']
>>> form.find('/contact/name', single=True)
<String u'name'; value=u'Obed Marsh'>
Export an element hierarchy as a flat sequence of key, value pairs.
| Parameters: |
|
|---|
Encodes the element hierarchy in a sep-separated name string, paired with any representation of the element you like. The default is the Unicode value of the element, and the output of the default flatten() can be round-tripped with set_flat().
Given a simple form with a string field and a nested dictionary:
>>> from flatland import Dict, String
>>> class Nested(Form):
... contact = Dict.of(String.named(u'name'),
... Dict.named(u'address'). ... of(String.named(u'email')))
...
>>> element = Nested()
>>> element.flatten()
[(u'contact_name', u''), (u'contact_address_email', u'')]
The value of each pair can be customized with the value callable:
>>> element.flatten(value=operator.attrgetter('u'))
[(u'contact_name', u''), (u'contact_address_email', u'')]
>>> element.flatten(value=lambda el: el.value)
[(u'contact_name', None), (u'contact_address_email', None)]
Solo elements will return a sequence containing a single pair:
>>> element['name'].flatten()
[(u'contact_name', u'')]
Return the element’s complete flattened name as a string.
Joins this element’s path with sep and returns the fully qualified, flattened name. Encodes all Container and other structures into a single string.
Example:
>>> import flatland
>>> form = flatland.List('addresses',
... flatland.String('address'))
>>> element = form()
>>> element.set([u'uptown', u'downtown'])
>>> element.el('0').value
u'uptown'
>>> element.el('0').flattened_name()
u'addresses_0_address'
Return the fully qualified path name of the element.
Returns a sep-separated string of el() compatible element indexes starting from the Element.root (.) down to the element.
>>> from flatland import Dict, Integer
>>> Point = Dict.named(u'point').of(Integer.named(u'x'),
... Integer.named(u'y'))
>>> p = Point(dict(x=10, y=20))
>>> p.name
u'point'
>>> p.fq_name()
u'.'
>>> p['x'].name
u'x'
>>> p['x'].fq_name()
u'.x'
The index used in a path may not be the name of the element. For example, sequence members are referenced by their numeric index.
>>> from flatland import List, String
>>> Addresses = List.named('addresses').of(String.named('address'))
>>> form = Addresses([u'uptown', u'downtown'])
>>> form.name
u'addresses'
>>> form.fq_name()
u'.'
>>> form[0].name
u'address'
>>> form[0].fq_name()
u'.0'
Return a class with additional descent *validators.
| Parameters: |
|
|---|---|
| Returns: | a new class |
Return a class with additional *validators.
| Parameters: |
|
|---|---|
| Returns: | a new class |
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.
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.
Return a class with name = name
| Parameter: | name – a string or None. str will be converted to unicode. |
|---|---|
| Returns: | a new class |
Declare the class to hold a sequence of *schema.
| Params *schema: | one or more flatland.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)])
>>> el
[{u'y': <Integer u'y'; value=2>, u'x': <Integer u'x'; value=1>}]
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.
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() the element to the schema default.
List’s set_default supports two modes for default values:
Set element values from pairs, expanding the element tree as needed.
Given a sequence of name/value tuples or a dict, build out a structured tree of value elements.
Return a class with attributes set from **overrides.
| Parameter: | **overrides – new values for any attributes already present on the class. A TypeError is raised for unknown attributes. |
|---|---|
| Returns: | a new class |
Assess the validity of this element and its children.
| Parameters: |
|
|---|
Iterates through this element and all of its children, invoking each element’s schema.validate_element(). Each element will be visited twice: once heading down the tree, breadth-first, and again heading back up in reverse order.
Returns True if all validations pass, False if one or more fail.
Validates on the first (downward) and second (upward) pass.
If descent_validators are defined on the schema, they will be evaluated before children are validated. If a validation function returns flatland.SkipAll or flatland.SkipFalse, downward validation will halt on this container and children will not be validated.
If validators are defined, they will be evaluated after children are validated.
See FieldSchema.validate_element().
Return a class with validators set to *validators.
| Parameter: | *validators – one or more validator functions, replacing any validators present on the class. |
|---|---|
| Returns: | a new class |
A calculated “default” value.
If default_factory is present, it will be called with the element as a single positional argument. The result of the call will be returned.
Otherwise, returns default.
When comparing an element’s value to its default value, use this property in the comparison.