Fix missing quotes and make spacing more standard
This commit is contained in:
Éric Araujo
GitHub
parent
263698173f
commit
70c3cd369a
147
docs/basics.rst
147
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue