Merge branch '3.x-line' into dev

CHANGELOG.rst

@@ -105,6 +105,14 @@ Previously-deprecated API have been removed, including:
 - `marshmallow.utils.pprint` (deprecated in 3.7.0). Use `pprint.pprint` instead.
 - Remove ``__version__``, ``__parsed_version__``, and ``__version_info__`` attributes which were deprecated in 3.21.0.
 
+3.24.2 (unreleased)
+*******************
+
+Documentation:
+
+- Add top-level API back to docs (:issue:`2739`).
+  Thanks :user:`llucax` for reporting.
+
 3.24.1 (2025-01-06)
 *******************
 
@@ -399,7 +407,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)
 *******************
@@ -974,7 +982,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)

docs/api_reference.rst

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

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

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``

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_collection=Tru
             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.
 

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
 

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
 

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

docs/upgrading.rst

@@ -483,15 +483,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`.
 
 
@@ -562,7 +562,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
@@ -1117,7 +1117,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
 
@@ -1622,7 +1622,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
@@ -1669,7 +1669,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
 
@@ -1704,7 +1704,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
 
@@ -1812,7 +1812,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
 
@@ -2087,7 +2087,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`.
 
@@ -2133,11 +2133,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::
 

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_collection=True``, the raw data (which may be a collection) is passed.
 
     If ``pass_original=True``, the original data (before unmarshalling) will be passed as
@@ -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_collection=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_collection=True``, the raw data (which may be a collection) is passed.
 
     If ``pass_original=True``, the original data (before serializing) will be passed as
@@ -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_collection=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_collection=True``, the raw data (which may be a collection) is passed.
 
     If ``pass_original=True``, the original data (before deserializing) will be passed as

src/marshmallow/fields.py

@@ -370,7 +370,7 @@ def deserialize(
 
         :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.
@@ -391,7 +391,7 @@ def deserialize(
 
     def _bind_to_schema(self, field_name: str, parent: 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 parent: Parent object.
@@ -435,7 +435,7 @@ def _deserialize(
 
         :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.
@@ -485,8 +485,9 @@ class ParentSchema(Schema):
         # 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``.
@@ -620,8 +621,8 @@ def _deserialize(
     ):
         """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.
@@ -1928,7 +1929,7 @@ def _deserialize(self, value, attr, data, **kwargs) -> _EnumType:
 
 
 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``