marshmallow 3.24.1__tar.gz → 3.25.0__tar.gz

{marshmallow-3.24.1 → marshmallow-3.25.0}/CHANGELOG.rst

@@ -1,6 +1,39 @@
 Changelog
 ---------
 
+3.25.0 (2025-01-09)
+*******************
+
+Features:
+
+- Typing: Improve type annotations for ``SchemaMeta.get_declared_fields`` (:pr:`2742`).
+
+Bug fixes:
+
+- Typing: Relax type annotation for ``Schema.opts`` to allow subclasses to define their own
+  options classes (:pr:`2744`).
+
+Other changes:
+
+- Restore ``marshmallow.base.SchemaABC`` for backwards-compatibility (:issue:`2743`).
+  Note that this class is deprecated and will be removed in marshmallow 4.
+  Use `marshmallow.schema.Schema` as a base class for type-checking instead.
+
+3.24.2 (2025-01-08)
+*******************
+
+Changes:
+
+- Don't override ``__new__`` to avoid breaking usages of `inspect.signature` with
+  `Field <marshmallow.fields.Field>` classes.
+  This allows marshmallow-sqlalchemy users to upgrade marshmallow without
+  upgrading to marshmallow-sqlalchemy>=1.1.1.
+
+Documentation:
+
+- Add top-level API back to docs (:issue:`2739`).
+  Thanks :user:`llucax` for reporting.
+
 3.24.1 (2025-01-06)
 *******************
 
@@ -22,7 +55,7 @@ Bug fixes:
 
 Deprecations:
 
-- Custom validators should raise a `ValidationError <marshmallow.exceptions.ValidationError>` for invalid values. 
+- Custom validators should raise a `ValidationError <marshmallow.exceptions.ValidationError>` for invalid values.
   Returning `False`` is no longer supported .
 - Deprecate ``context`` parameter of `Schema <marshmallow.schema.Schema>` (:issue:`1826`).
   Use `contextVars.ContextVar` to pass context data instead.
@@ -295,7 +328,7 @@ Bug fixes:
 - Don't expose ``Field``\s as ``Schema`` attributes. This reverts a change
   introduced in 3.12.0 that causes issues when field names conflict with
   ``Schema`` attributes or methods. ``Fields``\s are still accessible on a
-   ``Schema`` instance through the ``fields`` attribute. (:pr:`1843`)
+  ``Schema`` instance through the ``fields`` attribute. (:pr:`1843`)
 
 3.12.1 (2021-05-10)
 *******************
@@ -870,7 +903,7 @@ Bug fixes:
 Other changes:
 
 - *Backwards-incompatible*: ``_serialize`` and ``_deserialize`` methods of
-all ``fields.Field`` subclasses must accept ``**kwargs`` (:pr:`1007`).
+  all ``fields.Field`` subclasses must accept ``**kwargs`` (:pr:`1007`).
 
 
 3.0.0b18 (2018-10-15)

{marshmallow-3.24.1 → marshmallow-3.25.0}/PKG-INFO

@@ -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 → marshmallow-3.25.0}/docs/api_reference.rst

@@ -5,6 +5,7 @@ API Reference
 *************
 
 .. toctree::
+    top_level
     marshmallow.schema
     marshmallow.fields
     marshmallow.decorators

{marshmallow-3.24.1 → marshmallow-3.25.0}/docs/custom_fields.rst

@@ -1,7 +1,7 @@
 Custom fields
 =============
 
-There are three ways to create a custom-formatted field for a `Schema`:
+There are three ways to create a custom-formatted field for a `Schema <marshmallow.Schema>`:
 
 - Create a custom :class:`Field <marshmallow.fields.Field>` class
 - Use a :class:`Method <marshmallow.fields.Method>` field
@@ -101,7 +101,7 @@ Adding context to `Method` and `Function` fields
 
 A :class:`Function <marshmallow.fields.Function>` or :class:`Method <marshmallow.fields.Method>` field may need information about its environment to know how to serialize a value.
 
-In these cases, you can set the ``context`` attribute (a dictionary) of a `Schema`. :class:`Function <marshmallow.fields.Function>` and :class:`Method <marshmallow.fields.Method>` fields will have access to this dictionary.
+In these cases, you can set the ``context`` attribute (a dictionary) of a `Schema <marshmallow.Schema>`. :class:`Function <marshmallow.fields.Function>` and :class:`Method <marshmallow.fields.Method>` fields will have access to this dictionary.
 
 As an example, you might want your ``UserSchema`` to output whether or not a ``User`` is the author of a ``Blog`` or whether a certain word appears in a ``Blog's`` title.
 

{marshmallow-3.24.1 → marshmallow-3.25.0}/docs/examples.rst

@@ -1,5 +1,3 @@
-.. module:: marshmallow
-
 ********
 Examples
 ********
@@ -12,7 +10,7 @@ Below is a schema that could be used to validate
 ``package.json`` files. This example demonstrates the following features:
 
 
-- Validation and deserialization using :meth:`Schema.load`
+- Validation and deserialization using `Schema.load <marshmallow.Schema.load>`
 - :doc:`Custom fields <custom_fields>`
 - Specifying deserialization keys using ``data_key``
 - Including unknown keys using ``unknown = INCLUDE``

{marshmallow-3.24.1 → marshmallow-3.25.0}/docs/extending.rst

@@ -1,5 +1,3 @@
-.. module:: marshmallow
-
 Extending schemas
 =================
 
@@ -213,6 +211,8 @@ The pipeline for serialization is similar, except that the ``pass_many=True`` pr
             def step2(self, data, **kwargs):
                 do_step2(data)
 
+.. _schema_validation:
+
 Schema-level validation
 -----------------------
 
@@ -347,7 +347,7 @@ However, if you want to specify how values are accessed from an object, you can
 Custom error handling
 ---------------------
 
-By default, :meth:`Schema.load` will raise a :exc:`ValidationError <marshmallow.exceptions.ValidationError>` if passed invalid data.
+By default, `Schema.load <marshmallow.Schema.load>` will raise a :exc:`ValidationError <marshmallow.exceptions.ValidationError>` if passed invalid data.
 
 You can specify a custom error-handling function for a :class:`Schema` by overriding the `handle_error <marshmallow.Schema.handle_error>`  method. The method receives the :exc:`ValidationError <marshmallow.exceptions.ValidationError>` and the original input data to be deserialized.
 
@@ -457,7 +457,7 @@ Our application schemas can now inherit from our custom schema class.
 Using context
 -------------
 
-The ``context`` attribute of a `Schema` is a general-purpose store for extra information that may be needed for (de)serialization. It may be used in both ``Schema`` and ``Field`` methods.
+The ``context`` attribute of a `Schema <marshmallow.Schema>` is a general-purpose store for extra information that may be needed for (de)serialization. It may be used in both ``Schema`` and ``Field`` methods.
 
 .. code-block:: python
 

{marshmallow-3.24.1 → marshmallow-3.25.0}/docs/nesting.rst

@@ -261,7 +261,7 @@ This is useful for avoiding circular imports when your schemas are located in di
 Nesting a schema within itself
 ------------------------------
 
-If the object to be marshalled has a relationship to an object of the same type, you can nest the `Schema` within itself by passing a callable that returns an instance of the same schema.
+If the object to be marshalled has a relationship to an object of the same type, you can nest the `Schema <marshmallow.Schema>` within itself by passing a callable that returns an instance of the same schema.
 
 .. code-block:: python
 

{marshmallow-3.24.1 → marshmallow-3.25.0}/docs/quickstart.rst

@@ -1,5 +1,3 @@
-.. module:: marshmallow
-
 Quickstart
 ==========
 
@@ -176,7 +174,7 @@ Set ``many=True`` when dealing with iterable collections of objects.
 Validation
 ----------
 
-:meth:`Schema.load` (and its JSON-decoding counterpart, :meth:`Schema.loads`) raises a :exc:`ValidationError <marshmallow.exceptions.ValidationError>` error when invalid data are passed in. You can access the dictionary of validation errors from the `ValidationError.messages <marshmallow.exceptions.ValidationError.messages>` attribute. The data that were correctly deserialized are accessible in `ValidationError.valid_data <marshmallow.exceptions.ValidationError.valid_data>`. Some fields, such as the :class:`Email <fields.Email>` and :class:`URL <fields.URL>` fields, have built-in validation.
+`Schema.load <marshmallow.Schema.load>` (and its JSON-decoding counterpart, `Schema.loads <marshmallow.Schema.loads>`) raises a :exc:`ValidationError <marshmallow.exceptions.ValidationError>` error when invalid data are passed in. You can access the dictionary of validation errors from the `ValidationError.messages <marshmallow.exceptions.ValidationError.messages>` attribute. The data that were correctly deserialized are accessible in `ValidationError.valid_data <marshmallow.exceptions.ValidationError.valid_data>`. Some fields, such as the :class:`Email <fields.Email>` and :class:`URL <fields.URL>` fields, have built-in validation.
 
 .. code-block:: python
 
@@ -275,7 +273,7 @@ You may also pass a collection (list, tuple, generator) of callables to ``valida
 .. warning::
 
     Validation occurs on deserialization but not on serialization. 
-    To improve serialization performance, data passed to :meth:`Schema.dump` 
+    To improve serialization performance, data passed to `Schema.dump <marshmallow.Schema.dump>` 
     are considered valid.
 
 .. seealso::
@@ -286,7 +284,7 @@ You may also pass a collection (list, tuple, generator) of callables to ``valida
 
 .. seealso::
 
-    Need schema-level validation? See the :ref:`Extending Schemas <schemavalidation>` page.
+    Need schema-level validation? See the :ref:`Extending Schemas <schema_validation>` page.
 
 
 Field validators as methods
@@ -313,7 +311,7 @@ It is sometimes convenient to write validators as methods. Use the `validates <m
 Required fields
 ---------------
 
-Make a field required by passing ``required=True``. An error will be raised if the the value is missing from the input to :meth:`Schema.load`.
+Make a field required by passing ``required=True``. An error will be raised if the the value is missing from the input to `Schema.load <marshmallow.Schema.load>`.
 
 To customize the error message for required fields, pass a `dict` with a ``required`` key as the ``error_messages`` argument for the field.
 
@@ -405,7 +403,7 @@ This behavior can be modified with the ``unknown`` option, which accepts one of
 - `EXCLUDE <marshmallow.utils.EXCLUDE>`: exclude unknown fields
 - `INCLUDE <marshmallow.utils.INCLUDE>`: accept and include the unknown fields
 
-You can specify ``unknown`` in the *class Meta* of your `Schema`,
+You can specify ``unknown`` in the *class Meta* of your `Schema <marshmallow.Schema>`,
 
 .. code-block:: python
 
@@ -436,7 +434,7 @@ This order of precedence allows you to change the behavior of a schema for diffe
 Validation without deserialization
 ----------------------------------
 
-If you only need to validate input data (without deserializing to an object), you can use :meth:`Schema.validate`.
+If you only need to validate input data (without deserializing to an object), you can use `Schema.validate <marshmallow.Schema.validate>`.
 
 .. code-block:: python
 

marshmallow-3.25.0/docs/top_level.rst

@@ -0,0 +1,12 @@
+Top-level API
+=============
+
+.. automodule:: marshmallow
+   :members:
+   :undoc-members:
+   :autosummary:
+
+.. data:: EXCLUDE
+.. data:: INCLUDE
+.. data:: RAISE
+.. data:: missing

{marshmallow-3.24.1 → marshmallow-3.25.0}/docs/upgrading.rst

@@ -6,7 +6,7 @@ This section documents migration paths to new releases.
 Upgrading to 3.3
 ++++++++++++++++
 
-In 3.3, `fields.Nested <marshmallow.fields.Nested>` may take a callable that returns a schema instance. 
+In 3.3, `fields.Nested <marshmallow.fields.Nested>` may take a callable that returns a schema instance.
 Use this to resolve order-of-declaration issues when schemas nest each other.
 
 .. code-block:: python
@@ -103,15 +103,15 @@ along with the valid data from the `ValidationError.valid_data
         errors = err.messages
         valid_data = err.valid_data
 
-:meth:`Schema.validate() <marshmallow.Schema.validate>` always returns a dictionary of validation errors (same as 2.x with ``strict=False``).
+`Schema.validate <marshmallow.Schema.validate>` always returns a dictionary of validation errors (same as 2.x with ``strict=False``).
 
 .. code-block:: python
 
     schema.validate({"email": "invalid"})
     # {'email': ['Not a valid email address.']}
 
-Setting the ``strict`` option on ``class Meta`` has no effect on `Schema` behavior.
-Passing ``strict=True`` or ``strict=False`` to the `Schema` constructor
+Setting the ``strict`` option on ``class Meta`` has no effect on `Schema <marshmallow.Schema>` behavior.
+Passing ``strict=True`` or ``strict=False`` to the `Schema <marshmallow.Schema>` constructor
 will raise a :exc:`TypeError`.
 
 
@@ -182,7 +182,7 @@ and `validates_schema <marshmallow.decorators.validates_schema>` receive
 Validation does not occur on serialization
 ******************************************
 
-:meth:`Schema.dump() <marshmallow.Schema.dump>` will no longer validate and collect error messages. You *must* validate
+`Schema.dump <marshmallow.Schema.dump>` will no longer validate and collect error messages. You *must* validate
 your data before serializing it.
 
 .. code-block:: python
@@ -737,7 +737,7 @@ The same key is used for serialization and deserialization.
         email = fields.Email(data_key="CamelCasedEmail")
 
 It is not possible to specify a different key for serialization and deserialization on the same field.
-This use case is covered by using two different `Schema`.
+This use case is covered by using two different `Schema <marshmallow.Schema>`.
 
 .. code-block:: python
 
@@ -970,8 +970,8 @@ The ``prefix`` parameter of ``Schema`` is removed. The same feature can be achie
 
     # 2.x
     class MySchema(Schema):
-        f1 = fields.Field()
-        f2 = fields.Field()
+        f1 = fields.Raw()
+        f2 = fields.Raw()
 
 
     MySchema(prefix="pre_").dump({"f1": "one", "f2": "two"})
@@ -980,8 +980,8 @@ The ``prefix`` parameter of ``Schema`` is removed. The same feature can be achie
 
     # 3.x
     class MySchema(Schema):
-        f1 = fields.Field()
-        f2 = fields.Field()
+        f1 = fields.Raw()
+        f2 = fields.Raw()
 
         @post_dump
         def prefix_usr(self, data):
@@ -1025,10 +1025,10 @@ In marshmallow 2, it was possible to have multiple fields with the same ``attrib
 
     # 2.x
     class MySchema(Schema):
-        f1 = fields.Field()
-        f2 = fields.Field(attribute="f1")
-        f3 = fields.Field(attribute="f5")
-        f4 = fields.Field(attribute="f5")
+        f1 = fields.Raw()
+        f2 = fields.Raw(attribute="f1")
+        f3 = fields.Raw(attribute="f5")
+        f4 = fields.Raw(attribute="f5")
 
 
     MySchema()
@@ -1037,10 +1037,10 @@ In marshmallow 2, it was possible to have multiple fields with the same ``attrib
 
     # 3.x
     class MySchema(Schema):
-        f1 = fields.Field()
-        f2 = fields.Field(attribute="f1")
-        f3 = fields.Field(attribute="f5")
-        f4 = fields.Field(attribute="f5")
+        f1 = fields.Raw()
+        f2 = fields.Raw(attribute="f1")
+        f3 = fields.Raw(attribute="f5")
+        f4 = fields.Raw(attribute="f5")
 
 
     MySchema()
@@ -1048,10 +1048,10 @@ In marshmallow 2, it was possible to have multiple fields with the same ``attrib
 
 
     class MySchema(Schema):
-        f1 = fields.Field()
-        f2 = fields.Field(attribute="f1", dump_only=True)
-        f3 = fields.Field(attribute="f5")
-        f4 = fields.Field(attribute="f5", dump_only=True)
+        f1 = fields.Raw()
+        f2 = fields.Raw(attribute="f1", dump_only=True)
+        f3 = fields.Raw(attribute="f5")
+        f4 = fields.Raw(attribute="f5", dump_only=True)
 
 
     MySchema()
@@ -1061,7 +1061,7 @@ In marshmallow 2, it was possible to have multiple fields with the same ``attrib
 ``Field.fail`` is deprecated in favor of ``Field.make_error``
 *************************************************************
 
-`Field.fail <marshmallow.fields.Field.fail>` is deprecated. 
+`Field.fail <marshmallow.fields.Field.fail>` is deprecated.
 Use `Field.make_error <marshmallow.fields.Field.fail>`. This allows you to
 re-raise exceptions using ``raise ... from ...``.
 
@@ -1242,7 +1242,7 @@ As a consequence of this new behavior, the ``skip_missing`` class Meta option ha
 Pre-processing and post-processing methods
 ******************************************
 
-The pre- and post-processing API was significantly improved for better consistency and flexibility. The `pre_load <marshmallow.decorators.pre_load>`, `post_load <marshmallow.decorators.post_load>`, `pre_dump <marshmallow.decorators.pre_dump>`, and `post_dump <marshmallow.decorators.post_dump>` should be used to define processing hooks. `Schema.preprocessor` and `Schema.data_handler` are removed.
+The pre- and post-processing API was significantly improved for better consistency and flexibility. The `pre_load <marshmallow.decorators.pre_load>`, `post_load <marshmallow.decorators.post_load>`, `pre_dump <marshmallow.decorators.pre_dump>`, and `post_dump <marshmallow.decorators.post_dump>` should be used to define processing hooks. ``Schema.preprocessor`` and ``Schema.data_handler`` are removed.
 
 
 .. code-block:: python
@@ -1289,7 +1289,7 @@ See the :doc:`Extending Schemas <extending>` page for more information on the ``
 Schema validators
 *****************
 
-Similar to pre-processing and post-processing methods, schema validators are now defined as methods. Decorate schema validators with `validates_schema <marshmallow.decorators.validates_schema>`. `Schema.validator` is removed.
+Similar to pre-processing and post-processing methods, schema validators are now defined as methods. Decorate schema validators with `validates_schema <marshmallow.decorators.validates_schema>`. ``Schema.validator`` is removed.
 
 .. code-block:: python
 
@@ -1324,7 +1324,7 @@ Similar to pre-processing and post-processing methods, schema validators are now
 Custom accessors and error handlers
 ***********************************
 
-Custom accessors and error handlers are now defined as methods. `Schema.accessor` and `Schema.error_handler` are deprecated.
+Custom accessors and error handlers are now defined as methods. ``Schema.accessor`` and ``Schema.error_handler`` are deprecated.
 
 .. code-block:: python
 
@@ -1432,7 +1432,7 @@ The :exc:`MarshallingError` and :exc:`UnmarshallingError` exceptions are depreca
 Handle ``ValidationError`` in strict mode
 -----------------------------------------
 
-When using `strict` mode, you should handle `ValidationErrors` when calling `Schema.dump` and `Schema.load`.
+When using `strict` mode, you should handle `ValidationErrors` when calling `Schema.dump <marshmallow.Schema.dump>` and `Schema.load <marshmallow.Schema.load>`.
 
 .. code-block:: python
 
@@ -1707,7 +1707,7 @@ Perhaps the largest change is in how objects get serialized. Serialization occur
 
 .. note::
 
-    Some crucial parts of the pre-1.0 API have been retained to ease the transition. You can still pass an object to a `Schema` constructor and access the `Schema.data` and `Schema.errors` properties. The `is_valid` method, however, has been completely removed. It is recommended that you migrate to the new API to prevent future releases from breaking your code.
+    Some crucial parts of the pre-1.0 API have been retained to ease the transition. You can still pass an object to a `Schema <marshmallow.Schema>` constructor and access the `Schema.data` and `Schema.errors` properties. The `is_valid` method, however, has been completely removed. It is recommended that you migrate to the new API to prevent future releases from breaking your code.
 
 The Fields interface was also reworked in 1.0 to make it easier to define custom fields with their own serialization and deserialization behavior. Custom fields now implement :meth:`Field._serialize` and :meth:`Field._deserialize`.
 
@@ -1753,11 +1753,11 @@ Another major change in 1.0 is that multiple validation errors can be stored for
 
 Other notable changes:
 
-- Serialized output is no longer an `OrderedDict` by default. You must explicitly set the `ordered` class Meta option to `True` .
-- :class:`Serializer` has been renamed to :class:`Schema`, but you can still import `marshmallow.Serializer` (which is aliased to :class:`Schema`).
+- Serialized output is no longer an ``OrderedDict`` by default. You must explicitly set the `ordered` class Meta option to `True` .
+- ``Serializer`` has been renamed to `Schema <marshmallow.schema.Schema>`, but you can still import ``marshmallow.Serializer`` (which is aliased to `Schema <marshmallow.Schema>`).
 - ``datetime`` objects serialize to ISO8601-formatted strings by default (instead of RFC821 format).
 - The ``fields.validated`` decorator was removed, as it is no longer necessary given the new Fields interface.
-- `Schema.factory` class method was removed.
+- ``Schema.factory`` class method was removed.
 
 .. seealso::
 

{marshmallow-3.24.1 → marshmallow-3.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "marshmallow"
-version = "3.24.1"
+version = "3.25.0"
 description = "A lightweight library for converting complex datatypes to and from native Python datatypes."
 readme = "README.rst"
 license = { file = "LICENSE" }

marshmallow-3.25.0/src/marshmallow/base.py

@@ -0,0 +1,61 @@
+"""Abstract base classes.
+
+These are necessary to avoid circular imports between schema.py and fields.py.
+
+.. warning::
+
+    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
+
+from abc import ABC, abstractmethod
+
+
+class FieldABC(ABC):
+    """Abstract base class from which all Field classes inherit."""
+
+    @abstractmethod
+    def serialize(self, attr, obj, accessor=None):
+        pass
+
+    @abstractmethod
+    def deserialize(self, value):
+        pass
+
+    @abstractmethod
+    def _serialize(self, value, attr, obj, **kwargs):
+        pass
+
+    @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-3.24.1 → marshmallow-3.25.0}/src/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-3.24.1 → marshmallow-3.25.0}/src/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-3.24.1 → marshmallow-3.25.0}/src/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-3.24.1 → marshmallow-3.25.0}/src/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/src/marshmallow/base.py

@@ -1,33 +0,0 @@
-"""Abstract base classes.
-
-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.
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-
-
-class FieldABC(ABC):
-    """Abstract base class from which all Field classes inherit."""
-
-    @abstractmethod
-    def serialize(self, attr, obj, accessor=None):
-        pass
-
-    @abstractmethod
-    def deserialize(self, value):
-        pass
-
-    @abstractmethod
-    def _serialize(self, value, attr, obj, **kwargs):
-        pass
-
-    @abstractmethod
-    def _deserialize(self, value, attr, data, **kwargs):
-        pass