marshmallow

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bug fixes:

• 2025-68480: Merge error store messages without rebuilding collections. Thanks 카푸치노 for reporting and deckar01 for the fix.

Bump version and update changelog

Other changes:

• Add __len__ implementation to missing so that it can be used with validate.Length <marshmallow.validate.Length> (2861). Thanks agentgodzilla for the PR.

• Drop support for Python 3.9 (2363).

• Test against Python 3.14 (2864).

Bug fixes:

• Fix wildcard import of from marshmallow import * (2823). Thanks Florian-Laport for the PR.

See upgrading_4_0 for a guide on updating your code.

Features:

• Typing: Add types to all Field <marshmallow.fields.Field> constructor kwargs (2285). Thanks 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 (1415). Thanks bitdancer for the suggestion.

• @validates <marshmallow.validates> accepts multiple field names (1960). Backwards-incompatible: Decorated methods now receive data_key as a keyword argument. Thanks dpriskorn for the suggestion and 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 (1898). The typing of data is also updated to be more accurate. Thanks 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 (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 (2766).

• Remove from_rfc, and rfcformat from marshmallow.utils (2767).

• Remove is_keyed_tuple from marshmallow.utils (2768).

• Remove get_fixed_timezone from marshmallow.utils (2773).

• Backwards-incompatible: marshmallow.fields.Boolean no longer serializes non-boolean values (2725).

• Backwards-incompatible: Rename schema parameter to parent in marshmallow.fields.Field._bind_to_schema (1360).

• Backwards-incompatible: Rename pass_many parameter to pass_collection in pre/post processing methods (1369).

• Backwards-incompatible: marshmallow.fields.TimeDelta no longer truncates float values when deserializing (2654). This allows microseconds to be preserved, e.g.

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 (2654).

• Backwards-incompatible: Remove serialization_type parameter from marshmallow.fields.TimeDelta (2654).

Thanks 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 (1826). marshmallow 4 provides an experimental Context <marshmallow.experimental.context.Context> manager class that can be used to both set and retrieve context.

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 (1632). Thanks 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.) (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) (2772).

• Passing invalid values for unknown will cause an error in type checkers (2771).

Deprecations/Removals:

• Backwards-incompatible: Remove implicit field creation, i.e. using the fields or additional class Meta options with undeclared fields (1356).

• The ordered class Meta option is removed (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 (2722).

Previously-deprecated APIs have been removed, including:

• The ordered class Meta <marshmallow.Schema.Meta> option is removed (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 (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 (1742, 2700).

• Passing field metadata via keyword arguments (deprecated in 3.10.0). Use the explicit metadata=... argument instead (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.

Bug fixes:

• 2025-68480: Merge error store messages without rebuilding collections. Thanks 카푸치노 for reporting and deckar01 for the fix.

Bug fixes:

• Typing: Fix type annotations for class Meta <marshmallow.Schema.Meta> options (2804). Thanks lawrence-law for reporting.

Other changes:

• Remove default value for the data param of Nested._deserialize <marshmallow.fields.Nested._deserialize> (2802). Thanks gbenson for reporting.

Features:

• Typing: Add type annotations and improved documentation for class Meta <marshmallow.Schema.Meta> options (2760).

• Typing: Improve type coverage of marshmallow.Schema.SchemaMeta (2761).

• Typing: marshmallow.Schema.loads parameter allows bytes and bytesarray (2769).

Bug fixes:

• Respect data_key when schema validators raise a ValidationError <marshmallow.exceptions.ValidationError> with a field_name argument (2170). Thanks 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 (1755). Thanks ghostwheel42 for reporting.

• URL fields now properly validate file paths (2249). Thanks 0xDEC0DE for reporting and fixing.

Documentation:

• Add upgrading guides for 3.24 and 3.26 (2780).

• Various documentation improvements (2757, 2759, 2765, 2774, 2778, 2783, 2796).

Deprecations:

• The ordered class Meta <marshmallow.Schema.Meta> option is deprecated (2146, 2762). Field order is already preserved by default. Set marshmallow.Schema.dict_class to collections.OrderedDict to maintain the previous behavior.

Bug fixes:

• Typing: Fix type annotations for Tuple <marshmallow.fields.Tuple>, Boolean <marshmallow.fields.Boolean>, and Pluck <marshmallow.fields.Pluck> constructors (2756).

• Typing: Fix overload for marshmallow.class_registry.get_class (2756).

Documentation:

• Various documentation improvements (2746, 2747, 2748, 2749, 2750, 2751).

Features:

• Typing: Improve type annotations for SchemaMeta.get_declared_fields (2742).

Bug fixes:

• Typing: Relax type annotation for Schema.opts to allow subclasses to define their own options classes (2744).

Other changes:

• Restore marshmallow.base.SchemaABC for backwards-compatibility (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.

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 (2739). Thanks llucax for reporting.

Bug fixes:

• Typing: Fix typing for class_registry.get_class <marshmallow.class_registry.get_class> (2735).

Features:

• Typing: Improve typings in marshmallow.fields (2723).

• Typing: Replace type comments with inline typings (2718).

Bug fixes:

• Typing: Fix type hint for nested parameter of Nested <marshmallow.fields.Nested> (2721).

Deprecations:

• 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> (1826). Use contextVars.ContextVar to pass context data instead.

• Field <marshmallow.fields.Field>, Mapping <marshmallow.fields.Mapping>, and Number <marshmallow.fields.Number> should no longer be used as fields within schemas. Use their subclasses instead.

Bug fixes:

• Typing: Fix typing for Schema.from_dict <marshmallow.schema.Schema.from_dict> (1653). Thanks SteadBytes for reporting.

Support:

• Documentation: Various documentation cleanups, including more concise docs in the marshmallow.fields API reference (2307). Thanks AbdealiLoKo for reporting.

Bug fixes:

• Improve type hint formatting for Field, Nested, and Function fields to resolve PyCharm warnings (2268). Thanks Fares-Abubaker for reporting and fixing.

Support:

• Document absolute parameter of URL field (2327).

• Documentation: Remove (outdated) minimum Python 3 minor version in documentation and README (2323).

Features:

• Typing: replace "type" with specific metaclass for Schema and Field.

Other changes:

• Officially support Python 3.13 (2319).

• Drop support for Python 3.8 (2318).

Features:

• Add many Meta option to Schema so it expects a collection by default (2270). Thanks himalczyk for reporting and deckar01 for the PR.

• Refactor hooks (2279). Thanks deckar01 for the PR.

Bug fixes:

• Fix memory leak that prevented schema instances from getting GC'd (2277). Thanks mrcljx for the PR.

Bug fixes:

• Allow timestamp 0 in fields.DateTime (2133). Thanks flydzen for reporting.

Bug fixes:

• Fix error message when field is declared as a class and not an instance (2245). Thanks travnick for reporting.

Bug fixes:

• Fix validation of URL fields to allow missing user field, per NWG RFC 3986 (2232). Thanks ddennerline3 for reporting and deckar01 for the PR.

Other changes:

• Backwards-incompatible: __version__, __parsed_version__, and __version_info__ attributes are deprecated (2227). Use feature detection or importlib.metadata.version("marshmallow") instead.

Bug fixes:

• Fix Nested field type hint for lambda Schema types (2164). Thanks somethingnew2-0 for the PR.

Other changes:

• Officially support Python 3.12 (2188). Thanks hugovk for the PR.

Bug fixes:

• Fix call to get_declared_fields: pass dict_cls again (2152). Thanks Cheaterman for reporting.

Features:

• Add absolute parameter to URL validator and Url field (2123). Thanks sirosen for the PR.

• Use Abstract Base Classes to define FieldABC and SchemaABC (1449). Thanks aditkumar72 for the PR.

• Use OrderedSet as default set_class. Schemas are now ordered by default. (1744)

Bug fixes:

• Handle OSError and OverflowError in utils.from_timestamp (2102). Thanks TheBigRoomXXL for the PR.

• Fix the default inheritance of nested partial schemas (2149). Thanks matejsp for reporting.

Other changes:

• Officially support Python 3.11 (2067).

• Drop support for Python 3.7 (2135).

Features:

• Add timestamp and timestamp_ms formats to fields.DateTime (612). Thanks vgavro for the suggestion and thanks vanHoi for the PR.

Features:

• Add Enum field (2017) and (2044).

Bug fixes:

• Fix typing in Field._serialize signature (2046).

Bug fixes:

• Add return type to fields.Email.__init__ (2018). Thanks kkirsche for the PR.

• Add missing type hint to IPInterface __init__ (2036).

Features:

• Support serialization as float in TimeDelta field (1998). Thanks marcosatti for the PR.

• Add messages_dict property to ValidationError to facilitate type checking (1976). Thanks sirosen for the PR.

Features:

• Raise ValueError if an invalid value is passed to the unknown argument (1721, 1732). Thanks sirosen for the PR.

Other changes:

• Set lower bound for packaging requirement (1957). Thanks MatthewNicolTR for reporting and thanks sirosen for the PR.

• Improve warning messages by passing stacklevel (1986). Thanks tirkarthi for the PR.

Features:

• Allow passing a dict to fields.Nested (1935). Thanks sirosen for the PR.

Other changes:

• Address distutils deprecation warning in Python 3.10 (1903). Thanks kkirsche for the PR.

• Add py310 to black target-version (1921).

• Drop support for Python 3.6 (1923).

• Use postponed evaluation of annotations (1932). Thanks Isira-Seneviratne for the PR.

Bug fixes:

• Fix publishing type hints per PEP-561 (1905). Thanks bwindsor for the catch and patch.

Bug fixes:

• Fix fields.TimeDelta serialization precision (1865). Thanks yarsanich for reporting.

Other changes:

• Fix type-hints for data arg in Schema.validate to accept list of dictionaries (1790, 1868). Thanks yourun-proger for PR.

• Improve warning when passing metadata as keyword arguments (1882). Thanks traherom for the PR.

• Don't build universal wheels. We don't support Python 2 anymore. (1860) Thanks YKdvd for reporting.

• Make the build reproducible (1862).

• Drop support for Python 3.5 (1863).

• Test against Python 3.10 (1888).

Features:

• Replace missing/default field parameters with load_default/dump_default (1742). Thanks sirosen for the PR.

Deprecations:

• The use of missing/default field parameters is deprecated and will be removed in marshmallow 4. load_default/dump_default should be used instead.

Bug fixes:

• Don't expose Fields as Schema attributes. This reverts a change introduced in 3.12.0 that causes issues when field names conflict with Schema attributes or methods. Fieldss are still accessible on a Schema instance through the fields attribute. (1843)

Bug fixes:

• Fix bug that raised an AttributeError when instantiating a Schema with a field named parent (1808). Thanks flying-sheep for reporting and helping with the fix.

Features:

• Add validate.And (1768). Thanks rugleb for the suggestion.

• Add type annotations to marshmallow.decorators (1788, 1789). Thanks michaeldimchuk for the PR.

• Let Fields be accessed by name as Schema attributes (1631).

Other changes:

• Improve types in marshmallow.validate (1786).

• Make marshmallow.validate.Validator an abstract base class (1786).

• Remove unnecessary list cast (1785).

Bug fixes:

• Fix treatment of dotted keys when unknown=INCLUDE (1506). Thanks rbu for reporting and thanks sirosen for the fix (1745).

Features:

• Add fields.IPInterface, fields.IPv4Interface, and IPv6Interface (1733). Thanks madeinoz67 for the suggestion and the PR.

• Raise AttributeError for missing methods when using fields.Method (1675). Thanks lassandroan.

Other changes:

• Remove unnecessary hasattr and getattr checks in Field (1770).

Deprecations:

• Passing field metadata via keyword arguments is deprecated and will be removed in marshmallow 4 (1350). Use the explicit metadata=... argument instead. Thanks sirosen.

Bug fixes:

• Cast to mapping type in Mapping.serialize and Mapping.deserialize (1685).

• Fix bug letting Dict pass invalid dict on deserialization when no key or value Field is specified (1685).

Features:

• Add format argument to fields.Time and timeformat class Meta option (686). Thanks BennyAlex for the suggestion and thanks infinityxxx for the PR.

Other changes:

• Remove usage of implicit typing.Optional (1663). Thanks nadega for the PR.

Features:

• Add fields.IP, fields.IPv4 and fields.IPv6 (1485). Thanks mgetka for the PR.

Bug fixes:

• Fix typing in AwareDateTime (1658). Thanks adithyabsk for reporting.

Bug fixes:

• fields.Boolean correctly serializes non-hashable types (1633). Thanks jun0jang for the PR.

Deprecations:

• marshmallow.pprint is deprecated and will be removed in marshmallow 4 (1588).

Support:

• Document default_error_messages on field classes (1619). Thanks weeix.

Bug fixes:

• Fix passing only and exclude to Nested with an ordered Schema (1627). Thanks juannorris for the PR.

No code changes--only docs and contributor-facing updates in this release.

Support:

• Documentation: improve custom fields example (1538). Thanks pablospizzamiglio for reporting the problem with the old example and thanks Resinderate for the PR.

• Documentation: Split up API reference into multiple pages and add summary tables (1587). Thanks EpicWink for the PR.

Features:

• Add validate.ContainsNoneOf (1528). Thanks Resinderate for the suggestion and the PR.

Bug fixes:

• Fix typing in class_registry (1574). Thanks mahenzon.

Bug fixes:

• Includes bug fix from 2.21.0.

Bug fixes:

• Fix list of nullable nested fields List(Nested(Field, allow_none=True) (1497). Because this fix reverts an optimization introduced to speed-up serialization and deserialization of lists of nested fields, a negative impact on performance in this specific case is expected.

Features:

• Improve type coverage (1479). Thanks Reskov.

Bug fixes:

• Fix typing for data param of Schema.load and ValidationError (1492). Thanks mehdigmira for reporting and thanks dfirst for the PR.

Other changes:

• Remove unnecessary typecasts (1500). Thanks hukkinj1.

• Remove useless _serialize override in UUID field (1489).

Features:

• fields.Nested may take a callable that returns a schema instance. Use this to resolve order-of-declaration issues when schemas nest each other (1146).

# <3.3
class AlbumSchema(Schema):
    title = fields.Str()
    artist = fields.Nested("ArtistSchema", only=("name",))


class ArtistSchema(Schema):
    name = fields.Str()
    albums = fields.List(fields.Nested(AlbumSchema))


# >=3.3
class AlbumSchema(Schema):
    title = fields.Str()
    artist = fields.Nested(lambda: ArtistSchema(only=("name",)))


class ArtistSchema(Schema):
    name = fields.Str()
    albums = fields.List(fields.Nested(AlbumSchema))

Deprecations:

• Passing the string "self" to fields.Nested is deprecated. Use a callable instead.

from marshmallow import Schema, fields


# <3.3
class PersonSchema(Schema):
    partner = fields.Nested("self", exclude=("partner",))
    friends = fields.List(fields.Nested("self"))


# >=3.3
class PersonSchema(Schema):
    partner = fields.Nested(lambda: PersonSchema(exclude=("partner")))
    friends = fields.List(fields.Nested(lambda: PersonSchema()))

Other changes:

• Fix typing for Number._format_num (1466). Thanks hukkinj1.

• Make mypy stricter and remove dead code (1467). Thanks again, hukkinj1.

Bug fixes:

• Don't load fields for which load_only and dump_only are both True (1448).

• Fix types in marshmallow.validate (1446).

Support:

• Test against Python 3.8 (1431).