feat: many consistency between nested schema

Author: Jacques Fournier

src/marshmallow/fields.py

@@ -482,6 +482,9 @@ class ParentSchema(Schema):
     :param only: A list or tuple of fields to marshal. If `None`, all fields are marshalled.
         This parameter takes precedence over ``exclude``.
     :param many: Whether the field is a collection of objects.
+        If `None` (default), and nested `Schema` instance is provided, ``many`` is not overridden.
+        If `None` (default), and `Schema` subclass is provided, schema instance sets ``many`` as False.
+        If `True | False` nested `[nested_field].schema.many` is overridden.
     :param unknown: Whether to exclude, include, or raise an error for unknown
         fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
     :param kwargs: The same keyword arguments that :class:`Field` receives.
@@ -502,7 +505,7 @@ def __init__(
         *,
         only: types.StrSequenceOrSet | None = None,
         exclude: types.StrSequenceOrSet = (),
-        many: bool = False,
+        many: bool | None = None,
         unknown: types.UnknownOption | None = None,
         **kwargs: Unpack[_BaseFieldKwargs],
     ):
@@ -537,7 +540,7 @@ def schema(self) -> Schema:
 
             if isinstance(nested, Schema):
                 self._schema = copy.copy(nested)
-                # Respect only and exclude passed from parent and re-initialize fields
+                # Respect only and exclude and many passed from parent and re-initialize fields
                 set_class = typing.cast("type[set]", self._schema.set_class)
                 if self.only is not None:
                     if self._schema.only is not None:
@@ -548,6 +551,8 @@ def schema(self) -> Schema:
                 if self.exclude:
                     original = self._schema.exclude
                     self._schema.exclude = set_class(self.exclude) | set_class(original)
+                if self.many is not None:
+                    self._schema.many = self.many
                 self._schema._init_fields()
             else:
                 if isinstance(nested, type) and issubclass(nested, Schema):
@@ -560,7 +565,7 @@ def schema(self) -> Schema:
                 else:
                     schema_class = class_registry.get_class(nested, all=False)  # type: ignore[unreachable]
                 self._schema = schema_class(
-                    many=self.many,
+                    many=bool(self.many),
                     only=self.only,
                     exclude=self.exclude,
                     load_only=self._nested_normalized_option("load_only"),

tests/test_schema.py

@@ -2,7 +2,7 @@
 import math
 import random
 from collections import OrderedDict
-from typing import NamedTuple
+from typing import NamedTuple, cast
 
 import pytest
 import simplejson as json
@@ -1003,13 +1003,59 @@ class UserSchema(Schema):
     books = [{"id": 1, "title": "First book"}, {"id": 2, "title": "Second book"}]
     user = {"id": 1, "name": "Peter", "books": books}
 
+    assert cast("fields.Nested", UserSchema().fields["books"]).schema.many
+
+    user_dump = UserSchema().dump(user)
+    assert user_dump["books"] == books
+
+    user_load = UserSchema().load(user_dump)
+    assert user_load == user
+
+
+def test_nested_many_should_override_schema_many_case1():
+    class BookSchema(Schema):
+        id = fields.Int()
+        title = fields.String()
+
+    class UserSchema(Schema):
+        id = fields.Int()
+        name = fields.String()
+        books = fields.Nested(BookSchema(), many=True)
+
+    books = [{"id": 1, "title": "First book"}, {"id": 2, "title": "Second book"}]
+    user = {"id": 1, "name": "Peter", "books": books}
+
+    assert cast("fields.Nested", UserSchema().fields["books"]).schema.many
+
     user_dump = UserSchema().dump(user)
     assert user_dump["books"] == books
 
     user_load = UserSchema().load(user_dump)
     assert user_load == user
 
 
+def test_nested_many_should_override_schema_many_case2():
+    class BookSchema(Schema):
+        id = fields.Int()
+        title = fields.String()
+
+    class UserSchema(Schema):
+        id = fields.Int()
+        name = fields.String()
+        book = fields.Nested(BookSchema(many=True), many=False)
+
+    book = {"id": 1, "title": "First book"}
+    user = {"id": 1, "name": "Peter", "book": book}
+
+    assert not cast("fields.Nested", UserSchema().fields["book"]).schema.many
+
+    user_dump = UserSchema().dump(user)
+    assert user_dump["book"] == book
+
+    user_load = UserSchema().load(user_dump)
+    assert user_load == user
+
+
 def test_nested_instance_only():
     class ArtistSchema(Schema):
         first = fields.Str()