Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 117 lines (86 sloc) 3.454 kB
7dd682d @mcdonc fix title
mcdonc authored
1 .. _manipulating_data_structures:
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
2
3 Manipulating Data Structures
4 ============================
5
6 Colander schemas have some utility functions which can be used to manipulate
bf47752 @jayd3e Removed all stray whitespace.
jayd3e authored
7 an :term:`appstruct` or a :term:`cstruct`. Nested data structures can be
8 flattened into a single dictionary or a single flattened dictionary can be used
9 to produce a nested data structure. Values of particular nodes can also be set
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
10 or retrieved based on a flattened path spec.
11
12 Flattening a Data Structure
13 ---------------------------
14
15 :meth:`colander.SchemaNode.flatten` can be used to convert a datastructure with
16 nested dictionaries and/or lists into a single flattened dictionary where each
17 key in the dictionary is a dotted name path to the node in the nested structure.
18
19 Consider the following schema:
20
21 .. code-block:: python
22 :linenos:
23
24 import colander
25
26 class Friend(colander.TupleSchema):
bf47752 @jayd3e Removed all stray whitespace.
jayd3e authored
27 rank = colander.SchemaNode(colander.Int(),
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
28 validator=colander.Range(0, 9999))
29 name = colander.SchemaNode(colander.String())
30
31 class Phone(colander.MappingSchema):
bf47752 @jayd3e Removed all stray whitespace.
jayd3e authored
32 location = colander.SchemaNode(colander.String(),
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
33 validator=colander.OneOf(['home', 'work']))
34 number = colander.SchemaNode(colander.String())
35
36 class Friends(colander.SequenceSchema):
37 friend = Friend()
38
39 class Phones(colander.SequenceSchema):
40 phone = Phone()
41
42 class Person(colander.MappingSchema):
43 name = colander.SchemaNode(colander.String())
44 age = colander.SchemaNode(colander.Int(),
45 validator=colander.Range(0, 200))
46 friends = Friends()
47 phones = Phones()
48
49 Consider also a particular serialization of data using that schema:
50
51 .. code-block:: python
52 :linenos:
53
54 appstruct = {
55 'name':'keith',
56 'age':20,
57 'friends':[(1, 'jim'),(2, 'bob'), (3, 'joe'), (4, 'fred')],
58 'phones':[{'location':'home', 'number':'555-1212'},
59 {'location':'work', 'number':'555-8989'},],
60 }
61
62 This data can be flattened:
63
64 .. code-block:: python
65 :linenos:
bf47752 @jayd3e Removed all stray whitespace.
jayd3e authored
66
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
67 schema = Person()
68 fstruct = schema.flatten(appstruct)
69
70 The resulting flattened structure would look like this:
71
72 .. code-block:: python
73 :linenos:
74
75 {
76 'name': 'keith',
77 'age': 20,
78 'friends.0.rank': 1,
79 'friends.0.name': 'jim',
80 'friends.1.rank': 2,
5c2d672 @riffm Fixed key names of flattened structure
riffm authored
81 'friends.1.name': 'bob',
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
82 'friends.2.rank': 3,
5c2d672 @riffm Fixed key names of flattened structure
riffm authored
83 'friends.2.name': 'joe',
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
84 'friends.3.rank': 4,
5c2d672 @riffm Fixed key names of flattened structure
riffm authored
85 'friends.3.name': 'fred',
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
86 'phones.0.location': 'home',
87 'phones.0.number': '555-1212',
88 'phones.1.location': 'work',
89 'phones.1.number': '555-8989',
90 }
91
92 The process can be reversed using :meth:`colandar.SchemaNode.unflatten`:
93
94 .. code-block:: python
95 :linenos:
96
97 appstruct = schema.unflatten(fstruct)
98
99 Either an :term:`appstruct` or a :term:`cstruct` can be flattened or unflattened
100 in this way.
101
102 Accessing and Mutating Nodes in a Data Structure
103 ------------------------------------------------
104
105 :attr:`colander.SchemaNode.get_value` and :attr:`colander.SchemaNode.set_value`
bf47752 @jayd3e Removed all stray whitespace.
jayd3e authored
106 can be used to access and mutate nodes in an :term:`appstruct` or
42522a8 @chrisrossi Add section on datastructure manipulation.
chrisrossi authored
107 :term:`cstruct`. Using the example from above:
108
109 .. code-block:: python
110 :linenos:
111
112 # How much do I like Joe?
113 rank = schema.get_value(appstruct, 'friends.2.rank')
114
115 # Joe bought me beer. Let's promote Joe.
116 schema.set_value(appstruct, 'friends.2.rank', rank + 5000)
Something went wrong with that request. Please try again.