Drop marshmallow 3 (#461)

* Drop marshmallow 3 and deserialize default values

* Revert deserialization change

Author: sloria

.github/workflows/build-release.yml

@@ -13,11 +13,9 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - { name: "3.10", tox: py310-marshmallow3 }
-          - { name: "3.14", tox: py314-marshmallow3 }
+          - { name: "3.10", tox: py310-marshmallowdev }
+          - { name: "3.14", tox: py314-marshmallowdev }
           - { name: "lowest", tox: py310-marshmallowlowest }
-          - { name: "highest", tox: py314-marshmallowdev }
-          - { name: "mypy-ma3", tox: mypy-marshmallow3 }
           - { name: "mypy-madev", tox: mypy-marshmallowdev }
     steps:
       - uses: actions/checkout@v6

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## unreleased
+
+Other changes:
+
+- Drop support for marshmallow 3. marshmallow>=4.0.0 is now required.
+
 ## 14.6.0 (2026-02-19)
 
 Bug fixes:

pyproject.toml

@@ -3,11 +3,10 @@ name = "environs"
 version = "14.6.0"
 description = "simplified environment variable parsing"
 readme = "README.md"
-license = { file = "LICENSE" }
+license = "MIT"
 authors = [{ name = "Steven Loria", email = "oss@stevenloria.com" }]
 classifiers = [
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Natural Language :: English",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.10",
@@ -19,7 +18,7 @@ classifiers = [
 requires-python = ">=3.10"
 dependencies = [
   "python-dotenv",
-  "marshmallow>=3.26.2",
+  "marshmallow>=4.0.0",
   "typing-extensions; python_version < '3.11'",
 ]
 
@@ -34,17 +33,11 @@ django = ["dj-database-url", "dj-email-url", "django-cache-url"]
 [dependency-groups]
 django = ["dj-database-url", "dj-email-url", "django-cache-url"]
 tests = [
-  {include-group = "django"},
+  { include-group = "django" },
   "pytest",
-  "packaging",
   "backports.strenum; python_version < '3.11'",
 ]
-dev = [
-  {include-group = "tests"},
-  "tox",
-  "tox-uv",
-  "pre-commit>=4.0,<5.0",
-]
+dev = [{ include-group = "tests" }, "tox", "tox-uv", "pre-commit>=4.0,<5.0"]
 
 [build-system]
 requires = ["flit_core<4"]
@@ -74,6 +67,7 @@ ignore = [
   "ARG",     # unused arguments are common w/ interfaces
   "COM",     # let formatter take care commas
   "C901",    # don't enforce complexity level
+  "PLR0912", # don't enforce max branches
   "D",       # don't require docstrings
   "E501",    # leave line-length enforcement to formatter
   "EM",      # allow string messages in exceptions
@@ -99,10 +93,6 @@ ignore = [
   "T", # allow prints
 ]
 
-
-[tool.ruff.lint.pycodestyle]
-ignore-overlong-task-comments = true
-
 [tool.mypy]
 files = ["src", "tests"]
 ignore_missing_imports = true

src/environs/__init__.py

@@ -199,6 +199,8 @@ def _make_subcast_field(
 
         class SubcastField(ma.fields.Field):
             def _deserialize(self, value, *args, **kwargs):
+                if not isinstance(value, str):
+                    return value
                 return subcast(value)
 
         inner_field = SubcastField

src/environs/fields.py

@@ -16,8 +16,7 @@
 from marshmallow import ValidationError, fields
 
 
-# TODO: Change to ma.fields.Field[Path] after dropping marshmallow 3 support
-class Path(fields.Field):
+class Path(fields.Field[pathlib.Path]):
     def _serialize(self, value: pathlib.Path | None, *args, **kwargs) -> str | None:
         if value is None:
             return None
@@ -151,5 +150,7 @@ def deserialize(  # type: ignore[override]
         data: typing.Mapping[str, typing.Any] | None = None,
         **kwargs,
     ) -> ParseResult:
+        if isinstance(value, ParseResult):
+            return value
         ret = typing.cast("str", super().deserialize(value, attr, data, **kwargs))
         return urlparse(ret)

tests/mypy_test_cases/env.py

@@ -2,10 +2,6 @@
 
 To run these, use: ::
 
-    tox -e mypy-marshmallow3
-
-Or ::
-
     tox -e mypy-marshmallowdev
 """
 

tests/test_environs.py

@@ -1,5 +1,4 @@
 import datetime as dt
-import importlib.metadata
 import logging
 import os
 import pathlib
@@ -20,13 +19,11 @@
 import marshmallow as ma
 import pytest
 from marshmallow import fields
-from packaging.version import Version
 
 import environs
 from environs import validate
 
 HERE = pathlib.Path(__file__).parent
-MARSHMALLOW_VERSION = Version(importlib.metadata.version("marshmallow"))
 
 
 @pytest.fixture
@@ -265,14 +262,24 @@ def test_default_set_to_internal_type(
         method = getattr(env, method_name)
         assert method("NOTFOUND", value) == value
 
+    def test_url_with_parseresult_default(self, env: environs.Env):
+        default = urllib.parse.urlparse("https://example.com")
+        result = env.url("UNSET_URL", default=default)
+        assert result == default
+        assert isinstance(result, urllib.parse.ParseResult)
+
+    def test_none_default_unchanged(self, env: environs.Env):
+        assert env.int("UNSET_NONE1", default=None) is None
+        assert env.list("UNSET_NONE2", default=None) is None
+        assert env.timedelta("UNSET_NONE3", default=None) is None
+
     def test_timedelta_cast(self, set_env, env: environs.Env):
-        # marshmallow 4 preserves float values as microseconds
-        if MARSHMALLOW_VERSION.major >= 4:
-            set_env({"TIMEDELTA": "42.9"})
-            assert env.timedelta("TIMEDELTA") == dt.timedelta(
-                seconds=42,
-                microseconds=900000,
-            )
+        # marshmallow preserves float values as microseconds
+        set_env({"TIMEDELTA": "42.9"})
+        assert env.timedelta("TIMEDELTA") == dt.timedelta(
+            seconds=42,
+            microseconds=900000,
+        )
         # seconds as integer
         set_env({"TIMEDELTA": "0"})
         assert env.timedelta("TIMEDELTA") == dt.timedelta()

tox.ini

@@ -1,24 +1,16 @@
 [tox]
 envlist=
     lint
-    py{310,311,312,313,314}-marshmallow{3,lowest,dev}
-    mypy-marshmallow{3,dev}
+    py{310,311,312,313,314}-marshmallow{lowest,dev}
+    mypy-marshmallowdev
 
 [testenv]
 dependency_groups = tests
 deps =
-    marshmallowlowest: marshmallow==3.26.2;python_version<"3.12"
-    marshmallow3: marshmallow>=3.26.2,<4.0.0
+    marshmallowlowest: marshmallow==4.0.0
     marshmallowdev: https://github.com/marshmallow-code/marshmallow/archive/dev.tar.gz
 commands = pytest {posargs}
 
-[testenv:mypy-marshmallow3]
-dependency_groups = django
-deps =
-    mypy
-    marshmallow>=3.26.2,<4.0.0
-commands = mypy
-
 [testenv:mypy-marshmallowdev]
 dependency_groups = django
 deps =