API¶
-
class
Scalar
(value=Unspecified, **kw)¶ Bases:
flatland.schema.base.Element
The base implementation of simple values such as a string or number.
Scalar subclasses are responsible for translating the most common data types in and out of Python-native form: strings, numbers, dates, times, Boolean values, etc. Any data which can be represented by a single
(name, value)
pair is a likely Scalar.Scalar subclasses have two responsibilities: provide a method to adapt a value to native Python form, and provide a method to serialize the native form to a string.
This class is abstract.
-
set
(obj)¶ Process obj and assign the native and text values.
Returns: True if adaptation of obj was successful. Attempts to adapt the given object and assigns this element’s
value
andu
attributes in tandem.If adaptation succeeds,
.value
will contain theadapted
native Python value and.u
will contain a textserialized
version of it. A native value ofNone
will be represented asu''
in.u
.If adaptation fails,
.value
will beNone
and.u
will containstr(obj)
(or unicode), oru''
for none.
-
adapt
(obj)¶ Given any object obj, try to coerce it into native format.
Returns: the native format or raises AdaptationError on failure. This abstract method is called by
set()
.
-
serialize
(obj)¶ Given any object obj, coerce it into a text representation.
Returns: Must return a Unicode text object, always. No special effort is made to coerce values not of native or a compatible type.
This semi-abstract method is called by
set()
. The base implementation returnsstr(obj)
(or unicode).
-
set_default
()¶ set() the element to the schema default.
-
-
class
Number
(value=Unspecified, **kw)¶ Bases:
flatland.schema.scalars.Scalar
Base for numeric fields.
Subclasses provide
type_
andformat
attributes foradapt()
andserialize()
.-
type_
= None¶ The Python type for values, such as
int
orfloat
.
-
signed
= True¶ If true, allow negative numbers. Default
True
.
-
format
= u'%s'¶ The
text
serialization format.
-
adapt
(value)¶ Generic numeric coercion.
Returns: an instance of type_
orNone
Attempt to convert value using the class’s
type_
callable.
-
serialize
(value)¶ Generic numeric serialization.
Returns: Unicode text formatted with format
or thestr()
(or unicode) of value if value is not oftype_
Converts value to a string using Python’s string formatting function and the
format
as the template. The value is provided to the format as a single, positional format argument.
-
-
class
Temporal
(value=Unspecified, **kw)¶ Bases:
flatland.schema.scalars.Scalar
Base for datetime-based date and time fields.
-
type_
¶ Abstract. The native type for element values, will be called with positional arguments per
used
below.
-
regex
¶ Abstract. A regular expression to parse datetime values from a string. Must supply named groupings.
-
used
¶ Abstract. A sequence of regex match group names. These matches will be converted to ints and supplied to the
type_
constructor in the order specified.
-
format
¶ Abstract. A Python string format for serializing the native value. The format will be supplied a dict containing all attributes of the native type.
-
adapt
(value)¶ Coerces value to a native type.
If value is an instance of
type_
, returns it unchanged. If a string, attempts to parse it and construct atype
as described in the attribute documentation.
-
serialize
(value)¶ Serializes value to string.
If value is an instance of
type
, formats it as described in the attribute documentation. Otherwise returnsstr(value)
(or unicode).
-
-
class
Container
(value=Unspecified, **kw)¶ Bases:
flatland.schema.base.Element
Holds other schema items.
Base class for elements that can contain other elements, such as
List
andDict
.Parameters: - descent_validators – optional, a sequence of validators that will be run before contained elements are validated.
- validators – optional, a sequence of validators that will be run after contained elements are validated.
- **kw – other arguments common to
Element
.
-
descent_validators
= ()¶ Todo
doc descent_validators
-
descent_validated_by
(*validators)¶ Return a class with descent validators set to *validators.
Parameters: *validators – one or more validator functions, replacing any descent validators present on the class. Returns: a new class
-
including_descent_validators
(*validators, **kw)¶ Return a class with additional descent *validators.
Parameters: - *validators – one or more validator functions
- position – defaults to -1. By default, additional validators are placed after existing descent validators. Use 0 for before, or any other list index to splice in validators at that point.
Returns: a new class
-
class
Sequence
(value=Unspecified, **kw)¶ Bases:
flatland.schema.containers.Container
,list
Abstract base of sequence-like Containers.
Instances of
Sequence
hold other elements and operate like Python lists. Each sequence member will be an instance ofmember_schema
.Python list methods and operators may be passed instances of
member_schema
or plain Python values. Using plain values is a shorthand for creating anmember_schema
instance andset()ting
it with the value:>>> from flatland import Array, Integer >>> Numbers = Array.of(Integer) >>> ones = Numbers() >>> ones.append(1) >>> ones [<Integer None; value=1>] >>> another_one = Integer() >>> another_one.set(1) True >>> ones.append(another_one) >>> ones [<Integer None; value=1>, <Integer None; value=1>]
-
prune_empty
= True¶ If true, skip missing index numbers in
set_flat()
. Default True.See `Sequences`_ for more information.
-
of
(*schema)¶ Declare the class to hold a sequence of *schema.
Params *schema: one or more Element
classesReturns: 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 anonymousDict
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)]) >>> point = el[0] >>> point['x'] <Integer u'x'; value=1> >>> point['y'] <Integer u'y'; value=2>
-
set
(iterable)¶ Assign the native and Unicode value.
Attempts to adapt the given iterable and assigns this element’s
value
andu
attributes in tandem. Returns True if the adaptation was successful. SeeElement.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_default
()¶ set() the element to the schema default.
-
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.
-
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.
-
index
(value)¶ 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.
-
count
(value)¶ 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.
-
-
class
Mapping
(value=Unspecified, **kw)¶ Bases:
flatland.schema.containers.Container
,dict
Base of mapping-like Containers.
-
field_schema
= ()¶ Todo
doc field_schema
-
may_contain
(key)¶ Return True if the element schema allows a field named key.
-
clear
() → None. Remove all items from D.¶
-
popitem
() → (k, v), remove and return some (key, value) pair as a¶ 2-tuple; but raise KeyError if D is empty.
-
pop
(k[, d]) → v, remove specified key and return the corresponding value.¶ If key is not found, d is returned if given, otherwise KeyError is raised
-
update
(*dictish, **kwargs)¶ Update with keys from dict-like *dictish and **kwargs
-
setdefault
(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶
-
get
(k[, d]) → D[k] if k in D, else d. d defaults to None.¶
-
set
(value)¶ Todo
doc set()
-
set_default
()¶ set() the element to the schema default.
-
u
¶ A string repr of the element.
-
value
¶ The element as a regular Python dictionary.
-
is_empty
¶ Mappings are never empty.
-
-
class
Compound
(value=Unspecified, **kw)¶ Bases:
flatland.schema.containers.Mapping
,flatland.schema.scalars.Scalar
A mapping container that acts like a scalar value.
Compound fields are dictionary-like fields that can assemble a
u
andvalue
from their children, and can decompose a structured value passed to aset()
into values for its children.A simple example is a logical calendar date field composed of 3 separate Integer component fields, year, month and day. The Compound can wrap the 3 parts up into a single logical field that handles
datetime.date
values. Set adate
on the logical field and its component fields will be set with year, month and day; alter the int value of the year component field and the logical field updates thedate
to match.Compound
is an abstract class. Subclasses must implementcompose()
andexplode()
.Composites run validation after their children.
-
compose
()¶ Return a text, native tuple built from children’s state.
Returns: a 2-tuple of text representation, native value. These correspond to the serialize_element()
andadapt_element()
methods ofScalar
objects.For example, a compound date field may return a ‘-‘ delimited string of year, month and day digits and a
datetime.date
.
-
explode
(value)¶ Given a compound value, assign values to children.
Parameters: value – a value to be adapted and exploded For example, a compound date field may read attributes from a
datetime.date
value andset()
them on child fields.The decision to perform type checking on value is completely up to you and you may find you want different rules for different compound types.
-
serialize
(value)¶ Not implemented for Compound types.
-
set
(value)¶ Todo
doc set()
-
is_empty
¶ True if all subfields are empty.
-