marshmallow 3.23.2__py3-none-any.whl → 3.24.0__py3-none-any.whl

marshmallow/base.py

@@ -16,10 +16,6 @@ from abc import ABC, abstractmethod
 class FieldABC(ABC):
     """Abstract base class from which all Field classes inherit."""
 
-    parent = None
-    name = None
-    root = None
-
     @abstractmethod
     def serialize(self, attr, obj, accessor=None):
         pass
@@ -35,31 +31,3 @@ class FieldABC(ABC):
     @abstractmethod
     def _deserialize(self, value, attr, data, **kwargs):
         pass
-
-
-class SchemaABC(ABC):
-    """Abstract base class from which all Schemas inherit."""
-
-    @abstractmethod
-    def dump(self, obj, *, many: bool | None = None):
-        pass
-
-    @abstractmethod
-    def dumps(self, obj, *, many: bool | None = None):
-        pass
-
-    @abstractmethod
-    def load(self, data, *, many: bool | None = None, partial=None, unknown=None):
-        pass
-
-    @abstractmethod
-    def loads(
-        self,
-        json_data,
-        *,
-        many: bool | None = None,
-        partial=None,
-        unknown=None,
-        **kwargs,
-    ):
-        pass

marshmallow/class_registry.py

@@ -69,6 +69,16 @@ def register(classname: str, cls: SchemaType) -> None:
     return None
 
 
+@typing.overload
+def get_class(classname: str, all: typing.Literal[False]) -> SchemaType: ...
+
+
+@typing.overload
+def get_class(
+    classname: str, all: typing.Literal[True]
+) -> list[SchemaType] | SchemaType: ...
+
+
 def get_class(classname: str, all: bool = False) -> list[SchemaType] | SchemaType:
     """Retrieve a class from the registry.
 

marshmallow/fields.py

@@ -1,5 +1,3 @@
-"""Field classes for various types of data."""
-
 from __future__ import annotations
 
 import collections
@@ -16,7 +14,7 @@ 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, SchemaABC
+from marshmallow.base import FieldABC
 from marshmallow.exceptions import (
     FieldInstanceResolutionError,
     StringNotCollectionError,
@@ -31,10 +29,13 @@ from marshmallow.utils import (
     missing as missing_,
 )
 from marshmallow.validate import And, Length
-from marshmallow.warnings import RemovedInMarshmallow4Warning
+from marshmallow.warnings import (
+    ChangedInMarshmallow4Warning,
+    RemovedInMarshmallow4Warning,
+)
 
 if typing.TYPE_CHECKING:
-    from marshmallow.schema import SchemaMeta
+    from marshmallow.schema import Schema, SchemaMeta
 
 
 __all__ = [
@@ -77,14 +78,11 @@ __all__ = [
     "Pluck",
 ]
 
-_T = typing.TypeVar("_T")
-
 
 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.
-    On error, the name of the field will be returned.
 
     :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
@@ -108,8 +106,9 @@ class Field(FieldABC):
     :param required: Raise a :exc:`ValidationError` if the field value
         is not supplied during deserialization.
     :param allow_none: Set this to `True` if `None` should be considered a valid value during
-        validation/deserialization. If ``load_default=None`` and ``allow_none`` is unset,
-        will default to ``True``. Otherwise, the default is ``False``.
+        validation/deserialization. If set to `False` (the default), `None` is considered invalid input.
+        If ``load_default`` is explicitly set to `None` and ``allow_none`` is unset,
+        `allow_none` is implicitly set to ``True``.
     :param load_only: If `True` skip this field during serialization, otherwise
         its value will be present in the serialized data.
     :param dump_only: If `True` skip this field during deserialization, otherwise
@@ -118,28 +117,12 @@ class Field(FieldABC):
     :param dict error_messages: Overrides for `Field.default_error_messages`.
     :param metadata: Extra information to be stored as field metadata.
 
-    .. versionchanged:: 2.0.0
-        Removed `error` parameter. Use ``error_messages`` instead.
-
-    .. versionchanged:: 2.0.0
-        Added `allow_none` parameter, which makes validation/deserialization of `None`
-        consistent across fields.
-
-    .. versionchanged:: 2.0.0
-        Added `load_only` and `dump_only` parameters, which allow field skipping
-        during the (de)serialization process.
-
-    .. versionchanged:: 2.0.0
-        Added `missing` parameter, which indicates the value for a field if the field
-        is not found during deserialization.
-
-    .. versionchanged:: 2.0.0
-        ``default`` value is only used if explicitly set. Otherwise, missing values
-        inputs are excluded from serialized output.
-
     .. versionchanged:: 3.0.0b8
         Add ``data_key`` parameter for the specifying the key in the input and
         output data. This parameter replaced both ``load_from`` and ``dump_to``.
+
+    .. versionchanged:: 3.13.0
+        Replace ``missing`` and ``default`` parameters with ``load_default`` and ``dump_default``.
     """
 
     # Some fields, such as Method fields and Function fields, are not expected
@@ -150,12 +133,22 @@ class Field(FieldABC):
     #: Default error messages for various kinds of errors. The keys in this dictionary
     #: are passed to `Field.make_error`. The values are error messages passed to
     #: :exc:`marshmallow.exceptions.ValidationError`.
-    default_error_messages = {
+    default_error_messages: dict[str, str] = {
         "required": "Missing data for required field.",
         "null": "Field may not be null.",
         "validator_failed": "Invalid value.",
     }
 
+    def __new__(cls, *args, **kwargs):
+        if cls is Field:
+            warnings.warn(
+                "`Field` should not be instantiated. Use `fields.Raw` or  "
+                "another field subclass instead.",
+                ChangedInMarshmallow4Warning,
+                stacklevel=2,
+            )
+        return super().__new__(cls)
+
     def __init__(
         self,
         *,
@@ -236,12 +229,16 @@ class Field(FieldABC):
             )
 
         # Collect default error message from self and parent classes
-        messages = {}  # type: dict[str, str]
+        messages: dict[str, str] = {}
         for cls in reversed(self.__class__.__mro__):
             messages.update(getattr(cls, "default_error_messages", {}))
         messages.update(error_messages or {})
         self.error_messages = messages
 
+        self.parent: Field | Schema | None = None
+        self.name: str | None = None
+        self.root: Schema | None = None
+
     def __repr__(self) -> str:
         return (
             f"<fields.{self.__class__.__name__}(dump_default={self.dump_default!r}, "
@@ -255,7 +252,15 @@ class Field(FieldABC):
     def __deepcopy__(self, memo):
         return copy.copy(self)
 
-    def get_value(self, obj, attr, accessor=None, default=missing_):
+    def get_value(
+        self,
+        obj: typing.Any,
+        attr: str,
+        accessor: (
+            typing.Callable[[typing.Any, str, typing.Any], typing.Any] | None
+        ) = None,
+        default: typing.Any = missing_,
+    ):
         """Return the value for a given key from an object.
 
         :param object obj: The object to get the value from.
@@ -267,14 +272,14 @@ class Field(FieldABC):
         check_key = attr if self.attribute is None else self.attribute
         return accessor_func(obj, check_key, default)
 
-    def _validate(self, value):
+    def _validate(self, value: typing.Any):
         """Perform validation on ``value``. Raise a :exc:`ValidationError` if validation
         does not succeed.
         """
         self._validate_all(value)
 
     @property
-    def _validate_all(self):
+    def _validate_all(self) -> typing.Callable[[typing.Any], None]:
         return And(*self.validators, error=self.error_messages["validator_failed"])
 
     def make_error(self, key: str, **kwargs) -> ValidationError:
@@ -308,7 +313,7 @@ class Field(FieldABC):
         )
         raise self.make_error(key=key, **kwargs)
 
-    def _validate_missing(self, value):
+    def _validate_missing(self, value: typing.Any) -> None:
         """Validate missing values. Raise a :exc:`ValidationError` if
         `value` should be considered missing.
         """
@@ -375,7 +380,7 @@ class Field(FieldABC):
 
     # Methods for concrete classes to override.
 
-    def _bind_to_schema(self, field_name, schema):
+    def _bind_to_schema(self, field_name: str, schema: Schema | Field) -> None:
         """Update field with values from its parent schema. Called by
         :meth:`Schema._bind_field <marshmallow.Schema._bind_field>`.
 
@@ -390,7 +395,7 @@ class Field(FieldABC):
 
     def _serialize(
         self, value: typing.Any, attr: str | None, obj: typing.Any, **kwargs
-    ):
+    ) -> typing.Any:
         """Serializes ``value`` to a basic Python datatype. Noop by default.
         Concrete :class:`Field` classes should implement this method.
 
@@ -416,7 +421,7 @@ class Field(FieldABC):
         attr: str | None,
         data: typing.Mapping[str, typing.Any] | None,
         **kwargs,
-    ):
+    ) -> typing.Any:
         """Deserialize value. Concrete :class:`Field` classes should implement this method.
 
         :param value: The value to be deserialized.
@@ -426,9 +431,6 @@ class Field(FieldABC):
         :raise ValidationError: In case of formatting or validation failure.
         :return: The deserialized value.
 
-        .. versionchanged:: 2.0.0
-            Added ``attr`` and ``data`` parameters.
-
         .. versionchanged:: 3.0.0
             Added ``**kwargs`` to signature.
         """
@@ -437,9 +439,11 @@ class Field(FieldABC):
     # Properties
 
     @property
-    def context(self):
+    def context(self) -> dict | None:
         """The context dictionary for the parent :class:`Schema`."""
-        return self.parent.context
+        if self.parent:
+            return self.parent.context
+        return None
 
     # the default and missing properties are provided for compatibility and
     # emit warnings when they are accessed and set
@@ -540,13 +544,11 @@ class Nested(Field):
     def __init__(
         self,
         nested: (
-            SchemaABC
+            Schema
             | SchemaMeta
             | str
-            | dict[str, Field | type[Field]]
-            | typing.Callable[
-                [], SchemaABC | SchemaMeta | dict[str, Field | type[Field]]
-            ]
+            | dict[str, Field]
+            | typing.Callable[[], Schema | SchemaMeta | dict[str, Field]]
         ),
         *,
         dump_default: typing.Any = missing_,
@@ -576,11 +578,11 @@ class Nested(Field):
         self.exclude = exclude
         self.many = many
         self.unknown = unknown
-        self._schema = None  # Cached Schema instance
+        self._schema: Schema | None = None  # Cached Schema instance
         super().__init__(default=default, dump_default=dump_default, **kwargs)
 
     @property
-    def schema(self):
+    def schema(self) -> Schema:
         """The nested Schema object.
 
         .. versionchanged:: 1.0.0
@@ -592,18 +594,18 @@ class Nested(Field):
             if callable(self.nested) and not isinstance(self.nested, type):
                 nested = self.nested()
             else:
-                nested = self.nested
-            if isinstance(nested, dict):
-                # defer the import of `marshmallow.schema` to avoid circular imports
-                from marshmallow.schema import Schema
+                nested = typing.cast("Schema", self.nested)
+            # defer the import of `marshmallow.schema` to avoid circular imports
+            from marshmallow.schema import Schema
 
+            if isinstance(nested, dict):
                 nested = Schema.from_dict(nested)
 
-            if isinstance(nested, SchemaABC):
+            if isinstance(nested, Schema):
                 self._schema = copy.copy(nested)
                 self._schema.context.update(context)
                 # Respect only and exclude passed from parent and re-initialize fields
-                set_class = self._schema.set_class
+                set_class = typing.cast(type[set], self._schema.set_class)
                 if self.only is not None:
                     if self._schema.only is not None:
                         original = self._schema.only
@@ -615,17 +617,17 @@ class Nested(Field):
                     self._schema.exclude = set_class(self.exclude) | set_class(original)
                 self._schema._init_fields()
             else:
-                if isinstance(nested, type) and issubclass(nested, SchemaABC):
-                    schema_class = nested
+                if isinstance(nested, type) and issubclass(nested, Schema):
+                    schema_class: type[Schema] = nested
                 elif not isinstance(nested, (str, bytes)):
                     raise ValueError(
                         "`Nested` fields must be passed a "
                         f"`Schema`, not {nested.__class__}."
                     )
                 elif nested == "self":
-                    schema_class = self.root.__class__
+                    schema_class = typing.cast(Schema, self.root).__class__
                 else:
-                    schema_class = class_registry.get_class(nested)
+                    schema_class = class_registry.get_class(nested, all=False)
                 self._schema = schema_class(
                     many=self.many,
                     only=self.only,
@@ -653,12 +655,14 @@ class Nested(Field):
         many = schema.many or self.many
         return schema.dump(nested_obj, many=many)
 
-    def _test_collection(self, value):
+    def _test_collection(self, value: typing.Any) -> None:
         many = self.schema.many or self.many
         if many and not utils.is_collection(value):
             raise self.make_error("type", input=value, type=value.__class__.__name__)
 
-    def _load(self, value, data, partial=None):
+    def _load(
+        self, value: typing.Any, partial: bool | types.StrSequenceOrSet | None = None
+    ):
         try:
             valid_data = self.schema.load(value, unknown=self.unknown, partial=partial)
         except ValidationError as error:
@@ -667,7 +671,14 @@ class Nested(Field):
             ) from error
         return valid_data
 
-    def _deserialize(self, value, attr, data, partial=None, **kwargs):
+    def _deserialize(
+        self,
+        value: typing.Any,
+        attr: str | None,
+        data: typing.Mapping[str, typing.Any] | None = None,
+        partial: bool | types.StrSequenceOrSet | None = None,
+        **kwargs,
+    ) -> typing.Any:
         """Same as :meth:`Field._deserialize` with additional ``partial`` argument.
 
         :param bool|tuple partial: For nested schemas, the ``partial``
@@ -677,7 +688,7 @@ class Nested(Field):
             Add ``partial`` parameter.
         """
         self._test_collection(value)
-        return self._load(value, data, partial=partial)
+        return self._load(value, partial=partial)
 
 
 class Pluck(Nested):
@@ -709,7 +720,7 @@ class Pluck(Nested):
 
     def __init__(
         self,
-        nested: SchemaABC | SchemaMeta | str | typing.Callable[[], SchemaABC],
+        nested: Schema | SchemaMeta | str | typing.Callable[[], Schema],
         field_name: str,
         **kwargs,
     ):
@@ -717,7 +728,7 @@ class Pluck(Nested):
         self.field_name = field_name
 
     @property
-    def _field_data_key(self):
+    def _field_data_key(self) -> str:
         only_field = self.schema.fields[self.field_name]
         return only_field.data_key or self.field_name
 
@@ -735,7 +746,7 @@ class Pluck(Nested):
             value = [{self._field_data_key: v} for v in value]
         else:
             value = {self._field_data_key: value}
-        return self._load(value, data, partial=partial)
+        return self._load(value, partial=partial)
 
 
 class List(Field):
@@ -749,10 +760,6 @@ class List(Field):
     :param cls_or_instance: A field class or instance.
     :param kwargs: The same keyword arguments that :class:`Field` receives.
 
-    .. versionchanged:: 2.0.0
-        The ``allow_none`` parameter now applies to deserialization and
-        has the same semantics as the other fields.
-
     .. versionchanged:: 3.0.0rc9
         Does not serialize scalar values to single-item lists.
     """
@@ -773,7 +780,7 @@ class List(Field):
             self.only = self.inner.only
             self.exclude = self.inner.exclude
 
-    def _bind_to_schema(self, field_name, schema):
+    def _bind_to_schema(self, field_name: str, schema: Schema | Field) -> None:
         super()._bind_to_schema(field_name, schema)
         self.inner = copy.deepcopy(self.inner)
         self.inner._bind_to_schema(field_name, self)
@@ -817,7 +824,7 @@ class Tuple(Field):
         `typing.NamedTuple`, using a Schema within a Nested field for them is
         more appropriate than using a `Tuple` field.
 
-    :param Iterable[Field] tuple_fields: An iterable of field classes or
+    :param tuple_fields: An iterable of field classes or
         instances.
     :param kwargs: The same keyword arguments that :class:`Field` receives.
 
@@ -827,7 +834,7 @@ class Tuple(Field):
     #: Default error messages.
     default_error_messages = {"invalid": "Not a valid tuple."}
 
-    def __init__(self, tuple_fields, *args, **kwargs):
+    def __init__(self, tuple_fields: typing.Iterable[Field], *args, **kwargs):
         super().__init__(*args, **kwargs)
         if not utils.is_collection(tuple_fields):
             raise ValueError(
@@ -847,7 +854,7 @@ class Tuple(Field):
 
         self.validate_length = Length(equal=len(self.tuple_fields))
 
-    def _bind_to_schema(self, field_name, schema):
+    def _bind_to_schema(self, field_name: str, schema: Schema | Field) -> None:
         super()._bind_to_schema(field_name, schema)
         new_tuple_fields = []
         for field in self.tuple_fields:
@@ -937,14 +944,17 @@ class UUID(String):
         return self._validated(value)
 
 
-class Number(Field):
+_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 kwargs: The same keyword arguments that :class:`Field` receives.
     """
 
-    num_type = float  # type: typing.Type
+    num_type: type = float
 
     #: Default error messages.
     default_error_messages = {
@@ -952,18 +962,25 @@ class Number(Field):
         "too_large": "Number too large.",
     }
 
+    def __new__(cls, *args, **kwargs):
+        if cls is Number:
+            warnings.warn(
+                "`Number` field should not be instantiated. Use `Integer`, `Float`, or `Decimal` instead.",
+                ChangedInMarshmallow4Warning,
+                stacklevel=2,
+            )
+        return super().__new__(cls)
+
     def __init__(self, *, as_string: bool = False, **kwargs):
         self.as_string = as_string
         super().__init__(**kwargs)
 
-    def _format_num(self, value) -> typing.Any:
+    def _format_num(self, value) -> _NumType:
         """Return the number value for value, given this field's `num_type`."""
         return self.num_type(value)
 
-    def _validated(self, value) -> _T | None:
+    def _validated(self, value: typing.Any) -> _NumType:
         """Format the value or raise a :exc:`ValidationError` if an error occurs."""
-        if value is None:
-            return None
         # (value is True or value is False) is ~5x faster than isinstance(value, bool)
         if value is True or value is False:
             raise self.make_error("invalid", input=value)
@@ -974,21 +991,21 @@ class Number(Field):
         except OverflowError as error:
             raise self.make_error("too_large", input=value) from error
 
-    def _to_string(self, value) -> str:
+    def _to_string(self, value: _NumType) -> str:
         return str(value)
 
-    def _serialize(self, value, attr, obj, **kwargs) -> str | _T | None:
+    def _serialize(self, value, attr, obj, **kwargs) -> str | _NumType | None:
         """Return a string if `self.as_string=True`, otherwise return this field's `num_type`."""
         if value is None:
             return None
-        ret = self._format_num(value)  # type: _T
+        ret: _NumType = self._format_num(value)
         return self._to_string(ret) if self.as_string else ret
 
-    def _deserialize(self, value, attr, data, **kwargs) -> _T | None:
+    def _deserialize(self, value, attr, data, **kwargs) -> _NumType | None:
         return self._validated(value)
 
 
-class Integer(Number):
+class Integer(Number[int]):
     """An integer field.
 
     :param strict: If `True`, only integer types are valid.
@@ -1006,13 +1023,13 @@ class Integer(Number):
         super().__init__(**kwargs)
 
     # override Number
-    def _validated(self, value):
+    def _validated(self, value: typing.Any) -> int:
         if self.strict and not isinstance(value, numbers.Integral):
             raise self.make_error("invalid", input=value)
         return super()._validated(value)
 
 
-class Float(Number):
+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,
@@ -1032,7 +1049,7 @@ class Float(Number):
         self.allow_nan = allow_nan
         super().__init__(as_string=as_string, **kwargs)
 
-    def _validated(self, value):
+    def _validated(self, value: typing.Any) -> float:
         num = super()._validated(value)
         if self.allow_nan is False:
             if math.isnan(num) or num == float("inf") or num == float("-inf"):
@@ -1040,7 +1057,7 @@ class Float(Number):
         return num
 
 
-class Decimal(Number):
+class Decimal(Number[decimal.Decimal]):
     """A field that (de)serializes to the Python ``decimal.Decimal`` type.
     It's safe to use when dealing with money values, percentages, ratios
     or other numbers where precision is critical.
@@ -1111,7 +1128,7 @@ class Decimal(Number):
         return num
 
     # override Number
-    def _validated(self, value):
+    def _validated(self, value: typing.Any) -> decimal.Decimal:
         try:
             num = super()._validated(value)
         except decimal.InvalidOperation as error:
@@ -1121,7 +1138,7 @@ class Decimal(Number):
         return num
 
     # override Number
-    def _to_string(self, value):
+    def _to_string(self, value: decimal.Decimal) -> str:
         return format(value, "f")
 
 
@@ -1195,7 +1212,9 @@ class Boolean(Field):
         if falsy is not None:
             self.falsy = set(falsy)
 
-    def _serialize(self, value, attr, obj, **kwargs):
+    def _serialize(
+        self, value: typing.Any, attr: str | None, obj: typing.Any, **kwargs
+    ):
         if value is None:
             return None
 
@@ -1238,23 +1257,23 @@ class DateTime(Field):
         Add timestamp as a format.
     """
 
-    SERIALIZATION_FUNCS = {
+    SERIALIZATION_FUNCS: dict[str, typing.Callable[[typing.Any], str | float]] = {
         "iso": utils.isoformat,
         "iso8601": utils.isoformat,
         "rfc": utils.rfcformat,
         "rfc822": utils.rfcformat,
         "timestamp": utils.timestamp,
         "timestamp_ms": utils.timestamp_ms,
-    }  # type: dict[str, typing.Callable[[typing.Any], str | float]]
+    }
 
-    DESERIALIZATION_FUNCS = {
+    DESERIALIZATION_FUNCS: dict[str, typing.Callable[[str], typing.Any]] = {
         "iso": utils.from_iso_datetime,
         "iso8601": utils.from_iso_datetime,
         "rfc": utils.from_rfc,
         "rfc822": utils.from_rfc,
         "timestamp": utils.from_timestamp,
         "timestamp_ms": utils.from_timestamp_ms,
-    }  # type: dict[str, typing.Callable[[str], typing.Any]]
+    }
 
     DEFAULT_FORMAT = "iso"
 
@@ -1464,9 +1483,6 @@ class TimeDelta(Field):
     will always be truncated to microseconds.
     For example, `1.12345` interpreted as microseconds will result in `timedelta(microseconds=1)`.
 
-    .. versionchanged:: 2.0.0
-        Always serializes to an integer value to avoid rounding errors.
-        Add `precision` parameter.
     .. versionchanged:: 3.17.0
         Allow (de)serialization to `float` through use of a new `serialization_type` parameter.
         `int` is the default to retain previous behaviour.
@@ -1562,6 +1578,15 @@ class Mapping(Field):
     #: Default error messages.
     default_error_messages = {"invalid": "Not a valid mapping type."}
 
+    def __new__(cls, *args, **kwargs):
+        if cls is Mapping:
+            warnings.warn(
+                "`Mapping` field should not be instantiated. Use `Dict` instead.",
+                ChangedInMarshmallow4Warning,
+                stacklevel=2,
+            )
+        return super().__new__(cls)
+
     def __init__(
         self,
         keys: Field | type[Field] | None = None,
@@ -1760,7 +1785,7 @@ class IP(Field):
 
     default_error_messages = {"invalid_ip": "Not a valid IP address."}
 
-    DESERIALIZATION_CLASS = None  # type: typing.Optional[typing.Type]
+    DESERIALIZATION_CLASS: type | None = None
 
     def __init__(self, *args, exploded=False, **kwargs):
         super().__init__(*args, **kwargs)
@@ -1824,7 +1849,7 @@ class IPInterface(Field):
 
     default_error_messages = {"invalid_ip_interface": "Not a valid IP interface."}
 
-    DESERIALIZATION_CLASS = None  # type: typing.Optional[typing.Type]
+    DESERIALIZATION_CLASS: type | None = None
 
     def __init__(self, *args, exploded: bool = False, **kwargs):
         super().__init__(*args, **kwargs)
@@ -1874,7 +1899,7 @@ class Enum(Field):
         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).
-    If it is `True`, they are (de)serialized by value using :class:`Field`.
+    If it is `True`, they are (de)serialized by value using :class:`Raw`.
     If it is a field instance or class, they are (de)serialized by value using this field.
 
     .. versionadded:: 3.18.0
@@ -1904,7 +1929,7 @@ class Enum(Field):
         # Serialization by value
         else:
             if by_value is True:
-                self.field = Field()
+                self.field = Raw()
             else:
                 try:
                     self.field = resolve_field_instance(by_value)
@@ -1949,9 +1974,6 @@ class Method(Field):
         a value The method must take a single argument ``value``, which is the
         value to deserialize.
 
-    .. versionchanged:: 2.0.0
-        Removed optional ``context`` parameter on methods. Use ``self.context`` instead.
-
     .. versionchanged:: 2.3.0
         Deprecated ``method_name`` parameter in favor of ``serialize`` and allow
         ``serialize`` to not be passed at all.
@@ -2070,8 +2092,6 @@ class Constant(Field):
     ``dump_only=True`` or ``load_only=True`` respectively.
 
     :param constant: The constant to return for the field attribute.
-
-    .. versionadded:: 2.0.0
     """
 
     _CHECK_ATTRIBUTE = False

marshmallow/schema.py

@@ -154,7 +154,7 @@ class SchemaMeta(ABCMeta):
         """
         mro = inspect.getmro(cls)
 
-        hooks = defaultdict(list)  # type: dict[str, list[tuple[str, bool, dict]]]
+        hooks: dict[str, list[tuple[str, bool, dict]]] = defaultdict(list)
 
         for attr_name in dir(cls):
             # Need to look up the actual descriptor, not whatever might be
@@ -174,7 +174,9 @@ class SchemaMeta(ABCMeta):
                 continue
 
             try:
-                hook_config = attr.__marshmallow_hook__  # type: dict[str, list[tuple[bool, dict]]]
+                hook_config: dict[str, list[tuple[bool, dict]]] = (
+                    attr.__marshmallow_hook__
+                )
             except AttributeError:
                 pass
             else:
@@ -229,7 +231,7 @@ class SchemaOpts:
         self.many = getattr(meta, "many", False)
 
 
-class Schema(base.SchemaABC, metaclass=SchemaMeta):
+class Schema(metaclass=SchemaMeta):
     """Base schema class with which to define custom schemas.
 
     Example usage:
@@ -280,16 +282,9 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
 
     .. versionchanged:: 3.0.0
         `prefix` parameter removed.
-
-    .. versionchanged:: 2.0.0
-        `__validators__`, `__preprocessors__`, and `__data_handlers__` are removed in favor of
-        `marshmallow.decorators.validates_schema`,
-        `marshmallow.decorators.pre_load` and `marshmallow.decorators.post_dump`.
-        `__accessor__` and `__error_handler__` are deprecated. Implement the
-        `handle_error` and `get_attribute` methods instead.
     """
 
-    TYPE_MAPPING = {
+    TYPE_MAPPING: dict[type, type[ma_fields.Field]] = {
         str: ma_fields.String,
         bytes: ma_fields.String,
         dt.datetime: ma_fields.DateTime,
@@ -304,23 +299,23 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         dt.date: ma_fields.Date,
         dt.timedelta: ma_fields.TimeDelta,
         decimal.Decimal: ma_fields.Decimal,
-    }  # type: dict[type, typing.Type[ma_fields.Field]]
+    }
     #: Overrides for default schema-level error messages
-    error_messages = {}  # type: dict[str, str]
+    error_messages: dict[str, str] = {}
 
-    _default_error_messages = {
+    _default_error_messages: dict[str, str] = {
         "type": "Invalid input type.",
         "unknown": "Unknown field.",
-    }  # type: dict[str, str]
+    }
 
-    OPTIONS_CLASS = SchemaOpts  # type: type
+    OPTIONS_CLASS: type = SchemaOpts
 
     set_class = OrderedSet
 
     # These get set by SchemaMeta
-    opts = None  # type: SchemaOpts
-    _declared_fields = {}  # type: dict[str, ma_fields.Field]
-    _hooks = {}  # type: dict[str, list[tuple[str, bool, dict]]]
+    opts: SchemaOpts
+    _declared_fields: dict[str, ma_fields.Field] = {}
+    _hooks: dict[str, list[tuple[str, bool, dict]]] = {}
 
     class Meta:
         """Options object for a Schema.
@@ -395,12 +390,19 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
             if unknown is None
             else validate_unknown_parameter_value(unknown)
         )
+        if context:
+            warnings.warn(
+                "The `context` parameter is deprecated and will be removed in marshmallow 4.0. "
+                "Use `contextvars.ContextVar` to pass context instead.",
+                RemovedInMarshmallow4Warning,
+                stacklevel=2,
+            )
         self.context = context or {}
         self._normalize_nested_options()
         #: Dictionary mapping field_names -> :class:`Field` objects
-        self.fields = {}  # type: dict[str, ma_fields.Field]
-        self.load_fields = {}  # type: dict[str, ma_fields.Field]
-        self.dump_fields = {}  # type: dict[str, ma_fields.Field]
+        self.fields: dict[str, ma_fields.Field] = {}
+        self.load_fields: dict[str, ma_fields.Field] = {}
+        self.dump_fields: dict[str, ma_fields.Field] = {}
         self._init_fields()
         messages = {}
         messages.update(self._default_error_messages)
@@ -422,7 +424,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
     @classmethod
     def from_dict(
         cls,
-        fields: dict[str, ma_fields.Field | type[ma_fields.Field]],
+        fields: dict[str, ma_fields.Field],
         *,
         name: str = "GeneratedSchema",
     ) -> type[Schema]:
@@ -444,11 +446,10 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
 
         .. versionadded:: 3.0.0
         """
-        attrs = fields.copy()
-        attrs["Meta"] = type(
+        Meta = type(
             "GeneratedMeta", (getattr(cls, "Meta", object),), {"register": False}
         )
-        schema_cls = type(name, (cls,), attrs)
+        schema_cls = type(name, (cls,), {**fields.copy(), "Meta": Meta})
         return schema_cls
 
     ##### Override-able methods #####
@@ -463,8 +464,6 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         :param many: Value of ``many`` on dump or load.
         :param partial: Value of ``partial`` on load.
 
-        .. versionadded:: 2.0.0
-
         .. versionchanged:: 3.0.0rc9
             Receives `many` and `partial` (on deserialization) as keyword arguments.
         """
@@ -473,8 +472,6 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
     def get_attribute(self, obj: typing.Any, attr: str, default: typing.Any):
         """Defines how to pull values from an object to serialize.
 
-        .. versionadded:: 2.0.0
-
         .. versionchanged:: 3.0.0a1
             Changed position of ``obj`` and ``attr``.
         """
@@ -508,9 +505,6 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         :param obj: The object(s) to serialize.
         :param bool many: `True` if ``data`` should be serialized as a collection.
         :return: A dictionary of the serialized data
-
-        .. versionchanged:: 1.0.0
-            Renamed from ``marshal``.
         """
         if many and obj is not None:
             return [self._serialize(d, many=False) for d in obj]
@@ -836,7 +830,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
         :return: Deserialized data
         """
         error_store = ErrorStore()
-        errors = {}  # type: dict[str, list[str]]
+        errors: dict[str, list[str]] = {}
         many = self.many if many is None else bool(many)
         unknown = (
             self.unknown
@@ -853,7 +847,7 @@ class Schema(base.SchemaABC, metaclass=SchemaMeta):
                 )
             except ValidationError as err:
                 errors = err.normalized_messages()
-                result = None  # type: list | dict | None
+                result: list | dict | None = None
         else:
             processed_data = data
         if not errors:

marshmallow/utils.py

@@ -138,7 +138,7 @@ def get_fixed_timezone(offset: int | float | dt.timedelta) -> dt.timezone:
     if isinstance(offset, dt.timedelta):
         offset = offset.total_seconds() // 60
     sign = "-" if offset < 0 else "+"
-    hhmm = "%02d%02d" % divmod(abs(offset), 60)
+    hhmm = "{:02d}{:02d}".format(*divmod(abs(offset), 60))
     name = sign + hhmm
     return dt.timezone(dt.timedelta(minutes=offset), name)
 

marshmallow/validate.py

@@ -4,12 +4,14 @@ from __future__ import annotations
 
 import re
 import typing
+import warnings
 from abc import ABC, abstractmethod
 from itertools import zip_longest
 from operator import attrgetter
 
 from marshmallow import types
 from marshmallow.exceptions import ValidationError
+from marshmallow.warnings import ChangedInMarshmallow4Warning
 
 _T = typing.TypeVar("_T")
 
@@ -22,7 +24,7 @@ class Validator(ABC):
         add a useful `__repr__` implementation for validators.
     """
 
-    error = None  # type: str | None
+    error: str | None = None
 
     def __repr__(self) -> str:
         args = self._repr_args()
@@ -65,7 +67,7 @@ class And(Validator):
 
     def __init__(self, *validators: types.Validator, error: str | None = None):
         self.validators = tuple(validators)
-        self.error = error or self.default_error_message  # type: str
+        self.error: str = error or self.default_error_message
 
     def _repr_args(self) -> str:
         return f"validators={self.validators!r}"
@@ -77,6 +79,12 @@ class And(Validator):
             try:
                 r = validator(value)
                 if not isinstance(validator, Validator) and r is False:
+                    warnings.warn(
+                        "Returning `False` from a validator is deprecated. "
+                        "Raise a `ValidationError` instead.",
+                        ChangedInMarshmallow4Warning,
+                        stacklevel=2,
+                    )
                     raise ValidationError(self.error)
             except ValidationError as err:
                 kwargs.update(err.kwargs)
@@ -191,7 +199,7 @@ class URL(Validator):
             )
         self.relative = relative
         self.absolute = absolute
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
         self.schemes = schemes or self.default_schemes
         self.require_tld = require_tld
 
@@ -250,7 +258,7 @@ class Email(Validator):
     default_message = "Not a valid email address."
 
     def __init__(self, *, error: str | None = None):
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
 
     def _format_error(self, value: str) -> str:
         return self.error.format(input=value)
@@ -436,7 +444,7 @@ class Equal(Validator):
 
     def __init__(self, comparable, *, error: str | None = None):
         self.comparable = comparable
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
 
     def _repr_args(self) -> str:
         return f"comparable={self.comparable!r}"
@@ -477,7 +485,7 @@ class Regexp(Validator):
         self.regex = (
             re.compile(regex, flags) if isinstance(regex, (str, bytes)) else regex
         )
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
 
     def _repr_args(self) -> str:
         return f"regex={self.regex!r}"
@@ -514,7 +522,7 @@ class Predicate(Validator):
 
     def __init__(self, method: str, *, error: str | None = None, **kwargs):
         self.method = method
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
         self.kwargs = kwargs
 
     def _repr_args(self) -> str:
@@ -545,7 +553,7 @@ class NoneOf(Validator):
     def __init__(self, iterable: typing.Iterable, *, error: str | None = None):
         self.iterable = iterable
         self.values_text = ", ".join(str(each) for each in self.iterable)
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
 
     def _repr_args(self) -> str:
         return f"iterable={self.iterable!r}"
@@ -585,7 +593,7 @@ class OneOf(Validator):
         self.choices_text = ", ".join(str(choice) for choice in self.choices)
         self.labels = labels if labels is not None else []
         self.labels_text = ", ".join(str(label) for label in self.labels)
-        self.error = error or self.default_message  # type: str
+        self.error: str = error or self.default_message
 
     def _repr_args(self) -> str:
         return f"choices={self.choices!r}, labels={self.labels!r}"

marshmallow/warnings.py

@@ -1,2 +1,10 @@
-class RemovedInMarshmallow4Warning(DeprecationWarning):
+class Marshmallow4Warning(DeprecationWarning):
+    pass
+
+
+class ChangedInMarshmallow4Warning(Marshmallow4Warning):
+    pass
+
+
+class RemovedInMarshmallow4Warning(Marshmallow4Warning):
     pass

{marshmallow-3.23.2.dist-info → marshmallow-3.24.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: marshmallow
-Version: 3.23.2
+Version: 3.24.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>
@@ -22,7 +22,6 @@ Requires-Dist: pre-commit>=3.5,<5.0 ; extra == "dev"
 Requires-Dist: sphinx==8.1.3 ; extra == "docs"
 Requires-Dist: sphinx-issues==5.0.0 ; 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.14 ; extra == "docs"
 Requires-Dist: pytest ; extra == "tests"
 Requires-Dist: simplejson ; extra == "tests"

marshmallow-3.24.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+marshmallow/__init__.py,sha256=C-zbaQJ9dlJLJxotIqTa5OOaD6ojGNRqW8moGrMsGr8,2387
+marshmallow/base.py,sha256=ty-JhN__qqlJHaFVrFjMJTM5hQH6pG3xeo82Zu0sweY,719
+marshmallow/class_registry.py,sha256=3k485ifxO4ilctvG3ICeuEx8CRuRmw8Ka_3V-Qjgq9o,3020
+marshmallow/decorators.py,sha256=vmQFgBgdV0s1Fw8ySyZyQKvjKBTNf5JB3SCldEIl29o,8385
+marshmallow/error_store.py,sha256=A7AxgLMw9ffSmaxRH4x3wcBWibx-DuGH4LwSDpVn50I,2223
+marshmallow/exceptions.py,sha256=DuARdOcirCdJxmlp16V97hQKAXOokvdW12jXtYOlGyk,2326
+marshmallow/fields.py,sha256=BSqVSDWFWt0T-N477YHYCeGzQHBpiuEtTZPJ5ULPsQ8,74073
+marshmallow/orderedset.py,sha256=C2aAG6w1faIL1phinbAltbe3AUAnF5MN6n7fzESNDhI,2922
+marshmallow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+marshmallow/schema.py,sha256=FIwUiCJfdz9EMNMj9w__UIuTx0Ik_quFL_QqSWuzJ2s,48445
+marshmallow/types.py,sha256=RDS4IfasIehvH2rGWh9e4RTBtsMp-JFFtjApajV22zc,283
+marshmallow/utils.py,sha256=-6jOnkuqFvb0DLeTVVifAPOklD_IdHC4LanhClCO0Hc,11897
+marshmallow/validate.py,sha256=t5-4Qg_XlSQgcCujf_pimKIdZE0QT63jHyQP-miJNK0,24151
+marshmallow/warnings.py,sha256=YHC0kQQBbTKCiA1FuwnbnXqrph7oKuU9BjTV4cxwnzE,192
+marshmallow-3.24.0.dist-info/LICENSE,sha256=kGtdkFHkJhRMsXOtkRZnuOvQWpxYTCwmwTWzKj7RIAE,1064
+marshmallow-3.24.0.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
+marshmallow-3.24.0.dist-info/METADATA,sha256=bXLTvb7NO1z9CmSvghsh8UrrppbbrT2WUu64rRxNShE,7084
+marshmallow-3.24.0.dist-info/RECORD,,

marshmallow-3.23.2.dist-info/RECORD

@@ -1,18 +0,0 @@
-marshmallow/__init__.py,sha256=C-zbaQJ9dlJLJxotIqTa5OOaD6ojGNRqW8moGrMsGr8,2387
-marshmallow/base.py,sha256=jZ68DZxxSCvRg2GTcxQcf2JjTxqEn-xFNrBEMK3CinU,1346
-marshmallow/class_registry.py,sha256=kT_kv9KT0EUclIluLD5734ms9P0e65t5aky8y3lipFI,2804
-marshmallow/decorators.py,sha256=vmQFgBgdV0s1Fw8ySyZyQKvjKBTNf5JB3SCldEIl29o,8385
-marshmallow/error_store.py,sha256=A7AxgLMw9ffSmaxRH4x3wcBWibx-DuGH4LwSDpVn50I,2223
-marshmallow/exceptions.py,sha256=DuARdOcirCdJxmlp16V97hQKAXOokvdW12jXtYOlGyk,2326
-marshmallow/fields.py,sha256=MqrL2FplcXd6ZF5QhfAwawcDzy2NqcFFw2vGSd6pQOc,73253
-marshmallow/orderedset.py,sha256=C2aAG6w1faIL1phinbAltbe3AUAnF5MN6n7fzESNDhI,2922
-marshmallow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-marshmallow/schema.py,sha256=C4BsYkDBQbdgDA6w39oSqVlsDx4NfbkT_XtSIKcqxIo,48812
-marshmallow/types.py,sha256=RDS4IfasIehvH2rGWh9e4RTBtsMp-JFFtjApajV22zc,283
-marshmallow/utils.py,sha256=sWciesZ6tS08uX9Z9fzu2lbuut5eh8TKABU-TwgqSms,11886
-marshmallow/validate.py,sha256=hS7fYC6byDHK9A7A4is0McDMZEzu6GkKke-7unLt2hE,23857
-marshmallow/warnings.py,sha256=vHQu7AluuWqLhvlw5noXtWWbya13zDXY6JMaVSUzmDs,65
-marshmallow-3.23.2.dist-info/LICENSE,sha256=kGtdkFHkJhRMsXOtkRZnuOvQWpxYTCwmwTWzKj7RIAE,1064
-marshmallow-3.23.2.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
-marshmallow-3.23.2.dist-info/METADATA,sha256=TlOpI469OQ6idWY74rjfgWR_xKzZPANdBN5wyB9J6bY,7147
-marshmallow-3.23.2.dist-info/RECORD,,