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

marshmallow/__init__.py

@@ -68,14 +68,14 @@ __all__ = [
     "RAISE",
     "Schema",
     "SchemaOpts",
+    "ValidationError",
     "fields",
-    "validates",
-    "validates_schema",
-    "pre_dump",
+    "missing",
     "post_dump",
-    "pre_load",
     "post_load",
     "pprint",
-    "ValidationError",
-    "missing",
+    "pre_dump",
+    "pre_load",
+    "validates",
+    "validates_schema",
 ]

marshmallow/class_registry.py

@@ -7,6 +7,7 @@ class:`fields.Nested <marshmallow.fields.Nested>`.
     This module is treated as private API.
     Users should not need to use this module directly.
 """
+# ruff: noqa: ERA001
 
 from __future__ import annotations
 
@@ -49,7 +50,7 @@ def register(classname: str, cls: SchemaType) -> None:
     module = cls.__module__
     # Full module path to the class
     # e.g. user.schemas.UserSchema
-    fullpath = ".".join([module, classname])
+    fullpath = f"{module}.{classname}"
     # If the class is already registered; need to check if the entries are
     # in the same module as cls to avoid having multiple instances of the same
     # class in the registry
@@ -66,23 +67,22 @@ def register(classname: str, cls: SchemaType) -> None:
     else:
         # If fullpath does exist, replace existing entry
         _registry[fullpath] = [cls]
-    return None
 
 
 @typing.overload
-def get_class(classname: str, all: typing.Literal[False] = ...) -> SchemaType: ...
+def get_class(classname: str, *, all: typing.Literal[False] = ...) -> SchemaType: ...
 
 
 @typing.overload
 def get_class(
-    classname: str, all: typing.Literal[True] = ...
-) -> list[SchemaType] | SchemaType: ...
+    classname: str, *, all: typing.Literal[True] = ...
+) -> list[SchemaType]: ...
 
 
-def get_class(classname: str, all: bool = False) -> list[SchemaType] | SchemaType:
+def get_class(classname: str, *, all: bool = False) -> list[SchemaType] | SchemaType:  # noqa: A002
     """Retrieve a class from the registry.
 
-    :raises: marshmallow.exceptions.RegistryError if the class cannot be found
+    :raises: `marshmallow.exceptions.RegistryError` if the class cannot be found
         or if there are multiple entries for the given class name.
     """
     try:
@@ -100,5 +100,4 @@ def get_class(classname: str, all: bool = False) -> list[SchemaType] | SchemaTyp
             "were found. Please use the full, "
             "module-qualified path."
         )
-    else:
-        return _registry[classname][0]
+    return _registry[classname][0]

marshmallow/decorators.py

@@ -86,16 +86,16 @@ class MarshmallowHook:
 def validates(field_name: str) -> Callable[..., Any]:
     """Register a field validator.
 
-    :param str field_name: Name of the field that the method validates.
+    :param field_name: Name of the field that the method validates.
     """
     return set_hook(None, VALIDATES, field_name=field_name)
 
 
 def validates_schema(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,
-    pass_original: bool = False,
-    skip_on_field_errors: bool = True,
+    pass_many: bool = False,  # noqa: FBT001, FBT002
+    pass_original: bool = False,  # noqa: FBT001, FBT002
+    skip_on_field_errors: bool = True,  # noqa: FBT001, FBT002
 ) -> Callable[..., Any]:
     """Register a schema-level validator.
 
@@ -126,7 +126,8 @@ def validates_schema(
 
 
 def pre_dump(
-    fn: Callable[..., Any] | None = None, pass_many: bool = False
+    fn: Callable[..., Any] | None = None,
+    pass_many: bool = False,  # noqa: FBT001, FBT002
 ) -> Callable[..., Any]:
     """Register a method to invoke before serializing an object. The method
     receives the object to be serialized and returns the processed object.
@@ -143,8 +144,8 @@ def pre_dump(
 
 def post_dump(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,
-    pass_original: bool = False,
+    pass_many: bool = False,  # noqa: FBT001, FBT002
+    pass_original: bool = False,  # noqa: FBT001, FBT002
 ) -> Callable[..., Any]:
     """Register a method to invoke after serializing an object. The method
     receives the serialized object and returns the processed object.
@@ -163,7 +164,8 @@ def post_dump(
 
 
 def pre_load(
-    fn: Callable[..., Any] | None = None, pass_many: bool = False
+    fn: Callable[..., Any] | None = None,
+    pass_many: bool = False,  # noqa: FBT001, FBT002
 ) -> Callable[..., Any]:
     """Register a method to invoke before deserializing an object. The method
     receives the data to be deserialized and returns the processed data.
@@ -181,8 +183,8 @@ def pre_load(
 
 def post_load(
     fn: Callable[..., Any] | None = None,
-    pass_many: bool = False,
-    pass_original: bool = False,
+    pass_many: bool = False,  # noqa: FBT001, FBT002
+    pass_original: bool = False,  # noqa: FBT001, FBT002
 ) -> Callable[..., Any]:
     """Register a method to invoke after deserializing an object. The method
     receives the deserialized data and returns the processed data.
@@ -202,7 +204,10 @@ def post_load(
 
 
 def set_hook(
-    fn: Callable[..., Any] | None, tag: str, many: bool = False, **kwargs: Any
+    fn: Callable[..., Any] | None,
+    tag: str,
+    many: bool = False,  # noqa: FBT001, FBT002
+    **kwargs: Any,
 ) -> Callable[..., Any]:
     """Mark decorated function as a hook to be picked up later.
     You should not need to use this method directly.

marshmallow/error_store.py

@@ -25,7 +25,7 @@ class ErrorStore:
         self.errors = merge_errors(self.errors, messages)
 
 
-def merge_errors(errors1, errors2):
+def merge_errors(errors1, errors2):  # noqa: PLR0911
     """Deeply merge two error messages.
 
     The format of ``errors1`` and ``errors2`` matches the ``message``
@@ -40,7 +40,7 @@ def merge_errors(errors1, errors2):
             return errors1 + errors2
         if isinstance(errors2, dict):
             return dict(errors2, **{SCHEMA: merge_errors(errors1, errors2.get(SCHEMA))})
-        return errors1 + [errors2]
+        return [*errors1, errors2]
     if isinstance(errors1, dict):
         if isinstance(errors2, list):
             return dict(errors1, **{SCHEMA: merge_errors(errors1.get(SCHEMA), errors2)})
@@ -54,7 +54,7 @@ def merge_errors(errors1, errors2):
             return errors
         return dict(errors1, **{SCHEMA: merge_errors(errors1.get(SCHEMA), errors2)})
     if isinstance(errors2, list):
-        return [errors1] + errors2
+        return [errors1, *errors2]
     if isinstance(errors2, dict):
         return dict(errors2, **{SCHEMA: merge_errors(errors1, errors2.get(SCHEMA))})
     return [errors1, errors2]

marshmallow/fields.py

@@ -1,3 +1,4 @@
+# ruff: noqa: F841, SLF001
 from __future__ import annotations
 
 import collections
@@ -11,7 +12,6 @@ import typing
 import uuid
 import warnings
 from collections.abc import Mapping as _Mapping
-from enum import Enum as EnumType
 
 from marshmallow import class_registry, types, utils, validate
 from marshmallow.base import FieldABC
@@ -35,54 +35,54 @@ from marshmallow.warnings import (
 )
 
 if typing.TYPE_CHECKING:
+    from enum import Enum as EnumType
+
     from marshmallow.schema import Schema, SchemaMeta
 
 
 __all__ = [
-    "Field",
-    "Raw",
-    "Nested",
-    "Mapping",
-    "Dict",
-    "List",
-    "Tuple",
-    "String",
+    "IP",
+    "URL",
     "UUID",
-    "Number",
-    "Integer",
-    "Decimal",
-    "Boolean",
-    "Float",
-    "DateTime",
-    "NaiveDateTime",
     "AwareDateTime",
-    "Time",
+    "Bool",
+    "Boolean",
+    "Constant",
     "Date",
-    "TimeDelta",
-    "Url",
-    "URL",
+    "DateTime",
+    "Decimal",
+    "Dict",
     "Email",
-    "IP",
-    "IPv4",
-    "IPv6",
+    "Enum",
+    "Field",
+    "Float",
+    "Function",
     "IPInterface",
+    "IPv4",
     "IPv4Interface",
+    "IPv6",
     "IPv6Interface",
-    "Enum",
-    "Method",
-    "Function",
-    "Str",
-    "Bool",
     "Int",
-    "Constant",
+    "Integer",
+    "List",
+    "Mapping",
+    "Method",
+    "NaiveDateTime",
+    "Nested",
+    "Number",
     "Pluck",
+    "Raw",
+    "Str",
+    "String",
+    "Time",
+    "TimeDelta",
+    "Tuple",
+    "Url",
 ]
 
 
 class Field(FieldABC):
-    """Basic field from which other fields should extend. It applies no
-    formatting by default, and should only be used in cases where
-    data does not need to be formatted before being serialized or deserialized.
+    """Base field from which other fields inherit.
 
     :param dump_default: If set, this value will be used during serialization if the
         input value is missing. If not set, the field will be excluded from the
@@ -114,7 +114,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 dict error_messages: Overrides for `Field.default_error_messages`.
+    :param error_messages: Overrides for `Field.default_error_messages`.
     :param metadata: Extra information to be stored as field metadata.
 
     .. versionchanged:: 3.0.0b8
@@ -123,6 +123,10 @@ class Field(FieldABC):
 
     .. versionchanged:: 3.13.0
         Replace ``missing`` and ``default`` parameters with ``load_default`` and ``dump_default``.
+
+    .. versionchanged:: 3.24.0
+        `Field <marshmallow.fields.Field>` should no longer be used as a field within a `Schema <marshmallow.Schema>`.
+        Use `Raw <marshmallow.fields.Raw>` or another `Field <marshmallow.fields.Field>` subclass instead.
     """
 
     # Some fields, such as Method fields and Function fields, are not expected
@@ -148,11 +152,7 @@ class Field(FieldABC):
         default: typing.Any = missing_,
         data_key: str | None = None,
         attribute: str | None = None,
-        validate: (
-            typing.Callable[[typing.Any], typing.Any]
-            | typing.Iterable[typing.Callable[[typing.Any], typing.Any]]
-            | None
-        ) = None,
+        validate: types.Validator | typing.Iterable[types.Validator] | None = None,
         required: bool = False,
         allow_none: bool | None = None,
         load_only: bool = False,
@@ -260,9 +260,9 @@ class Field(FieldABC):
     ):
         """Return the value for a given key from an object.
 
-        :param object obj: The object to get the value from.
-        :param str attr: The attribute/key in `obj` to get the value from.
-        :param callable accessor: A callable used to retrieve the value of `attr` from
+        :param obj: The object to get the value from.
+        :param attr: The attribute/key in `obj` to get the value from.
+        :param accessor: A callable used to retrieve the value of `attr` from
             the object `obj`. Defaults to `marshmallow.utils.get_value`.
         """
         accessor_func = accessor or utils.get_value
@@ -381,8 +381,8 @@ class Field(FieldABC):
         """Update field with values from its parent schema. Called by
         `Schema._bind_field <marshmallow.Schema._bind_field>`.
 
-        :param str field_name: Field name set in schema.
-        :param Schema|Field schema: Parent object.
+        :param field_name: Field name set in schema.
+        :param schema: Parent object.
         """
         self.parent = self.parent or schema
         self.name = self.name or field_name
@@ -405,9 +405,9 @@ class Field(FieldABC):
                     return str(value).title()
 
         :param value: The value to be serialized.
-        :param str attr: The attribute or key on the object to be serialized.
-        :param object obj: The object the value was pulled from.
-        :param dict kwargs: Field-specific keyword arguments.
+        :param attr: The attribute or key on the object to be serialized.
+        :param obj: The object the value was pulled from.
+        :param kwargs: Field-specific keyword arguments.
         :return: The serialized value
         """
         return value
@@ -500,7 +500,9 @@ class Nested(Field):
             name = fields.Str()
             # Use lambda functions when you need two-way nesting or self-nesting
             parent = fields.Nested(lambda: ParentSchema(only=("id",)), dump_only=True)
-            siblings = fields.List(fields.Nested(lambda: ChildSchema(only=("id", "name"))))
+            siblings = fields.List(
+                fields.Nested(lambda: ChildSchema(only=("id", "name")))
+            )
 
 
         class ParentSchema(Schema):
@@ -710,9 +712,9 @@ class Pluck(Nested):
         loaded = AlbumSchema().load(in_data)  # => {'artist': {'id': 42}}
         dumped = AlbumSchema().dump(loaded)  # => {'artist': 42}
 
-    :param Schema nested: The Schema class or class name (string)
+    :param nested: The Schema class or class name (string)
         to nest, or ``"self"`` to nest the `Schema <marshmallow.Schema>` within itself.
-    :param str field_name: The key to pluck a value from.
+    :param field_name: The key to pluck a value from.
     :param kwargs: The same keyword arguments that :class:`Nested` receives.
     """
 
@@ -720,9 +722,14 @@ class Pluck(Nested):
         self,
         nested: Schema | SchemaMeta | str | typing.Callable[[], Schema],
         field_name: str,
+        *,
+        many: bool = False,
+        unknown: str | None = None,
         **kwargs,
     ):
-        super().__init__(nested, only=(field_name,), **kwargs)
+        super().__init__(
+            nested, only=(field_name,), many=many, unknown=unknown, **kwargs
+        )
         self.field_name = field_name
 
     @property
@@ -832,11 +839,15 @@ class Tuple(Field):
     #: Default error messages.
     default_error_messages = {"invalid": "Not a valid tuple."}
 
-    def __init__(self, tuple_fields: typing.Iterable[Field], *args, **kwargs):
-        super().__init__(*args, **kwargs)
+    def __init__(
+        self,
+        tuple_fields: typing.Iterable[Field] | typing.Iterable[type[Field]],
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
         if not utils.is_collection(tuple_fields):
             raise ValueError(
-                "tuple_fields must be an iterable of Field classes or " "instances."
+                "tuple_fields must be an iterable of Field classes or instances."
             )
 
         try:
@@ -856,9 +867,9 @@ class Tuple(Field):
         super()._bind_to_schema(field_name, schema)
         new_tuple_fields = []
         for field in self.tuple_fields:
-            field = copy.deepcopy(field)
-            field._bind_to_schema(field_name, self)
-            new_tuple_fields.append(field)
+            new_field = copy.deepcopy(field)
+            new_field._bind_to_schema(field_name, self)
+            new_tuple_fields.append(new_field)
 
         self.tuple_fields = new_tuple_fields
 
@@ -948,8 +959,12 @@ _NumType = typing.TypeVar("_NumType")
 class Number(Field, typing.Generic[_NumType]):
     """Base class for number fields.
 
-    :param bool as_string: If `True`, format the serialized value as a string.
+    :param as_string: If `True`, format the serialized value as a string.
     :param kwargs: The same keyword arguments that :class:`Field` receives.
+
+    .. versionchanged:: 3.24.0
+        `Number <marshmallow.fields.Number>` should no longer be used as a field within a `Schema <marshmallow.Schema>`.
+        Use `Integer <marshmallow.fields.Integer>`, `Float <marshmallow.fields.Float>`, or `Decimal <marshmallow.fields.Decimal>` instead.
     """
 
     num_type: type = float
@@ -1027,9 +1042,9 @@ class Integer(Number[int]):
 class Float(Number[float]):
     """A double as an IEEE-754 double precision string.
 
-    :param bool allow_nan: If `True`, `NaN`, `Infinity` and `-Infinity` are allowed,
+    :param allow_nan: If `True`, `NaN`, `Infinity` and `-Infinity` are allowed,
         even though they are illegal according to the JSON specification.
-    :param bool as_string: If `True`, format the value as a string.
+    :param as_string: If `True`, format the value as a string.
     :param kwargs: The same keyword arguments that :class:`Number` receives.
     """
 
@@ -1196,8 +1211,8 @@ class Boolean(Field):
     def __init__(
         self,
         *,
-        truthy: set | None = None,
-        falsy: set | None = None,
+        truthy: typing.Iterable | None = None,
+        falsy: typing.Iterable | None = None,
         **kwargs,
     ):
         super().__init__(**kwargs)
@@ -1283,7 +1298,7 @@ class DateTime(Field):
         "format": '"{input}" cannot be formatted as a {obj_type}.',
     }
 
-    def __init__(self, format: str | None = None, **kwargs) -> None:
+    def __init__(self, format: str | None = None, **kwargs) -> None:  # noqa: A002
         super().__init__(**kwargs)
         # Allow this to be None. It may be set later in the ``_serialize``
         # or ``_deserialize`` methods. This allows a Schema to dynamically set the
@@ -1341,7 +1356,7 @@ class NaiveDateTime(DateTime):
 
     def __init__(
         self,
-        format: str | None = None,
+        format: str | None = None,  # noqa: A002
         *,
         timezone: dt.timezone | None = None,
         **kwargs,
@@ -1378,7 +1393,7 @@ class AwareDateTime(DateTime):
 
     def __init__(
         self,
-        format: str | None = None,
+        format: str | None = None,  # noqa: A002
         *,
         default_timezone: dt.tzinfo | None = None,
         **kwargs,
@@ -1537,7 +1552,7 @@ class TimeDelta(Field):
             delta = utils.timedelta_to_microseconds(value)
             unit = utils.timedelta_to_microseconds(base_unit)
             return delta // unit
-        assert self.serialization_type is float
+        assert self.serialization_type is float  # noqa: S101
         return value.total_seconds() / base_unit.total_seconds()
 
     def _deserialize(self, value, attr, data, **kwargs):
@@ -1555,7 +1570,7 @@ class TimeDelta(Field):
 
 
 class Mapping(Field):
-    """An abstract class for objects with key-value pairs.
+    """An abstract class for objects with key-value pairs. This class should not be used within schemas.
 
     :param keys: A field class or instance for dict keys.
     :param values: A field class or instance for dict values.
@@ -1566,6 +1581,9 @@ class Mapping(Field):
         `keys` and `values` arguments to prevent content validation.
 
     .. versionadded:: 3.0.0rc4
+    .. versionchanged:: 3.24.0
+        `Mapping <marshmallow.fields.Mapping>` should no longer be used as a field within a `Schema <marshmallow.Schema>`.
+        Use `Dict <marshmallow.fields.Dict>` instead.
     """
 
     mapping_type = dict
@@ -1629,16 +1647,15 @@ class Mapping(Field):
         if not self.value_field and not self.key_field:
             return self.mapping_type(value)
 
-        #  Serialize keys
+        # Serialize keys
         if self.key_field is None:
-            keys = {k: k for k in value.keys()}
+            keys = {k: k for k in value}
         else:
             keys = {
-                k: self.key_field._serialize(k, None, None, **kwargs)
-                for k in value.keys()
+                k: self.key_field._serialize(k, None, None, **kwargs) for k in value
             }
 
-        #  Serialize values
+        # Serialize values
         result = self.mapping_type()
         if self.value_field is None:
             for k, v in value.items():
@@ -1658,18 +1675,18 @@ class Mapping(Field):
 
         errors = collections.defaultdict(dict)
 
-        #  Deserialize keys
+        # Deserialize keys
         if self.key_field is None:
-            keys = {k: k for k in value.keys()}
+            keys = {k: k for k in value}
         else:
             keys = {}
-            for key in value.keys():
+            for key in value:
                 try:
                     keys[key] = self.key_field.deserialize(key, **kwargs)
                 except ValidationError as error:
                     errors[key]["key"] = error.messages
 
-        #  Deserialize values
+        # Deserialize values
         result = self.mapping_type()
         if self.value_field is None:
             for k, v in value.items():
@@ -1769,7 +1786,7 @@ class Email(String):
 class IP(Field):
     """A IP address field.
 
-    :param bool exploded: If `True`, serialize ipv6 address in long form, ie. with groups
+    :param exploded: If `True`, serialize ipv6 address in long form, ie. with groups
         consisting entirely of zeros included.
 
     .. versionadded:: 3.8.0
@@ -1835,7 +1852,7 @@ class IPInterface(Field):
 
     see https://python.readthedocs.io/en/latest/library/ipaddress.html#interface-objects
 
-    :param bool exploded: If `True`, serialize ipv6 interface in long form, ie. with groups
+    :param exploded: If `True`, serialize ipv6 interface in long form, ie. with groups
         consisting entirely of zeros included.
     """
 
@@ -1886,8 +1903,8 @@ class IPv6Interface(IPInterface):
 class Enum(Field):
     """An Enum field (de)serializing enum members by symbol (name) or by value.
 
-    :param enum Enum: Enum class
-    :param boolean|Schema|Field by_value: Whether to (de)serialize by value or by name,
+    :param enum: Enum class
+    :param by_value: Whether to (de)serialize by value or by name,
         or Field class or instance to use to (de)serialize by value. Defaults to False.
 
     If `by_value` is `False` (default), enum members are (de)serialized by symbol (name).
@@ -1959,10 +1976,10 @@ class Enum(Field):
 class Method(Field):
     """A field that takes the value returned by a `Schema <marshmallow.Schema>` method.
 
-    :param str serialize: The name of the Schema method from which
+    :param serialize: The name of the Schema method from which
         to retrieve the value. The method must take an argument ``obj``
         (in addition to self) that is the object to be serialized.
-    :param str deserialize: Optional name of the Schema method for deserializing
+    :param deserialize: Optional name of the Schema method for deserializing
         a value The method must take a single argument ``value``, which is the
         value to deserialize.
 

marshmallow/orderedset.py

@@ -45,7 +45,7 @@ class OrderedSet(MutableSet):
 
     def discard(self, key):
         if key in self.map:
-            key, prev, next = self.map.pop(key)
+            key, prev, next = self.map.pop(key)  # noqa: A001
             prev[2] = next
             next[1] = prev