Add embed schema parameter and embed_only field option

AUTHORS.rst

@@ -160,3 +160,4 @@ Contributors (chronological)
 - Vladimir Mikhaylov `@vemikhaylov <https://github.com/vemikhaylov>`_
 - Stephen Eaton `@madeinoz67 <https://github.com/madeinoz67>`_
 - Antonio Lassandro `@lassandroan <https://github.com/lassandroan>`_
+- Brady Neumann `@bpneumann <https://github.com/bpneumann>`_

src/marshmallow/fields.py

@@ -103,6 +103,7 @@ class Field(FieldABC):
     :param dump_only: If `True` skip this field during deserialization, otherwise
         its value will be present in the deserialized object. In the context of an
         HTTP API, this effectively marks the field as "read-only".
+    :param embed_only: If `True`, exclude this field from serialization unles explicitly included in the `embed` option of the schema.
     :param dict error_messages: Overrides for `Field.default_error_messages`.
     :param metadata: Extra information to be stored as field metadata.
 
@@ -162,6 +163,7 @@ def __init__(
         allow_none: typing.Optional[bool] = None,
         load_only: bool = False,
         dump_only: bool = False,
+        embed_only: bool = False,
         error_messages: typing.Optional[typing.Dict[str, str]] = None,
         metadata: typing.Optional[typing.Mapping[str, typing.Any]] = None,
         **additional_metadata
@@ -187,6 +189,7 @@ def __init__(
         self.allow_none = missing is None if allow_none is None else allow_none
         self.load_only = load_only
         self.dump_only = dump_only
+        self.embed_only = embed_only
         if required is True and missing is not missing_:
             raise ValueError("'missing' must not be set for required fields.")
         self.required = required
@@ -472,6 +475,7 @@ class ParentSchema(Schema):
     :param exclude: A list or tuple of fields to exclude.
     :param only: A list or tuple of fields to marshal. If `None`, all fields are marshalled.
         This parameter takes precedence over ``exclude``.
+    :param embed: A list of `embed_only` field names to include in the output of the nested serializer.
     :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`.
@@ -488,6 +492,7 @@ def __init__(
         default: typing.Any = missing_,
         only: typing.Optional[types.StrSequenceOrSet] = None,
         exclude: types.StrSequenceOrSet = (),
+        embed: types.StrSequenceOrSet = (),
         many: bool = False,
         unknown: typing.Optional[str] = None,
         **kwargs
@@ -508,6 +513,7 @@ def __init__(
         self.nested = nested
         self.only = only
         self.exclude = exclude
+        self.embed = embed
         self.many = many
         self.unknown = unknown
         self._schema = None  # Cached Schema instance
@@ -542,6 +548,9 @@ def schema(self):
                 if self.exclude:
                     original = self._schema.exclude
                     self._schema.exclude = set_class(self.exclude) | set_class(original)
+                if self.embed:
+                    original = self._schema.embed
+                    self._schema.embed = set_class(self.embed) | set_class(original)
                 self._schema._init_fields()
             else:
                 if isinstance(nested, type) and issubclass(nested, SchemaABC):
@@ -558,6 +567,7 @@ def schema(self):
                 self._schema = schema_class(
                     many=self.many,
                     only=self.only,
+                    embed=self.embed,
                     exclude=self.exclude,
                     context=context,
                     load_only=self._nested_normalized_option("load_only"),

src/marshmallow/schema.py

@@ -230,6 +230,7 @@ def __init__(self, meta, ordered: bool = False):
         self.dump_only = getattr(meta, "dump_only", ())
         self.unknown = getattr(meta, "unknown", RAISE)
         self.register = getattr(meta, "register", True)
+        self.embed_only = getattr(meta, "embed_only", ())
 
 
 class Schema(base.SchemaABC, metaclass=SchemaMeta):
@@ -268,6 +269,8 @@ class AlbumSchema(Schema):
         when instantiating the Schema. If a field appears in both `only` and
         `exclude`, it is not used. Nested fields can be represented with dot
         delimiters.
+    :param embed: List of `embed_only` field names to include in the serialized
+        output. Nested fields can be represented with dot delimiters.
     :param many: Should be set to `True` if ``obj`` is a collection
         so that the object will be serialized to a list.
     :param context: Optional context passed to :class:`fields.Method` and
@@ -356,6 +359,8 @@ class Meta:
             of invalid items in a collection.
         - ``load_only``: Tuple or list of fields to exclude from serialized results.
         - ``dump_only``: Tuple or list of fields to exclude from deserialization
+        - ``embed_only``: Tuple or list of fields to exclude from serialized results
+            unless explicitly included in the `embed` option of the schema.
         - ``unknown``: Whether to exclude, include, or raise an error for unknown
             fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
         - ``register``: Whether to register the `Schema` with marshmallow's internal
@@ -369,6 +374,7 @@ def __init__(
         *,
         only: typing.Optional[types.StrSequenceOrSet] = None,
         exclude: types.StrSequenceOrSet = (),
+        embed: types.StrSequenceOrSet = (),
         many: bool = False,
         context: typing.Optional[typing.Dict] = None,
         load_only: types.StrSequenceOrSet = (),
@@ -381,14 +387,18 @@ def __init__(
             raise StringNotCollectionError('"only" should be a list of strings')
         if not is_collection(exclude):
             raise StringNotCollectionError('"exclude" should be a list of strings')
+        if not is_collection(embed):
+            raise StringNotCollectionError('"embed" should be a list of strings')
         # copy declared fields from metaclass
         self.declared_fields = copy.deepcopy(self._declared_fields)
         self.many = many
         self.only = only
+        self.embed = set(embed)
         self.exclude = set(self.opts.exclude) | set(exclude)
         self.ordered = self.opts.ordered
         self.load_only = set(load_only) or set(self.opts.load_only)
         self.dump_only = set(dump_only) or set(self.opts.dump_only)
+        self.embed_only = set(self.opts.embed_only)
         self.partial = partial
         self.unknown = unknown or self.opts.unknown
         self.context = context or {}
@@ -924,6 +934,13 @@ def _normalize_nested_options(self) -> None:
             self.exclude = self.set_class(
                 [field for field in self.exclude if "." not in field]
             )
+        if self.embed:
+            # Apply the embed option to nested fields.
+            self.__apply_nested_option("embed", self.embed, "union")
+            # Remove the child field names from the embed option.
+            self.embed = self.set_class(
+                self.set_class([field.split(".", 1)[0] for field in self.embed])
+            )
 
     def __apply_nested_option(self, option_name, field_names, set_operation) -> None:
         """Apply nested options to nested fields"""
@@ -965,6 +982,8 @@ def _init_fields(self) -> None:
         else:
             field_names = available_field_names
 
+        invalid_fields |= self.embed_only - available_field_names
+
         # If "exclude" option or param is specified, remove those fields.
         if self.exclude:
             # Note that this isn't available_field_names, since we want to
@@ -989,6 +1008,20 @@ def _init_fields(self) -> None:
             if not field_obj.load_only:
                 dump_fields[field_name] = field_obj
 
+        embed_only_fields = (
+            self.set_class(
+                [
+                    field_name
+                    for field_name, field_obj in dump_fields.items()
+                    if getattr(field_obj, "embed_only", False)
+                ]
+            )
+            | self.embed_only
+        )
+        non_embedded_fields = embed_only_fields - self.embed
+        for f in non_embedded_fields:
+            dump_fields.pop(f)
+
         dump_data_keys = [
             field_obj.data_key if field_obj.data_key is not None else name
             for name, field_obj in dump_fields.items()

tests/test_schema.py

@@ -1592,6 +1592,101 @@ class MySchema(Schema):
         MySchema(**{param: "foo"})
 
 
+def test_embed_only_in_meta_excludes_field():
+    class MySchema(Schema):
+        class Meta:
+            embed_only = ["foo"]
+
+        foo = fields.Field()
+
+    sch = MySchema()
+    assert "foo" not in sch.dump({"foo": "bar"})
+
+
+def test_embed_only_in_meta_includes_field():
+    class MySchema(Schema):
+        class Meta:
+            embed_only = ["foo"]
+
+        foo = fields.Field()
+
+    sch = MySchema(embed=["foo"])
+    assert "foo" in sch.dump({"foo": "bar"})
+
+
+def test_embed_only_on_field_excludes_field():
+    class MySchema(Schema):
+        foo = fields.Field(embed_only=True)
+
+    sch = MySchema()
+    assert "foo" not in sch.dump({"foo": "bar"})
+
+
+def test_embed_only_on_field_includes_field():
+    class MySchema(Schema):
+        foo = fields.Field(embed_only=True)
+
+    sch = MySchema(embed=["foo"])
+    assert "foo" in sch.dump({"foo": "bar"})
+
+
+def test_embed_only_nested():
+    class ChildSchema(Schema):
+        bar = fields.Field(embed_only=True)
+        baz = fields.Field(embed_only=True)
+
+    class ParentSchema(Schema):
+        foo = fields.Nested(ChildSchema(), embed_only=True)
+
+    sch = ParentSchema(embed=["foo.bar"])
+    dump = sch.dump({"foo": {"bar": "val", "baz": "val"}})
+    assert "foo" in dump
+    assert "bar" in dump["foo"]
+    assert "baz" not in dump["foo"]
+
+
+def test_embed_only_nested_child_field():
+    class ChildSchema(Schema):
+        bar = fields.Field(embed_only=True)
+        baz = fields.Field(embed_only=True)
+
+    class ParentSchema(Schema):
+        foo = fields.Nested(ChildSchema(), embed=["bar"], embed_only=True)
+
+    sch = ParentSchema(embed=["foo"])
+    dump = sch.dump({"foo": {"bar": "val", "baz": "val"}})
+    assert "foo" in dump
+    assert "bar" in dump["foo"]
+    assert "baz" not in dump["foo"]
+
+
+def test_embed_only_nested_child_schema():
+    class ChildSchema(Schema):
+        bar = fields.Field(embed_only=True)
+        baz = fields.Field(embed_only=True)
+
+    class ParentSchema(Schema):
+        foo = fields.Nested(ChildSchema(embed=["bar"]), embed_only=True)
+
+    sch = ParentSchema(embed=["foo"])
+    dump = sch.dump({"foo": {"bar": "val", "baz": "val"}})
+    assert "foo" in dump
+    assert "bar" in dump["foo"]
+    assert "baz" not in dump["foo"]
+
+
+def test_embed_only_with_load():
+    class MySchema(Schema):
+        foo = fields.Field(embed_only=True)
+        bar = fields.Field()
+
+    sch = MySchema()
+    data = {"foo": "val", "bar": "val"}
+    obj = sch.load(data)
+    assert "foo" in obj
+    assert "bar" in obj
+
+
 def test_nested_with_sets():
     class Inner(Schema):
         foo = fields.Field()