Enumerations — flatland 0.8.1 documentation

# Enumerations

## 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')
      True
      >>> element.value
      2
      >>> element.set(u'5')
      False
      >>> element.value is None
      True

  `Enum` is a subclass which provides a convenient enumerated wrapper.

  `child_type`

    The type of constrained value, defaulting to String.

    alias of `String`

  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.

  `adapt`(value)

    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`(value)

    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 returns `str(obj)` (or unicode).

## `Enum`

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`.

  `valued`(*enum_values)

    Return a class with `valid_values` = enum_values

    Parameters: | *enum_values – zero or more values for `valid_values`.
    Returns: | a new class

  `valid_values` = ()

    Valid element values.

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

  `valid_value`(element, value)

    True if value is within `valid_values`.