marshmallow 3.26.1__tar.gz → 4.0.1__tar.gz

{marshmallow-3.26.1 → marshmallow-4.0.1}/CHANGELOG.rst

@@ -1,6 +1,139 @@
 Changelog
 ---------
 
+4.0.1 (2025-08-28)
+++++++++++++++++++
+
+Bug fixes:
+
+- Fix wildcard import of ``from marshmallow import *`` (:pr:`2823`).
+  Thanks :user:`Florian-Laport` for the PR.
+
+
+4.0.0 (2025-04-16)
+******************
+
+See :ref:`upgrading_4_0` for a guide on updating your code.
+
+Features:
+
+- Typing: Add types to all `Field <marshmallow.fields.Field>` constructor kwargs (:issue:`2285`).
+  Thanks :user:`navignaw` for the suggestion.
+- `DateTime <marshmallow.fields.DateTime>`, `Date <marshmallow.fields.Date>`, `Time <marshmallow.fields.Time>`,
+  `TimeDelta <marshmallow.fields.TimeDelta>`, and `Enum <marshmallow.fields.Enum>`
+  accept their internal value types as valid input (:issue:`1415`).
+  Thanks :user:`bitdancer` for the suggestion.
+- `@validates <marshmallow.validates>` accepts multiple field names (:issue:`1960`).
+  *Backwards-incompatible*: Decorated methods now receive ``data_key`` as a keyword argument.
+  Thanks :user:`dpriskorn` for the suggestion and :user:`dharani7998` for the PR.
+
+Other changes:
+
+- Typing: `Field <marshmallow.fields.Field>` is now a generic type with a type argument for the internal value type.
+- `marshmallow.fields.UUID` no longer subclasses `marshmallow.fields.String`.
+- `marshmallow.Schema.load` no longer silently fails to call schema validators when a generator is passed (:issue:`1898`).
+  The typing of `data` is also updated to be more accurate.
+  Thanks :user:`ziplokk1` for reporting.
+- *Backwards-incompatible*: Use `datetime.date.fromisoformat`, `datetime.time.fromisoformat`, and `datetime.datetime.fromisoformat` from the standard library to deserialize dates, times and datetimes (:pr:`2078`).
+As a consequence of this change:
+  - Time with time offsets are now supported.
+  - YYYY-MM-DD is now accepted as a datetime and deserialized as naive 00:00 AM.
+  - `from_iso_date`, `from_iso_time` and `from_iso_datetime` are removed from `marshmallow.utils`.
+- Remove `isoformat`, `to_iso_time` and `to_iso_datetime` from `marshmallow.utils` (:pr:`2766`).
+- Remove `from_rfc`, and `rfcformat` from `marshmallow.utils` (:pr:`2767`).
+- Remove `is_keyed_tuple` from `marshmallow.utils` (:pr:`2768`).
+- Remove `get_fixed_timezone` from `marshmallow.utils` (:pr:`2773`).
+
+- *Backwards-incompatible*: `marshmallow.fields.Boolean` no longer serializes non-boolean values (:pr:`2725`).
+- *Backwards-incompatible*: Rename ``schema`` parameter to ``parent`` in `marshmallow.fields.Field._bind_to_schema` (:issue:`1360`).
+- *Backwards-incompatible*: Rename ``pass_many`` parameter to ``pass_collection`` in pre/post processing methods (:issue:`1369`).
+- *Backwards-incompatible*: `marshmallow.fields.TimeDelta` no longer truncates float values when
+  deserializing (:pr:`2654`). This allows microseconds to be preserved, e.g.
+
+.. code-block:: python
+
+    from marshmallow import fields
+
+    field = fields.TimeDelta()
+
+    # Before
+    field.deserialize(12.9)
+    datetime.timedelta(seconds=12)
+    # datetime.timedelta(seconds=12)
+
+    # After
+    field.deserialize(12.9)
+    # datetime.timedelta(seconds=12, microseconds=900000)
+
+- Improve performance and minimize float precision loss of `marshmallow.fields.TimeDelta` serialization (:pr:`2654`).
+- *Backwards-incompatible*: Remove ``serialization_type`` parameter from
+  `marshmallow.fields.TimeDelta` (:pr:`2654`).
+
+Thanks :user:`ddelange` for the PR.
+
+- *Backwards-incompatible*: Remove `Schema <marshmallow.schema.Schema>`'s ``context`` attribute (deprecated since 3.24.0). Passing a context
+  should be done using `contextvars.ContextVar` (:issue:`1826`).
+  marshmallow 4 provides an experimental `Context <marshmallow.experimental.context.Context>`
+  manager class that can be used to both set and retrieve context.
+
+.. code-block:: python
+
+    import typing
+
+    from marshmallow import Schema, fields
+    from marshmallow.experimental.context import Context
+
+
+    class UserContext(typing.TypedDict):
+        suffix: str
+
+
+    class UserSchema(Schema):
+        name_suffixed = fields.Function(
+            lambda obj: obj["name"] + Context[UserContext].get()["suffix"]
+        )
+
+
+    with Context[UserContext]({"suffix": "bar"}):
+        UserSchema().dump({"name": "foo"})
+        # {'name_suffixed': 'foobar'}
+
+- Methods decorated with `marshmallow.pre_load`, `marshmallow.post_load`, `marshmallow.validates_schema`,
+  receive ``unknown`` as a keyword argument (:pr:`1632`).
+  Thanks :user:`jforand` for the PR.
+- *Backwards-incompatible*: Arguments to `decorators <marshmallow.decorators>` are keyword-only arguments.
+- *Backwards-incompatible*: Rename ``json_data`` parameter of `marshmallow.Schema.loads` to ``s``
+  for compatibility with most render module implementations (`json`, ``simplejson``, etc.) (:pr:`2764`).
+  Also make it a positional-only argument.
+- Incorrectly declaring a field using a field class rather than instance
+  errors at class declaration time (previously happended when the schema was instantiated) (:pr:`2772`).
+- Passing invalid values for ``unknown`` will cause an error in type checkers (:pr:`2771`).
+
+Deprecations/Removals:
+
+- *Backwards-incompatible*: Remove implicit field creation, i.e. using the ``fields`` or ``additional`` class Meta options with undeclared fields (:issue:`1356`).
+- The `ordered` class Meta option is removed  (:issue:`2146`). Field order is already preserved by default.
+  Set `Schema.dict_class` to `OrderedDict` to maintain the previous behavior.
+- The `marshmallow.base` module is removed (:pr:`2722`).
+
+Previously-deprecated APIs have been removed, including:
+
+- The ``ordered`` `class Meta <marshmallow.Schema.Meta>` option is removed  (:issue:`2146`) (deprecated in 3.26.0).
+- *Backwards-incompatible*: `marshmallow.fields.Number` is no longer usable as a field in a schema (deprecated in 3.24.0).
+  Use `marshmallow.fields.Integer`, `marshmallow.fields.Float`, or `marshmallow.fields.Decimal` instead.
+- *Backwards-incompatible*: `marshmallow.fields.Mapping` is no longer usable as a field in a schema (deprecated in 3.24.0).
+- *Backwards-incompatible*: Custom validators must raise a `ValidationError <marshmallow.exceptions.ValidationError>` for invalid values (deprecated in 3.24.0).
+  Returning `False` is no longer supported (:issue:`1775`).
+  Use `marshmallow.fields.Dict` instead.
+- Remove ``__version__``, ``__parsed_version__``, and ``__version_info__`` attributes (deprecated in 3.21.0).
+- `default` and `missing` parameters, which were replaced by `dump_default` and `load_default` in 3.13.0 (:pr:`1742`, :pr:`2700`).
+- Passing field metadata via keyword arguments (deprecated in 3.10.0). Use the explicit ``metadata=...``
+  argument instead (:issue:`1350`).
+- `marshmallow.utils.pprint` (deprecated in 3.7.0). Use `pprint.pprint` instead.
+- Passing `"self"` to `fields.Nested` (deprecated in 3.3.0). Use a callable instead.
+- ``Field.fail``, which was replaced by ``Field.make_error`` in 3.0.0.
+- `json_module` class Meta option (deprecated in 3.0.0b3). Use `render_module` instead.
+
 3.26.1 (2025-02-03)
 *******************
 
@@ -26,7 +159,7 @@ Features:
 
 Bug fixes:
 
-- Respect ``data_key`` when schema validators raise a `ValidationError <marshmallow.exceptions.ValidationError>` 
+- Respect ``data_key`` when schema validators raise a `ValidationError <marshmallow.exceptions.ValidationError>`
   with a ``field_name`` argument (:issue:`2170`). Thanks :user:`matejsp` for reporting.
 - Correctly handle multiple `@post_load <marshmallow.post_load>` methods where one method appends to
   the data and another passes ``pass_original=True`` (:issue:`1755`).
@@ -109,7 +242,7 @@ Features:
 
 Bug fixes:
 
-- Typing: Fix type hint for ``nested`` parameter of `Nested <marshmallow.fields.Nested>`.
+- Typing: Fix type hint for ``nested`` parameter of `Nested <marshmallow.fields.Nested>` (:pr:`2721`).
 
 Deprecations:
 

{marshmallow-3.26.1 → marshmallow-4.0.1}/CONTRIBUTING.rst

@@ -26,8 +26,7 @@ Ways to contribute
 
 - Comment on some of marshmallow's `open issues <https://github.com/marshmallow-code/marshmallow/issues>`_ (especially those `labeled "feedback welcome" <https://github.com/marshmallow-code/marshmallow/issues?q=is%3Aopen+is%3Aissue+label%3A%22feedback+welcome%22>`_). Share a solution or workaround. Make a suggestion for how a feature can be made better. Opinions are welcome!
 - Improve `the docs <https://marshmallow.readthedocs.io>`_.
-  For straightforward edits,
-  click the ReadTheDocs menu button in the bottom-right corner of the page and click "Edit".
+  For straightforward edits, click the edit button in the top-right corner of the page.
   See the :ref:`Documentation <contributing_documentation>` section of this page if you want to build the docs locally.
 - If you think you've found a bug, `open an issue <https://github.com/marshmallow-code/marshmallow/issues>`_.
 - Contribute an :ref:`example usage <contributing_examples>` of marshmallow.

{marshmallow-3.26.1 → marshmallow-4.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: marshmallow
-Version: 3.26.1
+Version: 4.0.1
 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>
@@ -15,16 +15,18 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: packaging>=17.0
+License-File: LICENSE
+Requires-Dist: backports-datetime-fromisoformat; python_version < '3.11'
+Requires-Dist: typing-extensions; python_version < '3.11'
 Requires-Dist: marshmallow[tests] ; extra == "dev"
 Requires-Dist: tox ; extra == "dev"
 Requires-Dist: pre-commit>=3.5,<5.0 ; extra == "dev"
 Requires-Dist: autodocsumm==0.2.14 ; extra == "docs"
-Requires-Dist: furo==2024.8.6 ; extra == "docs"
+Requires-Dist: furo==2025.7.19 ; extra == "docs"
 Requires-Dist: sphinx-copybutton==0.5.2 ; extra == "docs"
-Requires-Dist: sphinx-issues==5.0.0 ; extra == "docs"
-Requires-Dist: sphinx==8.1.3 ; extra == "docs"
-Requires-Dist: sphinxext-opengraph==0.9.1 ; extra == "docs"
+Requires-Dist: sphinx-issues==5.0.1 ; extra == "docs"
+Requires-Dist: sphinx==8.2.3 ; extra == "docs"
+Requires-Dist: sphinxext-opengraph==0.12.0 ; extra == "docs"
 Requires-Dist: pytest ; extra == "tests"
 Requires-Dist: simplejson ; extra == "tests"
 Project-URL: Changelog, https://marshmallow.readthedocs.io/en/latest/changelog.html

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/api_reference.rst

@@ -9,6 +9,7 @@
     marshmallow.decorators
     marshmallow.validate
     marshmallow.utils
+    marshmallow.experimental.context
     marshmallow.exceptions
 
 Private API

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/conf.py

@@ -37,14 +37,14 @@ html_theme_options = {
     "light_logo": "marshmallow-logo-with-title.png",
     "dark_logo": "marshmallow-logo-with-title-for-dark-theme.png",
     "source_repository": "https://github.com/marshmallow-code/marshmallow",
-    "source_branch": "3.x-line",
+    "source_branch": "dev",
     "source_directory": "docs/",
     "sidebar_hide_name": True,
     "light_css_variables": {
         # Serif system font stack: https://systemfontstack.com/
         "font-stack": "Iowan Old Style, Apple Garamond, Baskerville, Times New Roman, Droid Serif, Times, Source Serif Pro, serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol;",
     },
-    "top_of_page_buttons": ["view"],
+    "top_of_page_buttons": ["view", "edit"],
 }
 pygments_dark_style = "lightbulb"
 html_favicon = "_static/favicon.ico"

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/custom_fields.rst

@@ -13,13 +13,14 @@ Creating a field class
 ----------------------
 
 To create a custom field class, create a subclass of :class:`marshmallow.fields.Field` and implement its :meth:`_serialize <marshmallow.fields.Field._serialize>` and/or :meth:`_deserialize <marshmallow.fields.Field._deserialize>` methods.
+Field's type argument is the internal type, i.e. the type that the field deserializes to.
 
 .. code-block:: python
 
     from marshmallow import fields, ValidationError
 
 
-    class PinCode(fields.Field):
+    class PinCode(fields.Field[list[int]]):
         """Field that serializes to a string of numbers and deserializes
         to a list of numbers.
         """
@@ -94,45 +95,72 @@ Both :class:`Function <marshmallow.fields.Function>` and :class:`Method <marshma
     result = schema.load({"balance": "100.00"})
     result["balance"]  # => 100.0
 
-.. _adding-context:
+.. _using_context:
 
-Adding context to `Method` and `Function` fields
-------------------------------------------------
+Using context
+-------------
 
-.. warning::
+A field may need information about its environment to know how to (de)serialize a value.
 
-    The ``context`` attribute is deprecated and will be removed in marshmallow 4.
-    Use `contextvars.ContextVar` for passing context to fields, pre-/post-processing methods, and validators instead.
-    marshmallow 4 will also provide an `experimental helper API <https://marshmallow.readthedocs.io/en/latest/marshmallow.experimental.context.html>`_
-    for using context.
+You can use the experimental `Context <marshmallow.experimental.context.Context>` class
+to set and retrieve context.
 
-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.
+Let's say your ``UserSchema`` needs to output
+whether or not a ``User`` is the author of a ``Blog`` or
+whether a certain word appears in a ``Blog's`` title.
 
-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.
+.. code-block:: python
 
-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.
+    import typing
+    from dataclasses import dataclass
+
+    from marshmallow import Schema, fields
+    from marshmallow.experimental.context import Context
+
+
+    @dataclass
+    class User:
+        name: str
+
+
+    @dataclass
+    class Blog:
+        title: str
+        author: User
+
+
+    class ContextDict(typing.TypedDict):
+        blog: Blog
 
-.. code-block:: python
 
     class UserSchema(Schema):
         name = fields.String()
-        # Function fields optionally receive context argument
-        is_author = fields.Function(lambda user, context: user == context["blog"].author)
+
+        is_author = fields.Function(
+            lambda user: user == Context[ContextDict].get()["blog"].author
+        )
         likes_bikes = fields.Method("writes_about_bikes")
 
-        def writes_about_bikes(self, user):
-            return "bicycle" in self.context["blog"].title.lower()
+        def writes_about_bikes(self, user: User) -> bool:
+            return "bicycle" in Context[ContextDict].get()["blog"].title.lower()
 
+.. note::
+    You can use `Context.get <marshmallow.experimental.context.Context.get>`
+    within custom fields, pre-/post-processing methods, and validators.
+
+When (de)serializing, set the context by using `Context <marshmallow.experimental.context.Context>` as a context manager.
+
+.. code-block:: python
 
-    schema = UserSchema()
 
     user = User("Freddie Mercury", "fred@queen.com")
     blog = Blog("Bicycle Blog", author=user)
 
-    schema.context = {"blog": blog}
-    result = schema.dump(user)
-    result["is_author"]  # => True
-    result["likes_bikes"]  # => True
+    schema = UserSchema()
+    with Context({"blog": blog}):
+        result = schema.dump(user)
+        print(result["is_author"])  # => True
+        print(result["likes_bikes"])  # => True
 
 
 Customizing error messages

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/extending/index.rst

@@ -12,5 +12,4 @@ The guides below demonstrate how to extend schemas in various ways.
   overriding_attribute_access
   custom_error_handling
   custom_options
-  using_context
   custom_error_messages

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/install.rst

@@ -1,8 +1,6 @@
 Installation
 ============
 
-**marshmallow** has no external dependencies other than the `packaging` library.
-
 Installing/upgrading from the PyPI
 ----------------------------------
 

marshmallow-4.0.1/docs/marshmallow.experimental.context.rst

@@ -0,0 +1,5 @@
+Context (experimental)
+======================
+
+.. automodule:: marshmallow.experimental.context
+    :members:

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/nesting.rst

@@ -199,7 +199,7 @@ Correspondingly, a representation of a ``Book`` will include its author represen
 
 .. code-block:: python
 
-    from marshmallow import pprint
+    from pprint import pprint
     from mymodels import Author, Book
 
     author = Author(name="William Faulkner")

{marshmallow-3.26.1 → marshmallow-4.0.1}/docs/quickstart.rst

@@ -244,7 +244,7 @@ There are a number of built-in validators in the :ref:`marshmallow.validate <api
 You may implement your own validators.
 A validator is a callable that accepts a single argument, the value to validate.
 If validation fails, the callable should raise a :exc:`ValidationError <marshmallow.exceptions.ValidationError>`
-with a useful error message or return ``False`` (for a generic error message).
+with an error message.
 
 .. code-block:: python
 
@@ -290,7 +290,7 @@ You may also pass a collection (list, tuple, generator) of callables to ``valida
 Field validators as methods
 +++++++++++++++++++++++++++
 
-It is sometimes convenient to write validators as methods. Use the `validates <marshmallow.decorators.validates>` decorator to register field validator methods.
+It is sometimes convenient to write validators as methods. Use the `validates <marshmallow.validates>` decorator to register field validator methods.
 
 .. code-block:: python
 
@@ -301,12 +301,30 @@ It is sometimes convenient to write validators as methods. Use the `validates <m
         quantity = fields.Integer()
 
         @validates("quantity")
-        def validate_quantity(self, value):
+        def validate_quantity(self, value: int, data_key: str) -> None:
             if value < 0:
                 raise ValidationError("Quantity must be greater than 0.")
             if value > 30:
                 raise ValidationError("Quantity must not be greater than 30.")
 
+.. note::
+
+    You can pass multiple field names to the `validates <marshmallow.validates>` decorator.
+
+    .. code-block:: python
+
+        from marshmallow import Schema, fields, validates, ValidationError
+
+
+        class UserSchema(Schema):
+            name = fields.Str(required=True)
+            nickname = fields.Str(required=True)
+
+            @validates("name", "nickname")
+            def validate_names(self, value: str, data_key: str) -> None:
+                if len(value) < 3:
+                    raise ValidationError("Too short")
+
 
 Required fields
 ---------------
@@ -529,60 +547,6 @@ If you are consuming and producing data that does not match your schema, you can
     # 'email': 'foo@bar.com'}
 
 
-.. _meta_options:
-
-Implicit field creation
------------------------
-
-.. warning::
-
-    Implicit field creation is deprecated and is removed in marshmallow 4.
-    Fields should be declared explicitly.
-
-    .. code-block:: python
-
-        # 3.x
-        class UserSchema(Schema):
-            class Meta:
-                fields = ("name", "birthdate")
-
-
-        # 4.x
-        class UserSchema(Schema):
-            name = fields.String()
-            email = fields.Date()
-
-When your model has many attributes, specifying the field type for every attribute can get repetitive, especially when many of the attributes are already native Python datatypes.
-
-The ``fields`` option allows you to specify implicitly-created fields. marshmallow will choose an appropriate field type based on the attribute's type.
-
-Let's refactor our User schema to be more concise.
-
-.. code-block:: python
-
-    class UserSchema(Schema):
-        uppername = fields.Function(lambda obj: obj.name.upper())
-
-        class Meta:
-            fields = ("name", "email", "created_at", "uppername")
-
-Note that ``name`` will be automatically formatted as a :class:`String <marshmallow.fields.String>` and ``created_at`` will be formatted as a :class:`DateTime <marshmallow.fields.DateTime>`.
-
-.. note::
-
-    If instead you want to specify which field names to include *in addition* to the explicitly declared fields, you can use the ``additional`` option.
-
-    The schema below is equivalent to above:
-
-    .. code-block:: python
-
-        class UserSchema(Schema):
-            uppername = fields.Function(lambda obj: obj.name.upper())
-
-            class Meta:
-                # No need to include 'uppername'
-                additional = ("name", "email", "created_at")
-
 Next steps
 ----------
 - Need to represent relationships between objects? See the :doc:`nesting` page.

marshmallow-4.0.1/docs/top_level.rst

@@ -0,0 +1,35 @@
+Top-level API
+=============
+
+.. automodule:: marshmallow
+   :members:
+   :autosummary:
+   :exclude-members: OPTIONS_CLASS
+
+.. Can't use :autodata: here due to Sphinx bug: https://github.com/sphinx-doc/sphinx/issues/6495
+.. data:: missing
+
+   Singleton value that indicates that a field's value is missing from input
+   dict passed to `Schema.load <marshmallow.Schema.load>`. If the field's value is not required,
+   its ``default`` value is used.
+
+Constants for ``unknown``
+-------------------------
+
+.. seealso:: :ref:`unknown`
+
+.. data:: EXCLUDE
+
+   Indicates that fields that are not explicitly declared on a schema should be
+   excluded from the deserialized result.
+
+
+.. data:: INCLUDE
+
+   Indicates that fields that are not explicitly declared on a schema should be
+   included from the deserialized result.
+
+.. data:: RAISE
+
+   Indicates that fields that are not explicitly declared on a schema should
+   result in an error.