Replace propagate_unknown with or-able unknown

Rather than having a new parameter which allows `propagate_unknown`
behavior, convert this into an option which can be set on the
``unknown`` parameter itself.

Drawing from other interfaces which present flags as or-able
values (traditionally bitmasks), express the setting of this option as
`x | PROPAGATE` for any supported `x`.

This makes it harder to propagate the value of `propagate` separately
from the rest of the value of `unknown`. For simplicity, change the
behavior here to suit this implementation.

Author: sirosen

CHANGELOG.rst

@@ -6,28 +6,26 @@ Changelog
 
 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.
+- The behavior of the ``unknown`` option can be further customized with a new
+  value, ``PROPAGATE``. If ``unknown=EXCLUDE | PROPAGATE`` is set, then the
+  value of ``unknown=EXCLUDE | PROPAGATE`` will be passed to any nested
+  schemas which do not explicitly set ``unknown`` in ``Nested`` or schema
+  options. This works for ``INCLUDE | PROPAGATE`` and ``RAISE | PROPAGATE`` as
+  well.
   (: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.
+  When a schema is being loaded with ``unknown=... | PROPAGATE``, you can still
+  set ``unknown`` explicitly on child schemas. However, be aware that such a
+  value may turn off propagation at that point in the schema hierarchy.
 
   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.
+  ``EXCLUDE`` for itself. But because the value is ``EXCLUDE`` rather than
+  ``EXCLUDE | PROPAGATE``, that setting will not be propagated to its
+  children, even if there is a parent schema which sets
+  ``unknown=EXCLUDE | PROPAGATE``.
 
 3.7.1 (2020-07-20)
 ******************

src/marshmallow/__init__.py

@@ -9,7 +9,7 @@
     validates,
     validates_schema,
 )
-from marshmallow.utils import EXCLUDE, INCLUDE, RAISE, pprint, missing
+from marshmallow.utils import EXCLUDE, INCLUDE, RAISE, PROPAGATE, pprint, missing
 from marshmallow.exceptions import ValidationError
 from distutils.version import LooseVersion
 
@@ -19,6 +19,7 @@
     "EXCLUDE",
     "INCLUDE",
     "RAISE",
+    "PROPAGATE",
     "Schema",
     "SchemaOpts",
     "fields",

src/marshmallow/base.py

@@ -39,24 +39,11 @@ def dumps(self, obj, *, many: bool = None):
         raise NotImplementedError
 
     def load(
-        self,
-        data,
-        *,
-        many: bool = None,
-        partial=None,
-        unknown=None,
-        propagate_unknown=None
+        self, data, *, many: bool = None, partial=None, unknown=None
     ):
         raise NotImplementedError
 
     def loads(
-        self,
-        json_data,
-        *,
-        many: bool = None,
-        partial=None,
-        unknown=None,
-        propagate_unknown=None,
-        **kwargs
+        self, json_data, *, many: bool = None, partial=None, unknown=None, **kwargs
     ):
         raise NotImplementedError

src/marshmallow/fields.py

@@ -18,6 +18,7 @@
     missing as missing_,
     resolve_field_instance,
     is_aware,
+    UnknownParam,
 )
 from marshmallow.exceptions import (
     ValidationError,
@@ -459,10 +460,6 @@ 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.
     """
 
@@ -477,8 +474,7 @@ def __init__(
         only: types.StrSequenceOrSet = None,
         exclude: types.StrSequenceOrSet = (),
         many: bool = False,
-        unknown: str = None,
-        propagate_unknown: bool = None,
+        unknown: typing.Union[str, UnknownParam] = None,
         **kwargs
     ):
         # Raise error if only or exclude is passed as string, not list of strings
@@ -498,8 +494,7 @@ def __init__(
         self.only = only
         self.exclude = exclude
         self.many = many
-        self.unknown = unknown
-        self.propagate_unknown = propagate_unknown
+        self.unknown = UnknownParam.parse_if_str(unknown) if unknown else None
         self._schema = None  # Cached Schema instance
         super().__init__(default=default, **kwargs)
 
@@ -577,32 +572,18 @@ def _test_collection(self, value):
         if many and not utils.is_collection(value):
             raise self.make_error("type", input=value, type=value.__class__.__name__)
 
-    def _load(self, value, data, partial=None, unknown=None, propagate_unknown=None):
+    def _load(self, value, data, partial=None, unknown=None):
         try:
             valid_data = self.schema.load(
-                value,
-                unknown=unknown or self.unknown,
-                propagate_unknown=propagate_unknown
-                if propagate_unknown is not None
-                else self.propagate_unknown,
-                partial=partial,
+                value, unknown=unknown if unknown else self.unknown, partial=partial,
             )
         except ValidationError as error:
             raise ValidationError(
                 error.messages, valid_data=error.valid_data
             ) from error
         return valid_data
 
-    def _deserialize(
-        self,
-        value,
-        attr,
-        data,
-        partial=None,
-        unknown=None,
-        propagate_unknown=None,
-        **kwargs
-    ):
+    def _deserialize(self, value, attr, data, partial=None, unknown=None, **kwargs):
         """Same as :meth:`Field._deserialize` with additional ``partial`` argument.
 
         :param bool|tuple partial: For nested schemas, the ``partial``
@@ -616,18 +597,14 @@ def _deserialize(
         # however, we should only respect `self.schema.unknown` if
         # `auto_unknown` is False, meaning that it was set explicitly on the
         # schema class or instance
-        explicit_unknown = self.unknown or (
-            self.schema.unknown if not self.schema.auto_unknown else None
+        explicit_unknown = (
+            self.unknown
+            if self.unknown
+            else (self.schema.unknown if not self.schema.auto_unknown else None)
         )
         if explicit_unknown:
             unknown = explicit_unknown
-        return self._load(
-            value,
-            data,
-            partial=partial,
-            unknown=unknown,
-            propagate_unknown=propagate_unknown,
-        )
+        return self._load(value, data, partial=partial, unknown=unknown,)
 
 
 class Pluck(Nested):