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.
