marshmallow 3.21.3__tar.gz → 3.22.0__tar.gz

{marshmallow-3.21.3 → marshmallow-3.22.0}/CHANGELOG.rst

@@ -1,6 +1,16 @@
 Changelog
 ---------
 
+3.22.0 (2024-08-20)
+*******************
+
+Features:
+
+- Add ``many`` Meta option to ``Schema`` so it expects a collection by default (:issue:`2270`).
+  Thanks :user:`himalczyk` for reporting and :user:`deckar01` for the PR.
+- Refactor hooks (:pr:`2279`).
+  Thanks :user:`deckar01` for the PR.
+
 3.21.3 (2024-06-05)
 *******************
 

{marshmallow-3.21.3 → marshmallow-3.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: marshmallow
-Version: 3.21.3
+Version: 3.22.0
 Summary: A lightweight library for converting complex datatypes to and from native Python datatypes.
 Author-email: Steven Loria <sloria1@gmail.com>
 Maintainer-email: Steven Loria <sloria1@gmail.com>, Jérôme Lafréchoux <jerome@jolimont.fr>, Jared Deckard <jared@shademaps.com>
@@ -19,11 +19,11 @@ Requires-Dist: packaging>=17.0
 Requires-Dist: marshmallow[tests] ; extra == "dev"
 Requires-Dist: tox ; extra == "dev"
 Requires-Dist: pre-commit~=3.5 ; extra == "dev"
-Requires-Dist: sphinx==7.3.7 ; extra == "docs"
+Requires-Dist: sphinx==8.0.2 ; extra == "docs"
 Requires-Dist: sphinx-issues==4.1.0 ; extra == "docs"
-Requires-Dist: alabaster==0.7.16 ; extra == "docs"
+Requires-Dist: alabaster==1.0.0 ; extra == "docs"
 Requires-Dist: sphinx-version-warning==1.1.2 ; extra == "docs"
-Requires-Dist: autodocsumm==0.2.12 ; extra == "docs"
+Requires-Dist: autodocsumm==0.2.13 ; extra == "docs"
 Requires-Dist: pytest ; extra == "tests"
 Requires-Dist: pytz ; extra == "tests"
 Requires-Dist: simplejson ; extra == "tests"
@@ -40,19 +40,21 @@ Provides-Extra: tests
 marshmallow: simplified object serialization
 ********************************************
 
-.. image:: https://badgen.net/pypi/v/marshmallow
+|pypi| |build-status| |pre-commit| |docs|
+
+.. |pypi| image:: https://badgen.net/pypi/v/marshmallow
     :target: https://pypi.org/project/marshmallow/
     :alt: Latest version
 
-.. image:: https://github.com/marshmallow-code/marshmallow/actions/workflows/build-release.yml/badge.svg
+.. |build-status| image:: https://github.com/marshmallow-code/marshmallow/actions/workflows/build-release.yml/badge.svg
     :target: https://github.com/marshmallow-code/marshmallow/actions/workflows/build-release.yml
     :alt: Build status
 
-.. image:: https://results.pre-commit.ci/badge/github/marshmallow-code/marshmallow/dev.svg
+.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/marshmallow-code/marshmallow/dev.svg
    :target: https://results.pre-commit.ci/latest/github/marshmallow-code/marshmallow/dev
    :alt: pre-commit.ci status
 
-.. image:: https://readthedocs.org/projects/marshmallow/badge/
+.. |docs| image:: https://readthedocs.org/projects/marshmallow/badge/
    :target: https://marshmallow.readthedocs.io/
    :alt: Documentation
 
@@ -152,15 +154,16 @@ Thank you to all our backers! [`Become a backer`_]
 Sponsors
 --------
 
-Support this project by becoming a sponsor (or ask your company to support this project by becoming a sponsor).
-Your logo will show up here with a link to your website. [`Become a sponsor`_]
+marshmallow is sponsored by `Route4Me <https://route4me.com>`_.
 
-.. _`Become a sponsor`: https://opencollective.com/marshmallow#sponsor
+.. image:: https://github.com/user-attachments/assets/018c2e23-032e-4a11-98da-8b6dc25b9054
+    :target: https://route4me.com
+    :alt: Routing Planner
 
-.. image:: https://opencollective.com/static/images/become_sponsor.svg
-    :target: https://opencollective.com/marshmallow#sponsor
-    :alt: Become a sponsor
+Support this project by becoming a sponsor (or ask your company to support this project by becoming a sponsor).
+Your logo will be displayed here with a link to your website. [`Become a sponsor`_]
 
+.. _`Become a sponsor`: https://opencollective.com/marshmallow#sponsor
 
 Professional Support
 ====================

{marshmallow-3.21.3 → marshmallow-3.22.0}/README.rst

@@ -2,19 +2,21 @@
 marshmallow: simplified object serialization
 ********************************************
 
-.. image:: https://badgen.net/pypi/v/marshmallow
+|pypi| |build-status| |pre-commit| |docs|
+
+.. |pypi| image:: https://badgen.net/pypi/v/marshmallow
     :target: https://pypi.org/project/marshmallow/
     :alt: Latest version
 
-.. image:: https://github.com/marshmallow-code/marshmallow/actions/workflows/build-release.yml/badge.svg
+.. |build-status| image:: https://github.com/marshmallow-code/marshmallow/actions/workflows/build-release.yml/badge.svg
     :target: https://github.com/marshmallow-code/marshmallow/actions/workflows/build-release.yml
     :alt: Build status
 
-.. image:: https://results.pre-commit.ci/badge/github/marshmallow-code/marshmallow/dev.svg
+.. |pre-commit| image:: https://results.pre-commit.ci/badge/github/marshmallow-code/marshmallow/dev.svg
    :target: https://results.pre-commit.ci/latest/github/marshmallow-code/marshmallow/dev
    :alt: pre-commit.ci status
 
-.. image:: https://readthedocs.org/projects/marshmallow/badge/
+.. |docs| image:: https://readthedocs.org/projects/marshmallow/badge/
    :target: https://marshmallow.readthedocs.io/
    :alt: Documentation
 
@@ -114,15 +116,16 @@ Thank you to all our backers! [`Become a backer`_]
 Sponsors
 --------
 
-Support this project by becoming a sponsor (or ask your company to support this project by becoming a sponsor).
-Your logo will show up here with a link to your website. [`Become a sponsor`_]
+marshmallow is sponsored by `Route4Me <https://route4me.com>`_.
 
-.. _`Become a sponsor`: https://opencollective.com/marshmallow#sponsor
+.. image:: https://github.com/user-attachments/assets/018c2e23-032e-4a11-98da-8b6dc25b9054
+    :target: https://route4me.com
+    :alt: Routing Planner
 
-.. image:: https://opencollective.com/static/images/become_sponsor.svg
-    :target: https://opencollective.com/marshmallow#sponsor
-    :alt: Become a sponsor
+Support this project by becoming a sponsor (or ask your company to support this project by becoming a sponsor).
+Your logo will be displayed here with a link to your website. [`Become a sponsor`_]
 
+.. _`Become a sponsor`: https://opencollective.com/marshmallow#sponsor
 
 Professional Support
 ====================

{marshmallow-3.21.3 → marshmallow-3.22.0}/docs/index.rst

@@ -18,6 +18,19 @@ Why another library?
 
 See :doc:`this document <why>` to learn about what makes marshmallow unique.
 
+Sponsors
+========
+
+marshmallow is sponsored by `Route4Me <https://route4me.com>`_.
+
+.. image:: https://github.com/user-attachments/assets/018c2e23-032e-4a11-98da-8b6dc25b9054
+    :target: https://route4me.com
+    :alt: Routing Planner
+
+Support this project by becoming a sponsor (or ask your company to support this project by becoming a sponsor).
+Your logo will be displayed here with a link to your website. [`Become a sponsor`_]
+
+.. _`Become a sponsor`: https://opencollective.com/marshmallow#sponsor
 
 Guide
 =====

{marshmallow-3.21.3 → marshmallow-3.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "marshmallow"
-version = "3.21.3"
+version = "3.22.0"
 description = "A lightweight library for converting complex datatypes to and from native Python datatypes."
 readme = "README.rst"
 license = { file = "LICENSE" }
@@ -33,11 +33,11 @@ Tidelift = "https://tidelift.com/subscription/pkg/pypi-marshmallow?utm_source=py
 
 [project.optional-dependencies]
 docs = [
-  "sphinx==7.3.7",
+  "sphinx==8.0.2",
   "sphinx-issues==4.1.0",
-  "alabaster==0.7.16",
+  "alabaster==1.0.0",
   "sphinx-version-warning==1.1.2",
-  "autodocsumm==0.2.12",
+  "autodocsumm==0.2.13",
 ]
 tests = ["pytest", "pytz", "simplejson"]
 dev = ["marshmallow[tests]", "tox", "pre-commit~=3.5"]

{marshmallow-3.21.3 → marshmallow-3.22.0}/src/marshmallow/decorators.py

@@ -68,6 +68,7 @@ Example: ::
 from __future__ import annotations
 
 import functools
+from collections import defaultdict
 from typing import Any, Callable, cast
 
 PRE_DUMP = "pre_dump"
@@ -79,7 +80,7 @@ VALIDATES_SCHEMA = "validates_schema"
 
 
 class MarshmallowHook:
-    __marshmallow_hook__: dict[tuple[str, bool] | str, Any] | None = None
+    __marshmallow_hook__: dict[str, list[tuple[bool, Any]]] | None = None
 
 
 def validates(field_name: str) -> Callable[..., Any]:
@@ -117,7 +118,8 @@ def validates_schema(
     """
     return set_hook(
         fn,
-        (VALIDATES_SCHEMA, pass_many),
+        VALIDATES_SCHEMA,
+        many=pass_many,
         pass_original=pass_original,
         skip_on_field_errors=skip_on_field_errors,
     )
@@ -136,7 +138,7 @@ def pre_dump(
     .. versionchanged:: 3.0.0
         ``many`` is always passed as a keyword arguments to the decorated method.
     """
-    return set_hook(fn, (PRE_DUMP, pass_many))
+    return set_hook(fn, PRE_DUMP, many=pass_many)
 
 
 def post_dump(
@@ -157,7 +159,7 @@ def post_dump(
     .. versionchanged:: 3.0.0
         ``many`` is always passed as a keyword arguments to the decorated method.
     """
-    return set_hook(fn, (POST_DUMP, pass_many), pass_original=pass_original)
+    return set_hook(fn, POST_DUMP, many=pass_many, pass_original=pass_original)
 
 
 def pre_load(
@@ -174,7 +176,7 @@ def pre_load(
         ``partial`` and ``many`` are always passed as keyword arguments to
         the decorated method.
     """
-    return set_hook(fn, (PRE_LOAD, pass_many))
+    return set_hook(fn, PRE_LOAD, many=pass_many)
 
 
 def post_load(
@@ -196,11 +198,11 @@ def post_load(
         ``partial`` and ``many`` are always passed as keyword arguments to
         the decorated method.
     """
-    return set_hook(fn, (POST_LOAD, pass_many), pass_original=pass_original)
+    return set_hook(fn, POST_LOAD, many=pass_many, pass_original=pass_original)
 
 
 def set_hook(
-    fn: Callable[..., Any] | None, key: tuple[str, bool] | str, **kwargs: Any
+    fn: Callable[..., Any] | None, tag: str, many: bool = False, **kwargs: Any
 ) -> Callable[..., Any]:
     """Mark decorated function as a hook to be picked up later.
     You should not need to use this method directly.
@@ -214,7 +216,7 @@ def set_hook(
     """
     # Allow using this as either a decorator or a decorator factory.
     if fn is None:
-        return functools.partial(set_hook, key=key, **kwargs)
+        return functools.partial(set_hook, tag=tag, many=many, **kwargs)
 
     # Set a __marshmallow_hook__ attribute instead of wrapping in some class,
     # because I still want this to end up as a normal (unbound) method.
@@ -222,10 +224,10 @@ def set_hook(
     try:
         hook_config = function.__marshmallow_hook__
     except AttributeError:
-        function.__marshmallow_hook__ = hook_config = {}
+        function.__marshmallow_hook__ = hook_config = defaultdict(list)
     # Also save the kwargs for the tagged function on
-    # __marshmallow_hook__, keyed by (<tag>, <pass_many>)
+    # __marshmallow_hook__, keyed by <tag>
     if hook_config is not None:
-        hook_config[key] = kwargs
+        hook_config[tag].append((many, kwargs))
 
     return fn

{marshmallow-3.21.3 → marshmallow-3.22.0}/src/marshmallow/schema.py

@@ -148,7 +148,7 @@ class SchemaMeta(ABCMeta):
             class_registry.register(name, cls)
         cls._hooks = cls.resolve_hooks()
 
-    def resolve_hooks(cls) -> dict[types.Tag, list[str]]:
+    def resolve_hooks(cls) -> dict[str, list[tuple[str, bool, dict]]]:
         """Add in the decorated processors
 
         By doing this after constructing the class, we let standard inheritance
@@ -156,7 +156,7 @@ class SchemaMeta(ABCMeta):
         """
         mro = inspect.getmro(cls)
 
-        hooks = defaultdict(list)  # type: typing.Dict[types.Tag, typing.List[str]]
+        hooks = defaultdict(list)  # type: typing.Dict[str, typing.List[typing.Tuple[str, bool, dict]]]
 
         for attr_name in dir(cls):
             # Need to look up the actual descriptor, not whatever might be
@@ -176,14 +176,16 @@ class SchemaMeta(ABCMeta):
                 continue
 
             try:
-                hook_config = attr.__marshmallow_hook__
+                hook_config = attr.__marshmallow_hook__  # type: typing.Dict[str, typing.List[typing.Tuple[bool, dict]]]
             except AttributeError:
                 pass
             else:
-                for key in hook_config.keys():
+                for tag, config in hook_config.items():
                     # Use name here so we can get the bound method later, in
                     # case the processor was a descriptor or something.
-                    hooks[key].append(attr_name)
+                    hooks[tag].extend(
+                        (attr_name, many, kwargs) for many, kwargs in config
+                    )
 
         return hooks
 
@@ -226,6 +228,7 @@ class SchemaOpts:
         self.dump_only = getattr(meta, "dump_only", ())
         self.unknown = validate_unknown_parameter_value(getattr(meta, "unknown", RAISE))
         self.register = getattr(meta, "register", True)
+        self.many = getattr(meta, "many", False)
 
 
 class Schema(base.SchemaABC, metaclass=SchemaMeta):
@@ -319,7 +322,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
     # These get set by SchemaMeta
     opts = None  # type: SchemaOpts
     _declared_fields = {}  # type: typing.Dict[str, ma_fields.Field]
-    _hooks = {}  # type: typing.Dict[types.Tag, typing.List[str]]
+    _hooks = {}  # type: typing.Dict[str, typing.List[typing.Tuple[str, bool, dict]]]
 
     class Meta:
         """Options object for a Schema.
@@ -342,6 +345,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
             `OrderedDict`.
         - ``exclude``: Tuple or list of fields to exclude in the serialized result.
             Nested fields can be represented with dot delimiters.
+        - ``many``: Whether the data is a collection by default.
         - ``dateformat``: Default format for `Date <fields.Date>` fields.
         - ``datetimeformat``: Default format for `DateTime <fields.DateTime>` fields.
         - ``timeformat``: Default format for `Time <fields.Time>` fields.
@@ -365,7 +369,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         *,
         only: types.StrSequenceOrSet | None = None,
         exclude: types.StrSequenceOrSet = (),
-        many: bool = False,
+        many: bool | None = None,
         context: dict | None = None,
         load_only: types.StrSequenceOrSet = (),
         dump_only: types.StrSequenceOrSet = (),
@@ -379,7 +383,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
             raise StringNotCollectionError('"exclude" should be a list of strings')
         # copy declared fields from metaclass
         self.declared_fields = copy.deepcopy(self._declared_fields)
-        self.many = many
+        self.many = self.opts.many if many is None else many
         self.only = only
         self.exclude: set[typing.Any] | typing.MutableSet[typing.Any] = set(
             self.opts.exclude
@@ -539,7 +543,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
             Validation no longer occurs upon serialization.
         """
         many = self.many if many is None else bool(many)
-        if self._has_processors(PRE_DUMP):
+        if self._hooks[PRE_DUMP]:
             processed_obj = self._invoke_dump_processors(
                 PRE_DUMP, obj, many=many, original_data=obj
             )
@@ -548,7 +552,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
 
         result = self._serialize(processed_obj, many=many)
 
-        if self._has_processors(POST_DUMP):
+        if self._hooks[POST_DUMP]:
             result = self._invoke_dump_processors(
                 POST_DUMP, result, many=many, original_data=obj
             )
@@ -846,7 +850,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         if partial is None:
             partial = self.partial
         # Run preprocessors
-        if self._has_processors(PRE_LOAD):
+        if self._hooks[PRE_LOAD]:
             try:
                 processed_data = self._invoke_load_processors(
                     PRE_LOAD, data, many=many, original_data=data, partial=partial
@@ -870,7 +874,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
                 error_store=error_store, data=result, many=many
             )
             # Run schema-level validation
-            if self._has_processors(VALIDATES_SCHEMA):
+            if self._hooks[VALIDATES_SCHEMA]:
                 field_errors = bool(error_store.errors)
                 self._invoke_schema_validators(
                     error_store=error_store,
@@ -892,7 +896,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
                 )
             errors = error_store.errors
             # Run post processors
-            if not errors and postprocess and self._has_processors(POST_LOAD):
+            if not errors and postprocess and self._hooks[POST_LOAD]:
                 try:
                     result = self._invoke_load_processors(
                         POST_LOAD,
@@ -1055,9 +1059,6 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
             raise error
         self.on_bind_field(field_name, field_obj)
 
-    def _has_processors(self, tag) -> bool:
-        return bool(self._hooks[(tag, True)] or self._hooks[(tag, False)])
-
     def _invoke_dump_processors(
         self, tag: str, data, *, many: bool, original_data=None
     ):
@@ -1102,9 +1103,8 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         return data
 
     def _invoke_field_validators(self, *, error_store: ErrorStore, data, many: bool):
-        for attr_name in self._hooks[VALIDATES]:
+        for attr_name, _, validator_kwargs in self._hooks[VALIDATES]:
             validator = getattr(self, attr_name)
-            validator_kwargs = validator.__marshmallow_hook__[VALIDATES]
             field_name = validator_kwargs["field_name"]
 
             try:
@@ -1159,11 +1159,10 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         partial: bool | types.StrSequenceOrSet | None,
         field_errors: bool = False,
     ):
-        for attr_name in self._hooks[(VALIDATES_SCHEMA, pass_many)]:
+        for attr_name, hook_many, validator_kwargs in self._hooks[VALIDATES_SCHEMA]:
+            if hook_many != pass_many:
+                continue
             validator = getattr(self, attr_name)
-            validator_kwargs = validator.__marshmallow_hook__[
-                (VALIDATES_SCHEMA, pass_many)
-            ]
             if field_errors and validator_kwargs["skip_on_field_errors"]:
                 continue
             pass_original = validator_kwargs.get("pass_original", False)
@@ -1201,12 +1200,11 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         original_data=None,
         **kwargs,
     ):
-        key = (tag, pass_many)
-        for attr_name in self._hooks[key]:
+        for attr_name, hook_many, processor_kwargs in self._hooks[tag]:
+            if hook_many != pass_many:
+                continue
             # This will be a bound method.
             processor = getattr(self, attr_name)
-
-            processor_kwargs = processor.__marshmallow_hook__[key]
             pass_original = processor_kwargs.get("pass_original", False)
 
             if many and not pass_many:

{marshmallow-3.21.3 → marshmallow-3.22.0}/src/marshmallow/types.py

@@ -8,5 +8,4 @@
 import typing
 
 StrSequenceOrSet = typing.Union[typing.Sequence[str], typing.AbstractSet[str]]
-Tag = typing.Union[str, typing.Tuple[str, bool]]
 Validator = typing.Callable[[typing.Any], typing.Any]

{marshmallow-3.21.3 → marshmallow-3.22.0}/tests/test_options.py

@@ -262,3 +262,19 @@ class TestIncludeOption:
         assert "email" in s._declared_fields.keys()
         assert "from" in s._declared_fields.keys()
         assert isinstance(s._declared_fields["from"], fields.Str)
+
+
+class TestManyOption:
+    class ManySchema(Schema):
+        foo = fields.Str()
+
+        class Meta:
+            many = True
+
+    def test_many_by_default(self):
+        test = self.ManySchema()
+        assert test.load([{"foo": "bar"}]) == [{"foo": "bar"}]
+
+    def test_explicit_single(self):
+        test = self.ManySchema(many=False)
+        assert test.load({"foo": "bar"}) == {"foo": "bar"}