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