deb-python-colander/docs/manipulation.rst

Manipulating Data Structures

Colander schemas have some utility functions which can be used to manipulate an appstruct or a cstruct. Nested data structures can be flattened into a single dictionary or a single flattened dictionary can be used to produce a nested data structure. Values of particular nodes can also be set or retrieved based on a flattened path spec.

Flattening a Data Structure

colander.SchemaNode.flatten can be used to convert a datastructure with nested dictionaries and/or lists into a single flattened dictionary where each key in the dictionary is a dotted name path to the node in the nested structure.

Consider the following schema:

import colander

class Friend(colander.TupleSchema):
    rank = colander.SchemaNode(colander.Int(),
                               validator=colander.Range(0, 9999))
    name = colander.SchemaNode(colander.String())

class Phone(colander.MappingSchema):
    location = colander.SchemaNode(colander.String(),
                                  validator=colander.OneOf(['home', 'work']))
    number = colander.SchemaNode(colander.String())

class Friends(colander.SequenceSchema):
    friend = Friend()

class Phones(colander.SequenceSchema):
    phone = Phone()

class Person(colander.MappingSchema):
    name = colander.SchemaNode(colander.String())
    age = colander.SchemaNode(colander.Int(),
                             validator=colander.Range(0, 200))
    friends = Friends()
    phones = Phones()

Consider also a particular serialization of data using that schema:

appstruct = {
'name':'keith',
'age':20,
'friends':[(1, 'jim'),(2, 'bob'), (3, 'joe'), (4, 'fred')],
'phones':[{'location':'home', 'number':'555-1212'},
          {'location':'work', 'number':'555-8989'},],
}

This data can be flattened:

schema = Person()
fstruct = schema.flatten(appstruct)

The resulting flattened structure would look like this:

{
'name': 'keith',
'age': 20,
'friends.0.rank': 1,
'friends.0.name': 'jim',
'friends.1.rank': 2,
'friends.1.name': 'bob',
'friends.2.rank': 3,
'friends.2.name': 'joe',
'friends.3.rank': 4,
'friends.3.name': 'fred',
'phones.0.location': 'home',
'phones.0.number': '555-1212',
'phones.1.location': 'work',
'phones.1.number': '555-8989',
}

The process can be reversed using colandar.SchemaNode.unflatten:

appstruct = schema.unflatten(fstruct)

Either an appstruct or a cstruct can be flattened or unflattened in this way.

Accessing and Mutating Nodes in a Data Structure

colander.SchemaNode.get_value and colander.SchemaNode.set_value can be used to access and mutate nodes in an appstruct or cstruct. Using the example from above:

# How much do I like Joe?
rank = schema.get_value(appstruct, 'friends.2.rank')

# Joe bought me beer. Let's promote Joe.
schema.set_value(appstruct, 'friends.2.rank', rank + 5000)