marshmallow 3.26.0__tar.gz → 4.0.0__tar.gz

{marshmallow-3.26.0 → marshmallow-4.0.0}/CHANGELOG.rst

@@ -1,6 +1,146 @@
 Changelog
 ---------
 
+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`.
+- *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`).
+- `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.
+
+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)
+*******************
+
+Bug fixes:
+
+- Typing: Fix type annotations for `class Meta <marshmallow.Schema.Meta>` options (:issue:`2804`).
+  Thanks :user:`lawrence-law` for reporting.
+
+Other changes:
+
+- Remove default value for the ``data`` param of `Nested._deserialize <marshmallow.fields.Nested._deserialize>` (:issue:`2802`).
+  Thanks :user:`gbenson` for reporting.
+
+
 3.26.0 (2025-01-22)
 *******************
 
@@ -95,7 +235,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.0 → marshmallow-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: marshmallow
-Version: 3.26.0
+Version: 4.0.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>
@@ -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: 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.10.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.0 → marshmallow-4.0.0}/docs/api_reference.rst

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

{marshmallow-3.26.0 → marshmallow-4.0.0}/docs/conf.py

@@ -37,7 +37,8 @@ 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",
+    "announcement": 'This is the documentation for the unreleased 4.0 version. The latest v3 docs are <a href="https://marshmallow.readthedocs.io/en/3.x-line/">here</a>.',
+    "source_branch": "dev",
     "source_directory": "docs/",
     "sidebar_hide_name": True,
     "light_css_variables": {

{marshmallow-3.26.0 → marshmallow-4.0.0}/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.0 → marshmallow-4.0.0}/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.0 → marshmallow-4.0.0}/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.0/docs/marshmallow.experimental.context.rst

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

{marshmallow-3.26.0 → marshmallow-4.0.0}/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.0 → marshmallow-4.0.0}/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.0/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.