Strings, Numbers and Booleans

Simple Fields

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 Unicode string.

This class is abstract.

set(value)

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.

adapt(value)

Given any value, try to coerce it into native format.

Returns:the native format or raises AdaptationError on failure.

This abstract method is called by set().

serialize(value)

Given any value, coerce it into a Unicode representation.

Returns:Must return a Unicode 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 returns unicode(value).

set_default()

set() the element to the schema default.

validate_element(state, descending)

Validates on the first, downward pass.

See FieldSchema.validate_element().

Strings

class String(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Scalar

A regular old Unicode string.

strip = True

If true, strip leading and trailing whitespace during conversion.

adapt(value)

Return a Unicode representation.

Returns:a unicode value or None

If strip is true, leading and trailing whitespace will be removed.

serialize(value)

Return a Unicode representation.

Returns:a unicode value or u'' if value is None

If strip is true, leading and trailing whitespace will be removed.

is_empty

True if the String is missing or has no value.

Numbers

class Number(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Scalar

Base for numeric fields.

Subclasses provide type_ and format attributes for adapt() and serialize().

type_ = None

The Python type for values, such as int or float.

signed = True

If true, allow negative numbers. Default True.

format = u'%s'

The unicode serialization format.

adapt(value)

Generic numeric coercion.

Returns:an instance of type_ or None

Attempt to convert value using the class’s type_ callable.

serialize(value)

Generic numeric serialization.

Returns:a unicode string formatted with format or the unicode() of value if value is not of type_

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 Integer(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Number

Element type for Python’s int.

type_

int

alias of int

format = u'%i'

u'%i'

class Long(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Number

Element type for Python’s long.

type_

long

alias of long

format = u'%i'

u'%i'

class Float(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Number

Element type for Python’s float.

type_

float

alias of float

format = u'%f'

u'%f'

class Decimal(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Number

Element type for Python’s Decimal.

type_

decimal.Decimal

alias of Decimal

format = u'%f'

u'%f'

Booleans

class Boolean(value=Unspecified, **kw)

Bases: flatland.schema.scalars.Scalar

Element type for Python’s bool.

true = u'1'

The unicode serialization for True: u'1'.

true_synonyms = (u'on', u'true', u'True', u'1')

A sequence of acceptable string equivalents for True.

Defaults to (u'on', u'true', u'True', u'1')

false = u''

The unicode serialization for False: u''.

false_synonyms = (u'off', u'false', u'False', u'0', u'')

A sequence of acceptable string equivalents for False.

Defaults to (u'off', u'false', u'False', u'0', u'')

adapt(value)

Coerce value to bool.

Returns:a bool or None

If value is a string, returns True if the value is in true_synonyms, False if in false_synonyms and None otherwise.

For non-string values, equivalent to bool(value).

serialize(value)

Convert bool(value) to a canonical string representation.

Returns:either self.true or self.false.