Support ordered case-insensitive duration strings for timedelta

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 11.1.0 (2025-11-11)
+## 11.1.0 (2024-11-11)
 
 Features:
 

README.md

@@ -78,7 +78,7 @@ secret = env("SECRET")  # => raises error if not set
 # casting
 max_connections = env.int("MAX_CONNECTIONS")  # => 100
 ship_date = env.date("SHIP_DATE")  # => datetime.date(1984, 6, 25)
-ttl = env.timedelta("TTL")  # => datetime.timedelta(0, 42)
+ttl = env.timedelta("TTL")  # => datetime.timedelta(seconds=42)
 log_level = env.log_level("LOG_LEVEL")  # => logging.DEBUG
 
 # providing a default value
@@ -110,7 +110,7 @@ The following are all type-casting methods of `Env`:
 - `env.datetime`
 - `env.date`
 - `env.time`
-- `env.timedelta` (assumes value is an integer in seconds)
+- `env.timedelta` (assumes value is an integer in seconds, or an ordered case-insensitive duration string like `7m7s` or `7w 7d 7h 7m 7s 7ms 7us`)
 - `env.url`
 - `env.uuid`
 - `env.log_level`

src/environs/__init__.py

@@ -8,6 +8,7 @@
 import re
 import typing
 from collections.abc import Mapping
+from datetime import timedelta
 from enum import Enum
 from pathlib import Path
 from urllib.parse import ParseResult, urlparse
@@ -31,6 +32,17 @@
 
 
 _EXPANDED_VAR_PATTERN = re.compile(r"(?<!\\)\$\{([A-Za-z0-9_]+)(:-[^\}:]*)?\}")
+_TIMEDELTA_PATTERN = re.compile(
+    r"^(?:\s*)"  # optional whitespace at the beginning of the string
+    r"(?:(\d+)\s*w\s*)?"  # weeks with optional whitespace around unit
+    r"(?:(\d+)\s*d\s*)?"  # days with optional whitespace around unit
+    r"(?:(\d+)\s*h\s*)?"  # hours with optional whitespace around unit
+    r"(?:(\d+)\s*m\s*)?"  # minutes with optional whitespace around unit
+    r"(?:(\d+)\s*s\s*)?"  # seconds with optional whitespace around unit
+    r"(?:(\d+)\s*ms\s*)?"  # milliseconds with optional whitespace around unit
+    r"(?:(\d+)\s*[µu]s\s*)?$",  # microseconds with optional whitespace around unit
+    flags=re.IGNORECASE,
+)
 
 
 class EnvError(ValueError):
@@ -356,6 +368,24 @@ def _format_num(self, value) -> int:
                 raise ma.ValidationError("Not a valid log level.") from error
 
 
+class TimeDeltaField(ma.fields.TimeDelta):
+    def _deserialize(self, value, *args, **kwargs) -> timedelta:
+        if isinstance(value, timedelta):
+            return value
+        match = _TIMEDELTA_PATTERN.match(value)
+        if match is not None and any(groups := match.groups()):
+            return timedelta(
+                weeks=int(groups[0] or 0),
+                days=int(groups[1] or 0),
+                hours=int(groups[2] or 0),
+                minutes=int(groups[3] or 0),
+                seconds=int(groups[4] or 0),
+                milliseconds=int(groups[5] or 0),
+                microseconds=int(groups[6] or 0),
+            )
+        return super()._deserialize(value, *args, **kwargs)
+
+
 class Env:
     """An environment variable reader."""
 
@@ -390,7 +420,7 @@ class Env:
     time = _field2method(ma.fields.Time, "time")
     path = _field2method(PathField, "path")
     log_level = _field2method(LogLevelField, "log_level")
-    timedelta = _field2method(ma.fields.TimeDelta, "timedelta")
+    timedelta = _field2method(TimeDeltaField, "timedelta")
     uuid = _field2method(ma.fields.UUID, "uuid")
     url = _field2method(URLField, "url")
     enum = _func2method(_enum_parser, "enum")

tests/test_environs.py

@@ -231,6 +231,25 @@ def test_date_cast(self, set_env, env):
     def test_timedelta_cast(self, set_env, env):
         set_env({"TIMEDELTA": "42"})
         assert env.timedelta("TIMEDELTA") == dt.timedelta(seconds=42)
+        set_env({"TIMEDELTA": "42s"})
+        assert env.timedelta("TIMEDELTA") == dt.timedelta(seconds=42)
+        # whitespace, case-insensitive, missing units
+        set_env({"TIMEDELTA": " 42 D  42s "})
+        assert env.timedelta("TIMEDELTA") == dt.timedelta(days=42, seconds=42)
+        # unicode µs (in addition to us below)
+        set_env({"TIMEDELTA": "42µs"})
+        assert env.timedelta("TIMEDELTA") == dt.timedelta(microseconds=42)
+        # all supported units
+        set_env({"TIMEDELTA": "42w 42d 42h 42m 42s 42ms 42us"})
+        assert env.timedelta("TIMEDELTA") == dt.timedelta(
+            weeks=42,
+            days=42,
+            hours=42,
+            minutes=42,
+            seconds=42,
+            milliseconds=42,
+            microseconds=42,
+        )
 
     def test_time_cast(self, set_env, env):
         set_env({"TIME": "10:30"})