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

marshmallow/base.py

@@ -4,8 +4,8 @@ These are necessary to avoid circular imports between schema.py and fields.py.
 
 .. warning::
 
-    This module is treated as private API.
-    Users should not need to use this module directly.
+    This module is deprecated. Users should not import from this module.
+    Use `marshmallow.fields.Field` and `marshmallow.schema.Schema` as base classes instead.
 """
 
 from __future__ import annotations
@@ -31,3 +31,31 @@ 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/decorators.py

@@ -100,7 +100,7 @@ def validates_schema(
     """Register a schema-level validator.
 
     By default it receives a single object at a time, transparently handling the ``many``
-    argument passed to the `Schema`'s :func:`~marshmallow.Schema.validate` call.
+    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_original=True``, the original data (before unmarshalling) will be passed as
@@ -132,7 +132,7 @@ def pre_dump(
     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`'s :func:`~marshmallow.Schema.dump` call.
+    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.
 
     .. versionchanged:: 3.0.0
@@ -150,7 +150,7 @@ def post_dump(
     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`'s :func:`~marshmallow.Schema.dump` call.
+    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_original=True``, the original data (before serializing) will be passed as
@@ -169,7 +169,7 @@ def pre_load(
     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`'s :func:`~marshmallow.Schema.load` call.
+    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.
 
     .. versionchanged:: 3.0.0
@@ -188,7 +188,7 @@ def post_load(
     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`'s :func:`~marshmallow.Schema.load` call.
+    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_original=True``, the original data (before deserializing) will be passed as

marshmallow/fields.py

@@ -139,16 +139,6 @@ class Field(FieldABC):
         "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,
         *,
@@ -171,6 +161,13 @@ class Field(FieldABC):
         metadata: typing.Mapping[str, typing.Any] | None = None,
         **additional_metadata,
     ) -> None:
+        if self.__class__ is Field:
+            warnings.warn(
+                "`Field` should not be instantiated. Use `fields.Raw` or  "
+                "another field subclass instead.",
+                ChangedInMarshmallow4Warning,
+                stacklevel=2,
+            )
         # handle deprecated `default` and `missing` parameters
         if default is not missing_:
             warnings.warn(
@@ -361,7 +358,7 @@ class Field(FieldABC):
 
         :param value: The value to deserialize.
         :param attr: The attribute/key in `data` to deserialize.
-        :param data: The raw input data passed to `Schema.load`.
+        :param data: The raw input data passed to `Schema.load <marshmallow.Schema.load>`.
         :param kwargs: Field-specific keyword arguments.
         :raise ValidationError: If an invalid value is passed or if a required value
             is missing.
@@ -382,7 +379,7 @@ class Field(FieldABC):
 
     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>`.
+        `Schema._bind_field <marshmallow.Schema._bind_field>`.
 
         :param str field_name: Field name set in schema.
         :param Schema|Field schema: Parent object.
@@ -426,7 +423,7 @@ class Field(FieldABC):
 
         :param value: The value to be deserialized.
         :param attr: The attribute/key in `data` to be deserialized.
-        :param data: The raw input data passed to the `Schema.load`.
+        :param data: The raw input data passed to the `Schema.load <marshmallow.Schema.load>`.
         :param kwargs: Field-specific keyword arguments.
         :raise ValidationError: In case of formatting or validation failure.
         :return: The deserialized value.
@@ -440,7 +437,7 @@ class Field(FieldABC):
 
     @property
     def context(self) -> dict | None:
-        """The context dictionary for the parent :class:`Schema`."""
+        """The context dictionary for the parent `Schema <marshmallow.Schema>`."""
         if self.parent:
             return self.parent.context
         return None
@@ -527,8 +524,9 @@ class Nested(Field):
         # No
         author = fields.Nested(UserSchema(), only=("id", "name"))
 
-    :param nested: `Schema` instance, class, class name (string), dictionary, or callable that
-        returns a `Schema` or dictionary. Dictionaries are converted with `Schema.from_dict`.
+    :param nested: `Schema <marshmallow.Schema>` instance, class, class name (string), dictionary, or callable that
+        returns a `Schema <marshmallow.Schema>` or dictionary.
+        Dictionaries are converted with `Schema.from_dict <marshmallow.Schema.from_dict>`.
     :param exclude: A list or tuple of fields to exclude.
     :param only: A list or tuple of fields to marshal. If `None`, all fields are marshalled.
         This parameter takes precedence over ``exclude``.
@@ -583,10 +581,10 @@ class Nested(Field):
 
     @property
     def schema(self) -> Schema:
-        """The nested Schema object.
+        """The nested `Schema <marshmallow.Schema>` object.
 
         .. versionchanged:: 1.0.0
-            Renamed from `serializer` to `schema`.
+            Renamed from ``serializer`` to ``schema``.
         """
         if not self._schema:
             # Inherit context from parent.
@@ -681,8 +679,8 @@ class Nested(Field):
     ) -> typing.Any:
         """Same as :meth:`Field._deserialize` with additional ``partial`` argument.
 
-        :param bool|tuple partial: For nested schemas, the ``partial``
-            parameter passed to `Schema.load`.
+        :param partial: For nested schemas, the ``partial``
+            parameter passed to `marshmallow.Schema.load`.
 
         .. versionchanged:: 3.0.0
             Add ``partial`` parameter.
@@ -713,7 +711,7 @@ class Pluck(Nested):
         dumped = AlbumSchema().dump(loaded)  # => {'artist': 42}
 
     :param Schema nested: The Schema class or class name (string)
-        to nest, or ``"self"`` to nest the :class:`Schema` within itself.
+        to nest, or ``"self"`` to nest the `Schema <marshmallow.Schema>` within itself.
     :param str field_name: The key to pluck a value from.
     :param kwargs: The same keyword arguments that :class:`Nested` receives.
     """
@@ -962,16 +960,13 @@ class Number(Field, typing.Generic[_NumType]):
         "too_large": "Number too large.",
     }
 
-    def __new__(cls, *args, **kwargs):
-        if cls is Number:
+    def __init__(self, *, as_string: bool = False, **kwargs):
+        if self.__class__ 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)
 
@@ -1578,21 +1573,18 @@ 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,
         values: Field | type[Field] | None = None,
         **kwargs,
     ):
+        if self.__class__ is Mapping:
+            warnings.warn(
+                "`Mapping` field should not be instantiated. Use `Dict` instead.",
+                ChangedInMarshmallow4Warning,
+                stacklevel=2,
+            )
         super().__init__(**kwargs)
         if keys is None:
             self.key_field = None
@@ -1965,7 +1957,7 @@ class Enum(Field):
 
 
 class Method(Field):
-    """A field that takes the value returned by a `Schema` method.
+    """A field that takes the value returned by a `Schema <marshmallow.Schema>` method.
 
     :param str serialize: The name of the Schema method from which
         to retrieve the value. The method must take an argument ``obj``

marshmallow/schema.py

@@ -41,7 +41,7 @@ from marshmallow.utils import (
 from marshmallow.warnings import RemovedInMarshmallow4Warning
 
 
-def _get_fields(attrs):
+def _get_fields(attrs) -> list[tuple[str, ma_fields.Field]]:
     """Get fields from a class
 
     :param attrs: Mapping of class attributes
@@ -124,10 +124,10 @@ class SchemaMeta(ABCMeta):
     def get_declared_fields(
         mcs,
         klass: SchemaMeta,
-        cls_fields: list,
-        inherited_fields: list,
+        cls_fields: list[tuple[str, ma_fields.Field]],
+        inherited_fields: list[tuple[str, ma_fields.Field]],
         dict_cls: type[dict] = dict,
-    ):
+    ) -> dict[str, ma_fields.Field]:
         """Returns a dictionary of field_name => `Field` pairs declared on the class.
         This is exposed mainly so that plugins can add additional fields, e.g. fields
         computed from class Meta options.
@@ -231,7 +231,7 @@ class SchemaOpts:
         self.many = getattr(meta, "many", False)
 
 
-class Schema(metaclass=SchemaMeta):
+class Schema(base.SchemaABC, metaclass=SchemaMeta):
     """Base schema class with which to define custom schemas.
 
     Example usage:
@@ -313,7 +313,7 @@ class Schema(metaclass=SchemaMeta):
     set_class = OrderedSet
 
     # These get set by SchemaMeta
-    opts: SchemaOpts
+    opts: typing.Any
     _declared_fields: dict[str, ma_fields.Field] = {}
     _hooks: dict[str, list[tuple[str, bool, dict]]] = {}
 
@@ -344,15 +344,15 @@ class Schema(metaclass=SchemaMeta):
         - ``timeformat``: Default format for `Time <fields.Time>` fields.
         - ``render_module``: Module to use for `loads <Schema.loads>` and `dumps <Schema.dumps>`.
             Defaults to `json` from the standard library.
-        - ``ordered``: If `True`, output of `Schema.dump` will be a `collections.OrderedDict`.
+        - ``ordered``: If `True`, output of `Schema.dump <marshmallow.Schema.dump>` will be a `collections.OrderedDict`.
         - ``index_errors``: If `True`, errors dictionaries will include the index
             of invalid items in a collection.
         - ``load_only``: Tuple or list of fields to exclude from serialized results.
         - ``dump_only``: Tuple or list of fields to exclude from deserialization
         - ``unknown``: Whether to exclude, include, or raise an error for unknown
             fields in the data. Use `EXCLUDE`, `INCLUDE` or `RAISE`.
-        - ``register``: Whether to register the `Schema` with marshmallow's internal
-            class registry. Must be `True` if you intend to refer to this `Schema`
+        - ``register``: Whether to register the `Schema <marshmallow.Schema>` with marshmallow's internal
+            class registry. Must be `True` if you intend to refer to this `Schema <marshmallow.Schema>`
             by class name in `Nested` fields. Only set this to `False` when memory
             usage is critical. Defaults to `True`.
         """
@@ -428,7 +428,7 @@ class Schema(metaclass=SchemaMeta):
         *,
         name: str = "GeneratedSchema",
     ) -> type[Schema]:
-        """Generate a `Schema` class given a dictionary of fields.
+        """Generate a `Schema <marshmallow.Schema>` class given a dictionary of fields.
 
         .. code-block:: python
 
@@ -1016,7 +1016,7 @@ class Schema(metaclass=SchemaMeta):
         self.load_fields = load_fields
 
     def on_bind_field(self, field_name: str, field_obj: ma_fields.Field) -> None:
-        """Hook to modify a field when it is bound to the `Schema`.
+        """Hook to modify a field when it is bound to the `Schema <marshmallow.Schema>`.
 
         No-op by default.
         """

marshmallow/utils.py

@@ -39,7 +39,7 @@ class _Missing:
 
 
 # Singleton value that indicates that a field's value is missing from input
-# dict passed to :meth:`Schema.load`. If the field's value is not required,
+# dict passed to `Schema.load <marshmallow.Schema.load>`. If the field's value is not required,
 # it's ``default`` value is used.
 missing = _Missing()
 

{marshmallow-3.24.1.dist-info → marshmallow-3.25.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: marshmallow
-Version: 3.24.1
+Version: 3.25.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>

{marshmallow-3.24.1.dist-info → marshmallow-3.25.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
 marshmallow/__init__.py,sha256=C-zbaQJ9dlJLJxotIqTa5OOaD6ojGNRqW8moGrMsGr8,2387
-marshmallow/base.py,sha256=ty-JhN__qqlJHaFVrFjMJTM5hQH6pG3xeo82Zu0sweY,719
+marshmallow/base.py,sha256=39W78-rnuzzx5T95YWBEECzjtqxdUA8XzYJNHd39VLg,1362
 marshmallow/class_registry.py,sha256=ZULbtwFxnj4bbzQqfwTLyNPUpr6xAZTLFMar4YJfKJQ,3032
-marshmallow/decorators.py,sha256=vmQFgBgdV0s1Fw8ySyZyQKvjKBTNf5JB3SCldEIl29o,8385
+marshmallow/decorators.py,sha256=B8Z-PsxWrftY4jTq3y_wt7kwlJWQI2vVQQyApMY5IeQ,8490
 marshmallow/error_store.py,sha256=A7AxgLMw9ffSmaxRH4x3wcBWibx-DuGH4LwSDpVn50I,2223
 marshmallow/exceptions.py,sha256=DuARdOcirCdJxmlp16V97hQKAXOokvdW12jXtYOlGyk,2326
-marshmallow/fields.py,sha256=BSqVSDWFWt0T-N477YHYCeGzQHBpiuEtTZPJ5ULPsQ8,74073
+marshmallow/fields.py,sha256=Z8wS9If4tqcv0KFnbm7HS5csMiVOD6--Donv6FlMfOc,74082
 marshmallow/orderedset.py,sha256=C2aAG6w1faIL1phinbAltbe3AUAnF5MN6n7fzESNDhI,2922
 marshmallow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-marshmallow/schema.py,sha256=FIwUiCJfdz9EMNMj9w__UIuTx0Ik_quFL_QqSWuzJ2s,48445
+marshmallow/schema.py,sha256=qUY1MvcYxtEuztzjoom2fYaC7x2t16cAx4FBdgz3SDY,48696
 marshmallow/types.py,sha256=RDS4IfasIehvH2rGWh9e4RTBtsMp-JFFtjApajV22zc,283
-marshmallow/utils.py,sha256=-6jOnkuqFvb0DLeTVVifAPOklD_IdHC4LanhClCO0Hc,11897
+marshmallow/utils.py,sha256=pLZXqQWu7PHaQrQCrgwnR8eI_-aq_BVct5CCwyygUvk,11917
 marshmallow/validate.py,sha256=t5-4Qg_XlSQgcCujf_pimKIdZE0QT63jHyQP-miJNK0,24151
 marshmallow/warnings.py,sha256=YHC0kQQBbTKCiA1FuwnbnXqrph7oKuU9BjTV4cxwnzE,192
-marshmallow-3.24.1.dist-info/LICENSE,sha256=kGtdkFHkJhRMsXOtkRZnuOvQWpxYTCwmwTWzKj7RIAE,1064
-marshmallow-3.24.1.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
-marshmallow-3.24.1.dist-info/METADATA,sha256=uuQri_Lj4klck4q6jwImdETasTVjrvGSpgu0I7GuM2E,7084
-marshmallow-3.24.1.dist-info/RECORD,,
+marshmallow-3.25.0.dist-info/LICENSE,sha256=kGtdkFHkJhRMsXOtkRZnuOvQWpxYTCwmwTWzKj7RIAE,1064
+marshmallow-3.25.0.dist-info/WHEEL,sha256=CpUCUxeHQbRN5UGRQHYRJorO5Af-Qy_fHMctcQ8DSGI,82
+marshmallow-3.25.0.dist-info/METADATA,sha256=yQLETlmBAzADnSDY4fAT_4zsyjlAxPlRFT6NVIovaYo,7084
+marshmallow-3.25.0.dist-info/RECORD,,