marshmallow 3.26.0__py3-none-any.whl → 4.0.0__py3-none-any.whl

marshmallow/__init__.py

@@ -1,10 +1,4 @@
-from __future__ import annotations
-
-import importlib.metadata
-import typing
-
-from packaging.version import Version
-
+from marshmallow.constants import EXCLUDE, INCLUDE, RAISE, missing
 from marshmallow.decorators import (
     post_dump,
     post_load,
@@ -15,53 +9,9 @@ from marshmallow.decorators import (
 )
 from marshmallow.exceptions import ValidationError
 from marshmallow.schema import Schema, SchemaOpts
-from marshmallow.utils import EXCLUDE, INCLUDE, RAISE, missing, pprint
 
 from . import fields
 
-
-def __getattr__(name: str) -> typing.Any:
-    import warnings
-
-    if name == "__version__":
-        warnings.warn(
-            "The '__version__' attribute is deprecated and will be removed in"
-            " in a future version. Use feature detection or"
-            " 'importlib.metadata.version(\"marshmallow\")' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return importlib.metadata.version("marshmallow")
-
-    if name == "__parsed_version__":
-        warnings.warn(
-            "The '__parsed_version__' attribute is deprecated and will be removed in"
-            " in a future version. Use feature detection or"
-            " 'packaging.Version(importlib.metadata.version(\"marshmallow\"))' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return Version(importlib.metadata.version("marshmallow"))
-
-    if name == "__version_info__":
-        warnings.warn(
-            "The '__version_info__' attribute is deprecated and will be removed in"
-            " in a future version. Use feature detection or"
-            " 'packaging.Version(importlib.metadata.version(\"marshmallow\")).release' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        __parsed_version__ = Version(importlib.metadata.version("marshmallow"))
-        __version_info__: tuple[int, int, int] | tuple[int, int, int, str, int] = (
-            __parsed_version__.release  # type: ignore[assignment]
-        )
-        if __parsed_version__.pre:
-            __version_info__ += __parsed_version__.pre  # type: ignore[assignment]
-        return __version_info__
-
-    raise AttributeError(name)
-
-
 __all__ = [
     "EXCLUDE",
     "INCLUDE",

marshmallow/constants.py

@@ -0,0 +1,22 @@
+import typing
+
+EXCLUDE: typing.Final = "exclude"
+INCLUDE: typing.Final = "include"
+RAISE: typing.Final = "raise"
+
+
+class _Missing:
+    def __bool__(self):
+        return False
+
+    def __copy__(self):
+        return self
+
+    def __deepcopy__(self, _):
+        return self
+
+    def __repr__(self):
+        return "<marshmallow.missing>"
+
+
+missing: typing.Final = _Missing()

marshmallow/decorators.py

@@ -35,12 +35,12 @@ Example: ::
             item["email"] = item["email"].lower().strip()
             return item
 
-        @pre_load(pass_many=True)
+        @pre_load(pass_collection=True)
         def remove_envelope(self, data, many, **kwargs):
             namespace = "results" if many else "result"
             return data[namespace]
 
-        @post_dump(pass_many=True)
+        @post_dump(pass_collection=True)
         def add_envelope(self, data, many, **kwargs):
             namespace = "results" if many else "result"
             return {namespace: data}
@@ -83,25 +83,29 @@ class MarshmallowHook:
     __marshmallow_hook__: dict[str, list[tuple[bool, Any]]] | None = None
 
 
-def validates(field_name: str) -> Callable[..., Any]:
-    """Register a field validator.
+def validates(*field_names: str) -> Callable[..., Any]:
+    """Register a validator method for field(s).
 
-    :param field_name: Name of the field that the method validates.
+    :param field_names: Names of the fields that the method validates.
+
+    .. versionchanged:: 4.0.0 Accepts multiple field names as positional arguments.
+    .. versionchanged:: 4.0.0 Decorated methods receive ``data_key`` as a keyword argument.
     """
-    return set_hook(None, VALIDATES, field_name=field_name)
+    return set_hook(None, VALIDATES, field_names=field_names)
 
 
 def validates_schema(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,  # noqa: FBT001, FBT002
-    pass_original: bool = False,  # noqa: FBT001, FBT002
-    skip_on_field_errors: bool = True,  # noqa: FBT001, FBT002
+    *,
+    pass_collection: bool = False,
+    pass_original: bool = False,
+    skip_on_field_errors: bool = True,
 ) -> Callable[..., Any]:
     """Register a schema-level validator.
 
     By default it receives a single object at a time, transparently handling the ``many``
     argument passed to the `Schema <marshmallow.Schema>`'s :func:`~marshmallow.Schema.validate` call.
-    If ``pass_many=True``, the raw data (which may be a collection) is passed.
+    If ``pass_collection=True``, the raw data (which may be a collection) is passed.
 
     If ``pass_original=True``, the original data (before unmarshalling) will be passed as
     an additional argument to the method.
@@ -109,17 +113,18 @@ def validates_schema(
     If ``skip_on_field_errors=True``, this validation method will be skipped whenever
     validation errors have been detected when validating fields.
 
-    .. versionchanged:: 3.0.0b1
-        ``skip_on_field_errors`` defaults to `True`.
-
-    .. versionchanged:: 3.0.0
-        ``partial`` and ``many`` are always passed as keyword arguments to
+    .. versionchanged:: 3.0.0b1 ``skip_on_field_errors`` defaults to `True`.
+    .. versionchanged:: 3.0.0 ``partial`` and ``many`` are always passed as keyword arguments to
         the decorated method.
+    .. versionchanged:: 4.0.0 ``unknown`` is passed as a keyword argument to the decorated method.
+    .. versionchanged:: 4.0.0 ``pass_many`` is renamed to ``pass_collection``.
+    .. versionchanged:: 4.0.0 ``pass_collection``, ``pass_original``, and ``skip_on_field_errors``
+        are keyword-only arguments.
     """
     return set_hook(
         fn,
         VALIDATES_SCHEMA,
-        many=pass_many,
+        many=pass_collection,
         pass_original=pass_original,
         skip_on_field_errors=skip_on_field_errors,
     )
@@ -127,86 +132,97 @@ def validates_schema(
 
 def pre_dump(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,  # noqa: FBT001, FBT002
+    *,
+    pass_collection: bool = False,
 ) -> Callable[..., Any]:
     """Register a method to invoke before serializing an object. The method
     receives the object to be serialized and returns the processed object.
 
     By default it receives a single object at a time, transparently handling the ``many``
     argument passed to the `Schema <marshmallow.Schema>`'s :func:`~marshmallow.Schema.dump` call.
-    If ``pass_many=True``, the raw data (which may be a collection) is passed.
+    If ``pass_collection=True``, the raw data (which may be a collection) is passed.
 
-    .. versionchanged:: 3.0.0
-        ``many`` is always passed as a keyword arguments to the decorated method.
+    .. versionchanged:: 3.0.0 ``many`` is always passed as a keyword arguments to the decorated method.
+    .. versionchanged:: 4.0.0 ``pass_many`` is renamed to ``pass_collection``.
+    .. versionchanged:: 4.0.0 ``pass_collection`` is a keyword-only argument.
     """
-    return set_hook(fn, PRE_DUMP, many=pass_many)
+    return set_hook(fn, PRE_DUMP, many=pass_collection)
 
 
 def post_dump(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,  # noqa: FBT001, FBT002
-    pass_original: bool = False,  # noqa: FBT001, FBT002
+    *,
+    pass_collection: bool = False,
+    pass_original: bool = False,
 ) -> Callable[..., Any]:
     """Register a method to invoke after serializing an object. The method
     receives the serialized object and returns the processed object.
 
     By default it receives a single object at a time, transparently handling the ``many``
     argument passed to the `Schema <marshmallow.Schema>`'s :func:`~marshmallow.Schema.dump` call.
-    If ``pass_many=True``, the raw data (which may be a collection) is passed.
+    If ``pass_collection=True``, the raw data (which may be a collection) is passed.
 
     If ``pass_original=True``, the original data (before serializing) will be passed as
     an additional argument to the method.
 
-    .. versionchanged:: 3.0.0
-        ``many`` is always passed as a keyword arguments to the decorated method.
+    .. versionchanged:: 3.0.0 ``many`` is always passed as a keyword arguments to the decorated method.
+    .. versionchanged:: 4.0.0 ``pass_many`` is renamed to ``pass_collection``.
+    .. versionchanged:: 4.0.0 ``pass_collection`` and ``pass_original`` are keyword-only arguments.
     """
-    return set_hook(fn, POST_DUMP, many=pass_many, pass_original=pass_original)
+    return set_hook(fn, POST_DUMP, many=pass_collection, pass_original=pass_original)
 
 
 def pre_load(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,  # noqa: FBT001, FBT002
+    *,
+    pass_collection: bool = False,
 ) -> Callable[..., Any]:
     """Register a method to invoke before deserializing an object. The method
     receives the data to be deserialized and returns the processed data.
 
     By default it receives a single object at a time, transparently handling the ``many``
     argument passed to the `Schema <marshmallow.Schema>`'s :func:`~marshmallow.Schema.load` call.
-    If ``pass_many=True``, the raw data (which may be a collection) is passed.
+    If ``pass_collection=True``, the raw data (which may be a collection) is passed.
 
-    .. versionchanged:: 3.0.0
-        ``partial`` and ``many`` are always passed as keyword arguments to
+    .. versionchanged:: 3.0.0 ``partial`` and ``many`` are always passed as keyword arguments to
         the decorated method.
+    .. versionchanged:: 4.0.0 ``pass_many`` is renamed to ``pass_collection``.
+    .. versionchanged:: 4.0.0 ``pass_collection`` is a keyword-only argument.
+    .. versionchanged:: 4.0.0 ``unknown`` is passed as a keyword argument to the decorated method.
     """
-    return set_hook(fn, PRE_LOAD, many=pass_many)
+    return set_hook(fn, PRE_LOAD, many=pass_collection)
 
 
 def post_load(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,  # noqa: FBT001, FBT002
-    pass_original: bool = False,  # noqa: FBT001, FBT002
+    *,
+    pass_collection: bool = False,
+    pass_original: bool = False,
 ) -> Callable[..., Any]:
     """Register a method to invoke after deserializing an object. The method
     receives the deserialized data and returns the processed data.
 
     By default it receives a single object at a time, transparently handling the ``many``
     argument passed to the `Schema <marshmallow.Schema>`'s :func:`~marshmallow.Schema.load` call.
-    If ``pass_many=True``, the raw data (which may be a collection) is passed.
+    If ``pass_collection=True``, the raw data (which may be a collection) is passed.
 
     If ``pass_original=True``, the original data (before deserializing) will be passed as
     an additional argument to the method.
 
-    .. versionchanged:: 3.0.0
-        ``partial`` and ``many`` are always passed as keyword arguments to
+    .. versionchanged:: 3.0.0 ``partial`` and ``many`` are always passed as keyword arguments to
         the decorated method.
+    .. versionchanged:: 4.0.0 ``pass_many`` is renamed to ``pass_collection``.
+    .. versionchanged:: 4.0.0 ``pass_collection`` and ``pass_original`` are keyword-only arguments.
+    .. versionchanged:: 4.0.0 ``unknown`` is passed as a keyword argument to the decorated method.
     """
-    return set_hook(fn, POST_LOAD, many=pass_many, pass_original=pass_original)
+    return set_hook(fn, POST_LOAD, many=pass_collection, pass_original=pass_original)
 
 
 def set_hook(
     fn: Callable[..., Any] | None,
     tag: str,
-    many: bool = False,  # noqa: FBT001, FBT002
+    *,
+    many: bool = False,
     **kwargs: Any,
 ) -> Callable[..., Any]:
     """Mark decorated function as a hook to be picked up later.
@@ -225,7 +241,7 @@ def set_hook(
 
     # Set a __marshmallow_hook__ attribute instead of wrapping in some class,
     # because I still want this to end up as a normal (unbound) method.
-    function = cast(MarshmallowHook, fn)
+    function = cast("MarshmallowHook", fn)
     try:
         hook_config = function.__marshmallow_hook__
     except AttributeError:

marshmallow/exceptions.py

@@ -32,7 +32,7 @@ class ValidationError(MarshmallowError):
         data: typing.Mapping[str, typing.Any]
         | typing.Iterable[typing.Mapping[str, typing.Any]]
         | None = None,
-        valid_data: list[dict[str, typing.Any]] | dict[str, typing.Any] | None = None,
+        valid_data: list[typing.Any] | dict[str, typing.Any] | None = None,
         **kwargs,
     ):
         self.messages = [message] if isinstance(message, (str, bytes)) else message
@@ -67,5 +67,5 @@ class StringNotCollectionError(MarshmallowError, TypeError):
     """Raised when a string is passed when a list of strings is expected."""
 
 
-class FieldInstanceResolutionError(MarshmallowError, TypeError):
-    """Raised when schema to instantiate is neither a Schema class nor an instance."""
+class _FieldInstanceResolutionError(MarshmallowError, TypeError):
+    """Raised when an argument is passed to a field class that cannot be resolved to a Field instance."""

marshmallow/experimental/__init__.py

@@ -0,0 +1,5 @@
+"""Experimental features.
+
+The features in this subpackage are experimental. Breaking changes may be
+introduced in minor marshmallow versions.
+"""

marshmallow/experimental/context.py

@@ -0,0 +1,73 @@
+"""Helper API for setting serialization/deserialization context.
+
+Example usage:
+
+.. code-block:: python
+
+    import typing
+
+    from marshmallow import Schema, fields
+    from marshmallow.experimental.context import Context
+
+
+    class UserContext(typing.TypedDict):
+        suffix: str
+
+
+    UserSchemaContext = Context[UserContext]
+
+
+    class UserSchema(Schema):
+        name_suffixed = fields.Function(
+            lambda user: user["name"] + UserSchemaContext.get()["suffix"]
+        )
+
+
+    with UserSchemaContext({"suffix": "bar"}):
+        print(UserSchema().dump({"name": "foo"}))
+        # {'name_suffixed': 'foobar'}
+"""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import typing
+
+try:
+    from types import EllipsisType
+except ImportError:  # Python<3.10
+    EllipsisType = type(Ellipsis)  # type: ignore[misc]
+
+_ContextT = typing.TypeVar("_ContextT")
+_DefaultT = typing.TypeVar("_DefaultT")
+_CURRENT_CONTEXT: contextvars.ContextVar = contextvars.ContextVar("context")
+
+
+class Context(contextlib.AbstractContextManager, typing.Generic[_ContextT]):
+    """Context manager for setting and retrieving context.
+
+    :param context: The context to use within the context manager scope.
+    """
+
+    def __init__(self, context: _ContextT) -> None:
+        self.context = context
+        self.token: contextvars.Token | None = None
+
+    def __enter__(self) -> Context[_ContextT]:
+        self.token = _CURRENT_CONTEXT.set(self.context)
+        return self
+
+    def __exit__(self, *args, **kwargs) -> None:
+        _CURRENT_CONTEXT.reset(typing.cast("contextvars.Token", self.token))
+
+    @classmethod
+    def get(cls, default: _DefaultT | EllipsisType = ...) -> _ContextT | _DefaultT:
+        """Get the current context.
+
+        :param default: Default value to return if no context is set.
+            If not provided and no context is set, a :exc:`LookupError` is raised.
+        """
+        if default is not ...:
+            return _CURRENT_CONTEXT.get(default)
+        return _CURRENT_CONTEXT.get()