openstack/deb-python-colander
Code Issues Proposed changes

Merge pull request #248 from lmctv/document_drop_behavior

Browse Source 
First attempt at documenting colander.drop
This commit is contained in:
Michael Merickel
2016-01-17 17:35:01 -06:00
parent 36369e51ea c9d8f7a64d
commit 5d017c58ef
3 changed files with 19 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
colander/__init__.py
View File

@@ -48,8 +48,9 @@ null = _null()
class _drop(object): class _drop(object):
""" Represents a value that will be dropped from the schema if it """ Represents a value that will be dropped from the schema if it
is missing during *deserialization*. Passed as a value to the is missing during *serialization* or *deserialization*. Passed as
`missing` keyword argument of :class:`SchemaNode`. a value to the `missing` or `default` keyword argument
of :class:`SchemaNode`.
""" """
def __repr__(self): def __repr__(self):
return '<colander.drop>' return '<colander.drop>'
@@ -1851,8 +1852,10 @@ class _SchemaNode(object):
- ``typ``: The 'type' for this node can optionally be passed in as a - ``typ``: The 'type' for this node can optionally be passed in as a
keyword argument. See the documentation for the positional arg above. keyword argument. See the documentation for the positional arg above.
- ``default``: The default serialization value for this node. - ``default``: The default serialization value for this node when
Default: :attr:`colander.null`. not set. If ``default`` is :attr:`colander.drop`, the node
will be dropped from schema serialization. If not provided,
the node will be serialized to :attr:`colander.null`.
- ``missing``: The default deserialization value for this node. If it is - ``missing``: The default deserialization value for this node. If it is
not provided, the missing value of this node will be the special marker not provided, the missing value of this node will be the special marker
@@ -1860,7 +1863,7 @@ class _SchemaNode(object):
'required'. When ``missing`` is :attr:`colander.required`, the 'required'. When ``missing`` is :attr:`colander.required`, the
``required`` computed attribute will be ``True``. When ``missing`` is ``required`` computed attribute will be ``True``. When ``missing`` is
:attr:`colander.drop`, the node is dropped from the schema if it isn't :attr:`colander.drop`, the node is dropped from the schema if it isn't
set during serialization/deserialization. set during deserialization.
- ``missing_msg``: Optional error message to be used if the value is - ``missing_msg``: Optional error message to be used if the value is
required and missing. required and missing.

2
docs/index.rst
View File

@@ -58,7 +58,7 @@ internationalizable.
:maxdepth: 2 :maxdepth: 2
basics.rst basics.rst
null.rst null_and_drop.rst
extending.rst extending.rst
binding.rst binding.rst
manipulation.rst manipulation.rst

15
docs/null.rst → docs/null_and_drop.rst
View File

@@ -1,21 +1,26 @@
.. _null: .. _null_and_drop:
The Null Value The Null and Drop Values
============== ========================
:attr:`colander.null` is a sentinel value which may be passed to :attr:`colander.null` is a sentinel value which may be passed to
:meth:`colander.SchemaNode.serialize` during serialization or to :meth:`colander.SchemaNode.serialize` during serialization or to
:meth:`colander.SchemaNode.deserialize` during deserialization. :meth:`colander.SchemaNode.deserialize` during deserialization.
:attr:`colander.drop` is a sentinel value which controls the
behavior of collection-like :class:`colander.SchemaNode` subclasses.
During serialization, the use of :attr:`colander.null` indicates that During serialization, the use of :attr:`colander.null` indicates that
the :term:`appstruct` value corresponding to the node it's passed to the :term:`appstruct` value corresponding to the node it's passed to
is missing and the value of the ``default`` attribute of the is missing and the value of the ``default`` attribute of the
corresponding node should be used instead. corresponding node should be used instead. If the node's ``default``
attribute is :attr:`colander.drop`, the serializer will skip the node.
During deserialization, the use of :attr:`colander.null` indicates During deserialization, the use of :attr:`colander.null` indicates
that the :term:`cstruct` value corresponding to the node it's passed that the :term:`cstruct` value corresponding to the node it's passed
to is missing, and if possible, the value of the ``missing`` attribute to is missing, and if possible, the value of the ``missing`` attribute
of the corresponding node should be used instead. of the corresponding node should be used instead. If the node's ``missing``
attribute is :attr:`colander.drop`, the deserializer will skip the node.
Note that :attr:`colander.null` has no relationship to the built-in Python Note that :attr:`colander.null` has no relationship to the built-in Python
``None`` value. ``colander.null`` is used instead of ``None`` because ``None`` value. ``colander.null`` is used instead of ``None`` because