diff --git a/docs/basics.rst b/docs/basics.rst index 053de47..46f4973 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -19,11 +19,11 @@ serialization might look something like this: :linenos: { - 'name':'keith', - 'age':'20', - 'friends':[('1', 'jim'),('2', 'bob'), ('3', 'joe'), ('4', 'fred')], - 'phones':[{'location':'home', 'number':'555-1212'}, - {'location':'work', 'number':'555-8989'},], + 'name': 'keith', + 'age': '20', + 'friends': [('1', 'jim'), ('2', 'bob'), ('3', 'joe'), ('4', 'fred')], + 'phones': [{'location': 'home', 'number': '555-1212'}, + {'location': 'work', 'number': '555-8989'}], } Let's further imagine you'd like to make sure, on demand, that a @@ -43,12 +43,12 @@ different types. class Friend(colander.TupleSchema): rank = colander.SchemaNode(colander.Int(), - validator=colander.Range(0, 9999)) + validator=colander.Range(0, 9999)) name = colander.SchemaNode(colander.String()) class Phone(colander.MappingSchema): location = colander.SchemaNode(colander.String(), - validator=colander.OneOf(['home', 'work'])) + validator=colander.OneOf(['home', 'work'])) number = colander.SchemaNode(colander.String()) class Friends(colander.SequenceSchema): @@ -60,7 +60,7 @@ different types. class Person(colander.MappingSchema): name = colander.SchemaNode(colander.String()) age = colander.SchemaNode(colander.Int(), - validator=colander.Range(0, 200)) + validator=colander.Range(0, 200)) friends = Friends() phones = Phones() @@ -411,15 +411,15 @@ Deserializing A Valid Serialization .. code-block:: python :linenos: - cstruct = { - 'name':'keith', - 'age':'20', - 'friends':[('1', 'jim'),('2', 'bob'), ('3', 'joe'), ('4', 'fred')], - 'phones':[{'location':'home', 'number':'555-1212'}, - {'location':'work', 'number':'555-8989'},], - } - schema = Person() - deserialized = schema.deserialize(cstruct) + cstruct = { + 'name': 'keith', + 'age': '20', + 'friends': [('1', 'jim'), ('2', 'bob'), ('3', 'joe'), ('4', 'fred')], + 'phones': [{'location': 'home', 'number': '555-1212'}, + {'location': 'work', 'number': '555-8989'}], + } + schema = Person() + deserialized = schema.deserialize(cstruct) When ``schema.deserialize(cstruct)`` is called, because all the data in the schema is valid, and the structure represented by ``cstruct`` @@ -428,13 +428,13 @@ conforms to the schema, ``deserialized`` will be the following: .. code-block:: python :linenos: - { - 'name':'keith', - 'age':20, - 'friends':[(1, 'jim'),(2, 'bob'), (3, 'joe'), (4, 'fred')], - 'phones':[{'location':'home', 'number':'555-1212'}, - {'location':'work', 'number':'555-8989'},], - } + { + 'name': 'keith', + 'age': 20, + 'friends': [(1, 'jim'), (2, 'bob'), (3, 'joe'), (4, 'fred')], + 'phones': [{'location': 'home', 'number': '555-1212'}, + {'location': 'work', 'number': '555-8989'}], + } Note that all the friend rankings have been converted to integers, likewise for the age. @@ -452,17 +452,17 @@ validation error? .. code-block:: python :linenos: - import colander + import colander - cstruct = { - 'name':'keith', - 'age':'-1', - 'friends':[('1', 'jim'),('t', 'bob'), ('3', 'joe'), ('4', 'fred')], - 'phones':[{'location':'bar', 'number':'555-1212'}, - {'location':'work', 'number':'555-8989'},], - } - schema = Person() - schema.deserialize(cstruct) + cstruct = { + 'name': 'keith', + 'age': '-1', + 'friends': [('1', 'jim'), ('t', 'bob'), ('3', 'joe'), ('4', 'fred')], + 'phones': [{'location': 'bar', 'number': '555-1212'}, + {'location': 'work', 'number': '555-8989'}], + } + schema = Person() + schema.deserialize(cstruct) The ``deserialize`` method will raise an exception, and the ``except`` clause above will be invoked, causing an error message to be printed. @@ -471,9 +471,9 @@ It will print something like: .. code-block:: python :linenos: - Invalid: {'age':'-1 is less than minimum value 0', - 'friends.1.0':'"t" is not a number', - 'phones.0.location:'"bar" is not one of "home", "work"'} + Invalid: {'age': '-1 is less than minimum value 0', + 'friends.1.0': '"t" is not a number', + 'phones.0.location': '"bar" is not one of "home", "work"'} The above error is telling us that: @@ -491,30 +491,30 @@ dictionary: .. code-block:: python :linenos: - import colander + import colander - cstruct = { - 'name':'keith', - 'age':'-1', - 'friends':[('1', 'jim'),('t', 'bob'), ('3', 'joe'), ('4', 'fred')], - 'phones':[{'location':'bar', 'number':'555-1212'}, - {'location':'work', 'number':'555-8989'},], - } - schema = Person() - try: - schema.deserialize(cstruct) - except colander.Invalid, e: - errors = e.asdict() - print errors + cstruct = { + 'name': 'keith', + 'age': '-1', + 'friends': [('1', 'jim'), ('t', 'bob'), ('3', 'joe'), ('4', 'fred')], + 'phones': [{'location': 'bar', 'number': '555-1212'}, + {'location': 'work', 'number': '555-8989'}], + } + schema = Person() + try: + schema.deserialize(cstruct) + except colander.Invalid, e: + errors = e.asdict() + print errors This will print something like: .. code-block:: python :linenos: - {'age':'-1 is less than minimum value 0', - 'friends.1.0':'"t" is not a number', - 'phones.0.location:'"bar" is not one of "home", "work"'} + {'age': '-1 is less than minimum value 0', + 'friends.1.0': '"t" is not a number', + 'phones.0.location': '"bar" is not one of "home", "work"'} :exc:`colander.Invalid` Exceptions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -654,12 +654,12 @@ We can serialize a matching data structure: .. code-block:: python :linenos: - appstruct = {'age':20, 'name':'Bob'} + appstruct = {'age': 20, 'name': 'Bob'} schema = Person() serialized = schema.serialize(appstruct) -The value for ``serialized`` above will be ``{'age':'20', -'name':'Bob'}``. Note that the ``age`` integer has become a string. +The value for ``serialized`` above will be ``{'age': '20', +'name': 'Bob'}``. Note that the ``age`` integer has become a string. Serialization and deserialization are not completely symmetric, however. Although schema-driven data conversion happens during @@ -678,12 +678,12 @@ using the ``serialize`` method of the schema: .. code-block:: python :linenos: - appstruct = {'age':20} + appstruct = {'age': 20} schema = Person() serialized = schema.serialize(appstruct) -The value for ``serialized`` above will be ``{'age':'20', -'name':colander.null}``. Note the ``age`` integer has become a +The value for ``serialized`` above will be ``{'age': '20', +'name': colander.null}``. Note the ``age`` integer has become a string, and the missing ``name`` attribute has been replaced with :attr:`colander.null`. Above, even though we did not include the ``name`` attribute in the appstruct we fed to ``serialize``, an error @@ -985,12 +985,12 @@ schema configuration. Here's our previous declarative schema: class Friend(colander.TupleSchema): rank = colander.SchemaNode(colander.Int(), - validator=colander.Range(0, 9999)) + validator=colander.Range(0, 9999)) name = colander.SchemaNode(colander.String()) class Phone(colander.MappingSchema): location = colander.SchemaNode(colander.String(), - validator=colander.OneOf(['home', 'work'])) + validator=colander.OneOf(['home', 'work'])) number = colander.SchemaNode(colander.String()) class Friends(colander.SequenceSchema): @@ -1002,7 +1002,7 @@ schema configuration. Here's our previous declarative schema: class Person(colander.MappingSchema): name = colander.SchemaNode(colander.String()) age = colander.SchemaNode(colander.Int(), - validator=colander.Range(0, 200)) + validator=colander.Range(0, 200)) friends = Friends() phones = Phones() @@ -1015,7 +1015,7 @@ We can imperatively construct a completely equivalent schema like so: friend = colander.SchemaNode(colander.Tuple()) friend.add(colander.SchemaNode(colander.Int(), - validator=colander.Range(0, 9999), + validator=colander.Range(0, 9999), name='rank')) friend.add(colander.SchemaNode(colander.String(), name='name')) @@ -1030,7 +1030,7 @@ We can imperatively construct a completely equivalent schema like so: schema = colander.SchemaNode(colander.Mapping()) schema.add(colander.SchemaNode(colander.String(), name='name')) schema.add(colander.SchemaNode(colander.Int(), name='age', - validator=colander.Range(0, 200))) + validator=colander.Range(0, 200))) schema.add(colander.SequenceSchema(friend, name='friends')) schema.add(colander.SequenceSchema(phone, name='phones')) @@ -1048,14 +1048,14 @@ a schema created declaratively: .. code-block:: python :linenos: - data = { - 'name':'keith', - 'age':'20', - 'friends':[('1', 'jim'),('2', 'bob'), ('3', 'joe'), ('4', 'fred')], - 'phones':[{'location':'home', 'number':'555-1212'}, - {'location':'work', 'number':'555-8989'},], - } - deserialized = schema.deserialize(data) + data = { + 'name': 'keith', + 'age': '20', + 'friends': [('1', 'jim'), ('2', 'bob'), ('3', 'joe'), ('4', 'fred')], + 'phones': [{'location': 'home', 'number': '555-1212'}, + {'location': 'work', 'number': '555-8989'}], + } + deserialized = schema.deserialize(data) Gotchas ------- @@ -1102,4 +1102,3 @@ module scope before mutating any of its subnodes: :meth:`colander.SchemaNode.clone` clones all the nodes in the schema, so you can work with a "deep copy" of the schema without disturbing the "template" schema nodes defined at a higher scope. -