fix: properly handle typing of list and dict with defined defaults (#407)

* fix: properly handle typing of list and dict with defined defaults

* fix typing for list and dict handling with subcasts and None default; expand tests

* Update changelog

---------

Co-authored-by: Lucas Brémond <lucas@mac.lan>
Co-authored-by: Steven Loria <sloria1@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 Bug fixes:
 
+- Typing: Fix typing for `env.list` and `env.dict` to properly handle
+  `default` and `subcast` arguments ([#406](https://github.com/sloria/environs/issues/406)).
+  Thanks [lucas-bremond](https://github.com/lucas-bremond) for the PR.
 - Add `env` to `__all__` ([#396](https://github.com/sloria/environs/issues/396)).
   Thanks [daveflr](https://github.com/daveflr) for reporting.
 

src/environs/types.py

@@ -21,6 +21,7 @@
     from marshmallow.fields import Field
 
 T = typing.TypeVar("T")
+SubcastT = typing.TypeVar("SubcastT")
 EnumT = typing.TypeVar("EnumT", bound=enum.Enum)
 
 ErrorMapping: typing.TypeAlias = typing.Mapping[str, list[str]]
@@ -70,7 +71,6 @@ def __call__(
         self,
         name: str,
         default: typing.Any = ...,
-        subcast: Subcast[T] | None = ...,
         **kwargs: Unpack[BaseMethodKwargs],
     ) -> T | None: ...
 
@@ -80,40 +80,75 @@ class ListFieldMethod:
     def __call__(
         self,
         name: str,
-        default: typing.Any = ...,
+        default: list[T] = ...,
+        subcast: Subcast[T] = ...,
+        *,
+        delimiter: str | None = ...,
+        **kwargs: Unpack[BaseMethodKwargs],
+    ) -> list[T]: ...
+
+    @typing.overload
+    def __call__(
+        self,
+        name: str,
+        default: T = ...,
         subcast: None = ...,
         *,
         delimiter: str | None = ...,
         **kwargs: Unpack[BaseMethodKwargs],
-    ) -> list[typing.Any] | None: ...
+    ) -> list[typing.Any] | T: ...
 
     @typing.overload
     def __call__(
         self,
         name: str,
-        default: typing.Any = ...,
-        subcast: Subcast[T] = ...,
+        default: T = ...,
+        subcast: Subcast[SubcastT] = ...,
         *,
         delimiter: str | None = ...,
         **kwargs: Unpack[BaseMethodKwargs],
-    ) -> list[T] | None: ...
+    ) -> list[SubcastT] | T: ...
 
     def __call__(
         self,
         name: str,
-        default: typing.Any = ...,
-        subcast: Subcast[T] | None = ...,
+        default: T = ...,
+        subcast: Subcast[SubcastT] | None = ...,
         *,
         delimiter: str | None = ...,
         **kwargs: Unpack[BaseMethodKwargs],
-    ) -> list[T] | None: ...
+    ) -> list[SubcastT] | list[typing.Any] | T | None: ...
 
 
 KeysT = typing.TypeVar("KeysT")
 ValuesT = typing.TypeVar("ValuesT")
 
 
 class DictFieldMethod:
+    @typing.overload
+    def __call__(
+        self,
+        name: str,
+        default: dict[KeysT, ValuesT] = ...,
+        *,
+        subcast_keys: Subcast[KeysT] | None = None,
+        subcast_values: Subcast[ValuesT] | None = None,
+        delimiter: str | None = None,
+        **kwargs: Unpack[BaseMethodKwargs],
+    ) -> dict[KeysT, ValuesT]: ...
+
+    @typing.overload
+    def __call__(
+        self,
+        name: str,
+        default: None = ...,
+        *,
+        subcast_keys: Subcast[KeysT] | None = None,
+        subcast_values: Subcast[ValuesT] | None = None,
+        delimiter: str | None = None,
+        **kwargs: Unpack[BaseMethodKwargs],
+    ) -> dict[KeysT, ValuesT] | None: ...
+
     def __call__(
         self,
         name: str,

tests/mypy_test_cases/env.py

@@ -41,13 +41,30 @@ class Color(enum.IntEnum):
 DECIMAL0: decimal.Decimal | None = env.decimal("FOO", None)
 LIST0: list | None = env.list("FOO", None)
 LIST1: list[int] | None = env.list("FOO", None, subcast=int)
+LIST2: list[Any] = env.list("FOO")
+LIST3: list[int] = env.list("FOO", subcast=int)
+LIST4: list[int] | bool = env.list("FOO", default=False, subcast=int)
+LIST5: list[int] = env.list("FOO", default=[], subcast=int)
 DICT0: dict | None = env.dict("FOO", None)
 DICT1: dict[str, int] | None = env.dict(
     "FOO",
     None,
     subcast_keys=str,
     subcast_values=int,
 )
+DICT2: dict[str, int] = env.dict(
+    "FOO",
+    subcast_keys=str,
+    subcast_values=int,
+)
+DICT3: dict[int, Any] = env.dict(
+    "FOO",
+    subcast_keys=int,
+)
+DICT4: dict[Any, int] = env.dict(
+    "FOO",
+    subcast_values=int,
+)
 JSON0: list | dict | None = env.json("FOO", None)
 DATETIME0: dt.datetime | None = env.datetime("FOO", None)
 DATE0: dt.date | None = env.date("FOO", None)