Skip to content

Commit

Permalink
Add changelog and docs for propagate_unknown
Browse files Browse the repository at this point in the history
The changelog entry, including credit to prior related work, covers
the closed issues and describes how `propagate_unknown` is expected to
behave.

Inline documentation attempts to strike a balance between clarify and
brevity.

closes marshmallow-code#1428, marshmallow-code#1429, marshmallow-code#1490, marshmallow-code#1575
  • Loading branch information
sirosen committed Jul 17, 2020
1 parent 0dcee07 commit fc6f52a
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 0 deletions.
28 changes: 28 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,34 @@
Changelog
---------

3.8.0 (Unreleased)
******************

Features:

- The behavior of the ``unknown`` option can be further customized with a
second option, ``propagate_unknown``. When set to ``True``, any nested
schemas will receive the same ``unknown`` value as their parent if they did
not set an ``unknown`` value explicitly.
``propagate_unknown`` itself propagates across any number of layers of
nesting and cannot be disabled by a child schema if it enabled in its parent.
(:issue:`1490`, :issue:`1428`)
Thanks :user:`lmignon` and :user:`mahenzon`.

.. note::

In order to retain flexibility, when a schema is being loaded with
``propagate_unknown=True``, you can still set ``unknown`` explicitly on child
schemas. However, be aware that such a value will be propagated to any of its
descendants.

For example, a schema which specifies ``unknown=EXCLUDE`` will set
``EXCLUDE`` in all of its children. If one of the children specifies
``unknown=IGNORE``, then ``IGNORE`` will be passed to the relevant
grandchildren.
Other children of the original schema could specify ``unknown=RAISE``, and
this would apply to them equally well.

3.7.0 (2020-07-08)
******************

Expand Down
4 changes: 4 additions & 0 deletions src/marshmallow/fields.py
Original file line number Diff line number Diff line change
Expand Up @@ -459,6 +459,10 @@ class ParentSchema(Schema):
:param many: Whether the field is a collection of objects.
:param unknown: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
:param propagate_unknown: If ``True``, the value for ``unknown`` will be
applied to any ``Nested`` fields within the nested schema. Propagates down and allows
``Nested`` fields to apply their own ``unknown`` value. Note that this
only has an effect when there are multiple layers of nesting
:param kwargs: The same keyword arguments that :class:`Field` receives.
"""

Expand Down
19 changes: 19 additions & 0 deletions src/marshmallow/schema.py
Original file line number Diff line number Diff line change
Expand Up @@ -287,6 +287,9 @@ class AlbumSchema(Schema):
will be ignored. Use dot delimiters to specify nested fields.
:param unknown: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
:param propagate_unknown: If ``True``, the value for ``unknown`` will be
applied to all ``Nested`` fields. Propagates down and allows
``Nested`` fields to apply their own ``unknown`` value
.. versionchanged:: 3.0.0
`prefix` parameter removed.
Expand Down Expand Up @@ -364,6 +367,10 @@ class Meta:
- ``dump_only``: Tuple or list of fields to exclude from deserialization
- ``unknown``: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
- ``propagate_unknown`` If ``True``, the value for ``unknown`` will be
applied to all ``Nested`` fields. Propagates down, but if a ``Nested``
field sets ``unknown``, it will begin to propagate that value, not the
where this is set.
- ``register``: Whether to register the `Schema` with marshmallow's internal
class registry. Must be `True` if you intend to refer to this `Schema`
by class name in `Nested` fields. Only set this to `False` when memory
Expand Down Expand Up @@ -619,6 +626,9 @@ def _deserialize(
will be ignored. Use dot delimiters to specify nested fields.
:param unknown: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
:param propagate_unknown: If ``True``, the value for ``unknown`` will be
applied to all ``Nested`` fields. Propagates down and allows
``Nested`` fields to apply their own ``unknown`` value
:param int index: Index of the item being serialized (for storing errors) if
serializing a collection, otherwise `None`.
:return: A dictionary of the deserialized data.
Expand Down Expand Up @@ -733,6 +743,9 @@ def load(
:param unknown: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
If `None`, the value for `self.unknown` is used.
:param propagate_unknown: If ``True``, the value for ``unknown`` will be
applied to all ``Nested`` fields. Propagates down and allows
``Nested`` fields to apply their own ``unknown`` value
:return: Deserialized data
.. versionadded:: 1.0.0
Expand Down Expand Up @@ -772,6 +785,9 @@ def loads(
:param unknown: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
If `None`, the value for `self.unknown` is used.
:param propagate_unknown: If ``True``, the value for ``unknown`` will be
applied to all ``Nested`` fields. Propagates down and allows
``Nested`` fields to apply their own ``unknown`` value
:return: Deserialized data
.. versionadded:: 1.0.0
Expand Down Expand Up @@ -864,6 +880,9 @@ def _do_load(
:param unknown: Whether to exclude, include, or raise an error for unknown
fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
If `None`, the value for `self.unknown` is used.
:param propagate_unknown: If ``True``, the value for ``unknown`` will be
applied to all ``Nested`` fields. Propagates down and allows
``Nested`` fields to apply their own ``unknown`` value
:param postprocess: Whether to run post_load methods..
:return: Deserialized data
"""
Expand Down

0 comments on commit fc6f52a

Please sign in to comment.