From c9d8f7a64d4afdbef8afc62fe74c582dfc309224 Mon Sep 17 00:00:00 2001 From: "Lorenzo M. Catucci" Date: Sun, 17 Jan 2016 13:27:47 +0100 Subject: [PATCH] First attempt at documenting colander.drop --- colander/__init__.py | 13 ++++++++----- docs/index.rst | 2 +- docs/{null.rst => null_and_drop.rst} | 15 ++++++++++----- 3 files changed, 19 insertions(+), 11 deletions(-) rename docs/{null.rst => null_and_drop.rst} (96%) diff --git a/colander/__init__.py b/colander/__init__.py index 37ce5f9..d641df6 100644 --- a/colander/__init__.py +++ b/colander/__init__.py @@ -48,8 +48,9 @@ null = _null() class _drop(object): """ Represents a value that will be dropped from the schema if it - is missing during *deserialization*. Passed as a value to the - `missing` keyword argument of :class:`SchemaNode`. + is missing during *serialization* or *deserialization*. Passed as + a value to the `missing` or `default` keyword argument + of :class:`SchemaNode`. """ def __repr__(self): return '' @@ -1851,8 +1852,10 @@ class _SchemaNode(object): - ``typ``: The 'type' for this node can optionally be passed in as a keyword argument. See the documentation for the positional arg above. - - ``default``: The default serialization value for this node. - Default: :attr:`colander.null`. + - ``default``: The default serialization value for this node when + 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 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`` computed attribute will be ``True``. When ``missing`` is :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 required and missing. diff --git a/docs/index.rst b/docs/index.rst index d899227..ce41c4b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,7 +58,7 @@ internationalizable. :maxdepth: 2 basics.rst - null.rst + null_and_drop.rst extending.rst binding.rst manipulation.rst diff --git a/docs/null.rst b/docs/null_and_drop.rst similarity index 96% rename from docs/null.rst rename to docs/null_and_drop.rst index 2e23d3a..1ed7050 100644 --- a/docs/null.rst +++ b/docs/null_and_drop.rst @@ -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 :meth:`colander.SchemaNode.serialize` during serialization or to :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 the :term:`appstruct` value corresponding to the node it's passed to 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 that the :term:`cstruct` value corresponding to the node it's passed 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 ``None`` value. ``colander.null`` is used instead of ``None`` because