Constrained Types

class Constrained(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Scalar

A scalar type with a constrained set of legal values.

Wraps another scalar type and ensures that a value set() is within bounds defined by valid_value(). If valid_value() returns false, the element is not converted and will have a value of None.

Constrained is a semi-abstract class that requires an implementation of valid_value(), either by subclassing or overriding on a per-instance basis through the constructor.

An example of a wrapper of int values that only allows the values of 1, 2 or 3:

>>> from flatland import Constrained, Integer
>>> def is_valid(element, value):
...     return value in (1, 2, 3)
>>> schema = Constrained.using(child_type=Integer, valid_value=is_valid)
>>> element = schema()
>>> element.set(u'2')
>>> element.value
>>> element.set(u'5')
>>> element.value is None

Enum is a subclass which provides a convenient enumerated wrapper.

static valid_value(element, value)

Returns True if value for element is within the constraints.

This method is abstract. Override in a subclass or pass a custom callable to the Constrained constructor.

TODO: doc


Schema Constructors

classmethod Enum.named(name)

Return a class with name = name

Parameter:name – a string or None. str will be converted to unicode.
Returns:a new class
classmethod Enum.valued(*enum_values)

Return a class with valid_values = enum_values

Parameter:*enum_values – zero or more values for valid_values.
Returns:a new class
classmethod Element.using(**overrides)

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

Factory Methods

classmethod Element.from_defaults(**kw)

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)
classmethod Element.from_flat(pairs, **kw)

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)

Configurable Attributes

TODO: doc

Valid element values.

Attempting to set() a value not present in valid_values will cause an adaptation failure, and value will be None.


class Enum(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Constrained

A scalar type with a limited set of allowed values.

By default values are strings, but can be of any type you like by customizing child_type.

Register an error message on this element, ignoring duplicates.
Register a warning message on this element, ignoring duplicates.
el(path, sep=u'.')

Find a child element by string path.

  • path – a sep-separated string of element names, or an iterable of names
  • sep – optional, a string separator used to parse path

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>
find(path, single=False, strict=True)

Find child elements by string path.

  • path – a /-separated string specifying elements to select, such as ‘child/grandchild/greatgrandchild’. Relative & absolute paths are supported, as well as container expansion. See Path Lookups.
  • single – if true, return a scalar result rather than a list of elements. If no elements match path, None is returned. If multiple elements match, a LookupError is raised. If multiple elements are found and strict is false, an unspecified element from the result set is returned.
  • strict – defaults to True. If path specifies children or sequence indexes that do not exist, a :ref:`LookupError is raised.

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'>
flatten(sep=u'_', value=<operator.attrgetter object at 0x16cdd30>)

Export an element hierarchy as a flat sequence of key, value pairs.

  • sep – a string, will join together element names.
  • value – a 1-arg callable called once for each element. Defaults to a callable that returns the u of each element.

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.


>>> import flatland
>>> form = flatland.List('addresses',
...                      flatland.String('address'))
>>> element = form()
>>> element.set([u'uptown', u'downtown'])
>>> element.el('0').value
>>> element.el('0').flattened_name()

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
>>> p.fq_name()
>>> p['x'].name
>>> p['x'].fq_name()

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
>>> form.fq_name()
>>> form[0].name
>>> form[0].fq_name()
classmethod including_validators(*validators, **kw)

Return a class with additional *validators.

  • *validators – one or more validator functions
  • position – defaults to -1. By default, additional validators are placed after existing validators. Use 0 for before, or any other list index to splice in validators at that point.

a new class


Assign the native and Unicode value.

Returns:True if adaptation of value was successful.

Attempts to adapt the given value 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 Unicode 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 unicode(value) or u'' for none.

set() the element to the schema default.
set_flat(pairs, sep=u'_')

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.

valid_value(element, value)
True if value is within valid_values.
validate(state=None, recurse=True)

Assess the validity of this element and its children.

  • state – optional, will be passed unchanged to all validator callables.
  • recurse – if False, do not validate children. :returns: True or False

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.

validate_element(state, descending)

Validates on the first, downward pass.

See FieldSchema.validate_element().

classmethod validated_by(*validators)

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
classmethod valued(*enum_values)

Return a class with valid_values = enum_values

Parameter:*enum_values – zero or more values for valid_values.
Returns:a new class
classmethod with_properties(*iterable, **properties)
TODO: doc
An iterator of all child elements, breadth-first.
True if this element and all children are valid.
An iterator of immediate child elements.

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.

True if the element has no value.
An iterator of all parent elements.
An iterator of all elements from root to the Element, inclusive.
The top-most parent of the element.

Valid element values.

Attempting to set() a value not present in valid_values will cause an adaptation failure, and value will be None.

Sugar, the xml-escaped value of u.
Sugar, the xml-attribute-escaped value of u.