Dicts — flatland 0.8.1 documentation

# Dicts

Todo

intro

## `set()` Policy

Todo

strict, duck, etc.

## Validation

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.

## `Dict`

class `Dict`(value=Unspecified, **kw)

  Bases: `flatland.schema.containers.Mapping`, `dict`

  A mapping Container with named members.

  `policy` = 'subset'

    Deprecated. One of ‘strict’, ‘subset’ or ‘duck’. Default ‘subset’.

    Operates as `SetWithAllFields` and `SetWithKnownFields`, except raises an exception immediately upon `set()`.

    To migrate to the new validators, set `policy` to `None` to disable the policy behavior.

  `of`(*fields)

    Todo

    doc of()

  classmethod `from_object`(obj, include=None, omit=None, rename=None, **kw)

    Return an element initialized with an object’s attributes.

    Parameters: | obj – any object include – optional, an iterable of attribute names to pull from obj, if present on the object. Only these attributes will be included. omit – optional, an iterable of attribute names to ignore on obj. All other attributes matching a named field on the mapping will be included. rename – optional, a mapping of attribute-to-field name transformations. Attributes specified in the mapping will be included regardless of include or omit. **kw – keyword arguments will be passed to the element’s constructor.

    include and omit are mutually exclusive.

    This is a convenience constructor for `set_by_object()`:

        element = cls(**kw)
        element.set_by_object(obj, include, omit, rename)

  `set`(value, policy=None)

    Todo

    doc set()

  `set_by_object`(obj, include=None, omit=None, rename=None)

    Set fields with an object’s attributes.

    Parameters: | obj – any object include – optional, an iterable of attribute names to pull from obj, if present on the object. Only these attributes will be included. omit – optional, an iterable of attribute names to ignore on obj. All other attributes matching a named field on the mapping will be included. rename – optional, a mapping of attribute-to-field name transformations. Attributes specified in the mapping will be included regardless of include or omit.

    include and omit are mutually exclusive.

    Sets fields on self, using as many attributes as possible from obj. Object attributes that do not correspond to field names are ignored.

    Mapping instances have two corresponding methods useful for round-tripping values in and out of your domain objects.

    `update_object()` performs the inverse of `set_object()`, and `slice()` is useful for constructing new objects.

        >>> user = User('biff', 'secret')
        >>> form = UserForm()
        >>> form.set_by_object(user)
        >>> form['login'].value
        u'biff'
        >>> form['password'] = u'new-password'
        >>> form.update_object(user, omit=['verify_password'])
        >>> user.password
        u'new-password'
        >>> user_keywords = form.slice(omit=['verify_password'], key=str)
        >>> sorted(user_keywords.keys())
        ['login', 'password']
        >>> new_user = User(**user_keywords)

  `update_object`(obj, include=None, omit=None, rename=None, key=<function identifier_transform>)

    Update an object’s attributes using the element’s values.

    Produces a `slice()` using include, omit, rename and key, and sets the selected attributes on obj using `setattr`.

    Returns: | nothing. obj is modified directly.

  `slice`(include=None, omit=None, rename=None, key=None)

    Return a `dict` containing a subset of the element’s values.

## `SparseDict`

class `SparseDict`(value=Unspecified, **kw)

  Bases: `flatland.schema.containers.Dict`

  A Mapping which may contain a subset of the schema’s allowed keys.

  This differs from `Dict` in that new instances are not created with empty values for all possible keys. In addition, mutating operations are allowed so long as the operations operate within the schema. For example, you may `pop()` and `del` members of the mapping.

  `minimum_fields` = None

    The subset of fields to autovivify on instantiation.

    May be `None` or `'required'`. If `None`, mappings will be created empty and mutation operations are unrestricted within the bounds of the `field_schema`. If `required`, fields with `optional` of `False` will always be present after instantiation, and attempts to remove them from the mapping with `del` and friends will raise `TypeError`.

  `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

  `setdefault`(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  `set_default`()

    set() the element to the schema default.