Add stubs for django-environ #14573

EmCeeEs · 2025-08-13T15:28:52Z

Types for django-environ.

donBarbos · 2025-08-13T19:04:42Z

Thanks! I just want to note that the project doesn’t seem to be very actively maintained (the last commit was 7 months ago), so I wouldn’t expect type hints to be added to the library itself anytime soon.

FTR: here’s a recent issue essentially complaining about the lack of type hints: joke2k/django-environ#567, and another one joke2k/django-environ#365 that might give some insight into the maintainer’s stance on adding them.

donBarbos

Looks good! Just few moments:

stubs/django-environ/environ/__init__.pyi

stubs/django-environ/environ/compat.pyi

stubs/django-environ/environ/environ.pyi

brianschubert

Thanks! Looks good overall, see remarks below

stubs/django-environ/environ/__init__.pyi

stubs/django-environ/environ/compat.pyi

stubs/django-environ/environ/environ.pyi

stubs/django-environ/environ/fileaware_mapping.pyi

donBarbos · 2025-08-18T18:23:14Z

I noticed that you’ve added quite a few Any types in generics. Just a gentle reminder that the use of Any is usually accompanied by a short comment explaining why it’s needed. If you’re not entirely sure about the type yet, you might consider using Incomplete instead. It could be a more suitable choice in such cases.

stubs/django-environ/METADATA.toml

EmCeeEs · 2025-08-19T15:22:04Z

stubs/django-environ/environ/environ.pyi

    def __call__(
-        self, var: _str, cast: type[_dict], default: _dict[_str, _str] | NoValue = ..., parse_default: _bool = False
+        self, var: _str, cast: type[_dict[Any, Any]], default: _dict[_str, _str] | NoValue = ..., parse_default: _bool = False
    ) -> _dict[_str, _str]: ...


I noticed that you’ve added quite a few Any types in generics. Just a gentle reminder that the use of Any is usually accompanied by a short comment explaining why it’s needed. If you’re not entirely sure about the type yet, you might consider using Incomplete instead. It could be a more suitable choice in such cases.

@donBarbos You are right. However, what I need is type[dict] of the builtin function. I think it's awkward, but pyright requires type arguments in that case. So I added the Any. Not sure if comments or replace with Incomplete makes more sense here.

If you can't specify types just leave Incomplete, this is a good case.
Anyway in the future it could be improved (type Any is not very suitable as a placeholder)

I replaced Any with Incomplete or object where applicable. Remaining Anys are explained with comments.

…ype.

…e types.

github-actions · 2025-08-26T14:08:46Z

Diff from mypy_primer, showing the effect of this PR on open source code:

discord.py (https://github.com/Rapptz/discord.py)
- discord/ext/commands/hybrid.py:834: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
+ discord/ext/commands/hybrid.py:834: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
- discord/ext/commands/hybrid.py:858: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
+ discord/ext/commands/hybrid.py:858: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
- discord/ext/commands/hybrid.py:883: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
+ discord/ext/commands/hybrid.py:883: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
- discord/ext/commands/hybrid.py:935: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
+ discord/ext/commands/hybrid.py:935: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
- discord/ext/commands/bot.py:290: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
+ discord/ext/commands/bot.py:290: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
- discord/ext/commands/bot.py:314: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
+ discord/ext/commands/bot.py:314: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]

brianschubert · 2025-09-07T17:01:56Z

stubs/django-environ/@tests/test_cases/check_parse_value.py

+
+# cast dict values
+assert_type(env.parse_value("0=TRUE,99=FALSE", {}), dict[str, str])
+assert_type(env.parse_value("0=TRUE,99=FALSE", {"cast": {}}), dict[str, Union[str, object]])


I think the inferred type for this case should ideally be dict[str, str]. Inferring dict[str, object] makes this awkward to use for end users, since you can't use the values in the dictionary without casting them or using a type narrowing construct

brianschubert · 2025-09-07T17:02:25Z

stubs/django-environ/@tests/test_cases/check_parse_value.py

+def cast_person(v: str) -> Person:
+    parts = v.split(",")
+    return {"first_name": parts[0], "last_name": parts[1], "age": int(parts[2])}


No need to include a runtime implementation since these tests aren't executed (we only check how they type check). I think this case is also redundant with custom cast function case above

brianschubert · 2025-09-07T17:02:30Z

stubs/django-environ/environ/__init__.pyi

@@ -0,0 +1,13 @@
+from typing import Final
+
+from .compat import DJANGO_POSTGRES as DJANGO_POSTGRES, PYMEMCACHE_DRIVER as PYMEMCACHE_DRIVER, REDIS_DRIVER as REDIS_DRIVER


These are indirectly re-exported from .environ, so let's move the import there

Suggested change

from .compat import DJANGO_POSTGRES as DJANGO_POSTGRES, PYMEMCACHE_DRIVER as PYMEMCACHE_DRIVER, REDIS_DRIVER as REDIS_DRIVER

brianschubert · 2025-09-07T17:02:44Z

stubs/django-environ/environ/environ.pyi

+from typing_extensions import NotRequired, Required, TypeAlias, Unpack
+from urllib.parse import ParseResult
+
+from .fileaware_mapping import FileAwareMapping


See above

Suggested change

from .fileaware_mapping import FileAwareMapping

from .compat import DJANGO_POSTGRES as DJANGO_POSTGRES, PYMEMCACHE_DRIVER as PYMEMCACHE_DRIVER, REDIS_DRIVER as REDIS_DRIVER

from .fileaware_mapping import FileAwareMapping

brianschubert · 2025-09-07T17:03:30Z

stubs/django-environ/environ/environ.pyi

+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
+
+_Cast: TypeAlias = Callable[[str], _T]


nit: I'd suggest calling this something like _CastFunc to help distinguish this from the type that's accepted by the various cast parameters, which is different

brianschubert · 2025-09-07T17:19:58Z

stubs/django-environ/environ/environ.pyi

+
+class Path:
+    def path(self, *paths: str, **kwargs: Unpack[PathKwargs]) -> Path: ...
+    def file(self, name: str, *args, **kwargs) -> IO[str]: ...


This could also return a IO[bytes] if e.g. mode="rb" is passed, so let's change this to IO[Any].

Suggested change

def file(self, name: str, *args, **kwargs) -> IO[str]: ...

# *args and **kwargs are passed to open().

def file(self, name: str, *args: Any, **kwargs: Any) -> IO[Any]: ...

brianschubert · 2025-09-07T17:22:06Z

stubs/django-environ/environ/environ.pyi

+    def rfind(self, s: str, sub: str, start: int = 0, end: int = ...) -> int: ...
+    def find(self, s: str, sub: str, start: int = 0, end: int = ...) -> int: ...


Suggested change

def rfind(self, s: str, sub: str, start: int = 0, end: int = ...) -> int: ...

def find(self, s: str, sub: str, start: int = 0, end: int = ...) -> int: ...

def rfind(self, s: str, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /) -> int: ...

def find(self, s: str, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /) -> int: ...

brianschubert · 2025-09-07T17:28:27Z

stubs/django-environ/environ/environ.pyi

+
+    __root__: str
+
+    def __init__(self, start: str = "", *paths: str, **kwargs: Unpack[PathKwargs]) -> None: ...


start and paths are passed directly to os.path functions, so any pathlike is accepted.

Suggested change

def __init__(self, start: str = "", *paths: str, **kwargs: Unpack[PathKwargs]) -> None: ...

def __init__(self, start: StrPath = "", *paths: StrPath, **kwargs: Unpack[PathKwargs]) -> None: ...

You'll need to import StrPath from _typeshed

brianschubert · 2025-09-07T17:28:29Z

stubs/django-environ/environ/environ.pyi

+    __root__: str
+
+    def __init__(self, start: str = "", *paths: str, **kwargs: Unpack[PathKwargs]) -> None: ...
+    def __call__(self, *paths: str, **kwargs: Unpack[PathKwargs]) -> str: ...


Suggested change

def __call__(self, *paths: str, **kwargs: Unpack[PathKwargs]) -> str: ...

def __call__(self, *paths: StrPath, **kwargs: Unpack[PathKwargs]) -> str: ...

brianschubert · 2025-09-07T17:32:03Z

stubs/django-environ/environ/environ.pyi

+# One CastDict for each combination of 'key', 'value' and 'cast' (8 in total).
+# Use auxiliary '_type' to make them distinguishable for type checkers.
+@type_check_only
+class CastDict000(TypedDict):
+    _type: NotRequired[Literal["000"]]


I don't quite follow what's being done with these TypedDicts. It looks like this is a complicated case that would take some effort to get right. In order to not delay getting the rest of the stubs merged, I'd suggest taking a very simple approach for this PR (say, something inferring dict[Any, Any] for any dict-valued cast argument) and work on refining the dict cast behavior in a followup

marcus added 5 commits August 7, 2025 19:38

[django-environ] Run create_baseline_stubs.py script.

a7151c6

[django-environ] Fix incomplete types.

40c0da3

[django-environ] Use generic types where applicable.

a08916e

[django-environ] Fix tests.

f090e9f

[django-environ] Improve typing for Path.

11da833

This comment has been minimized.

Sign in to view

[django-environ] Fix stubtests.

5b5a7bb

This comment has been minimized.

Sign in to view

donBarbos reviewed Aug 13, 2025

View reviewed changes

brianschubert reviewed Aug 13, 2025

View reviewed changes

brianschubert changed the title ~~Feature/django environ types~~ Add stubs for django-environ Aug 13, 2025

marcus added 3 commits August 18, 2025 17:09

[django-environ] Apply suggestions.

88ae28a

[django-environ] Use import aliases for builtins.

e0977d6

[django-environ] Add overloads for various cast arguments types.

fe8b2f4

This comment has been minimized.

Sign in to view

[django-environ] Add missing type arguments (pyright).

73b4012

This comment has been minimized.

Sign in to view

EmCeeEs commented Aug 19, 2025

View reviewed changes

stubs/django-environ/METADATA.toml Outdated Show resolved Hide resolved

EmCeeEs commented Aug 19, 2025

View reviewed changes

marcus added 3 commits August 20, 2025 11:15

[django-environ] Remove django-stubs dependency.

1326a7a

[django-environ] Use generics for CastDict. Comment on usage of Any t…

f8a7a38

…ype.

[django-environ] Add tests for parse_value and fix/extend/improve som…

076c8e2

…e types.

brianschubert reviewed Sep 7, 2025

View reviewed changes

		@@ -0,0 +1,13 @@
		from typing import Final

		from .compat import DJANGO_POSTGRES as DJANGO_POSTGRES, PYMEMCACHE_DRIVER as PYMEMCACHE_DRIVER, REDIS_DRIVER as REDIS_DRIVER

	from .fileaware_mapping import FileAwareMapping
	from .compat import DJANGO_POSTGRES as DJANGO_POSTGRES, PYMEMCACHE_DRIVER as PYMEMCACHE_DRIVER, REDIS_DRIVER as REDIS_DRIVER
	from .fileaware_mapping import FileAwareMapping

	def file(self, name: str, args, *kwargs) -> IO[str]: ...
	# args and *kwargs are passed to open().
	def file(self, name: str, args: Any, *kwargs: Any) -> IO[Any]: ...

		def rfind(self, s: str, sub: str, start: int = 0, end: int = ...) -> int: ...
		def find(self, s: str, sub: str, start: int = 0, end: int = ...) -> int: ...


		__root__: str

		def __init__(self, start: str = "", paths: str, *kwargs: Unpack[PathKwargs]) -> None: ...

	def __init__(self, start: str = "", paths: str, *kwargs: Unpack[PathKwargs]) -> None: ...
	def __init__(self, start: StrPath = "", paths: StrPath, *kwargs: Unpack[PathKwargs]) -> None: ...

	def __call__(self, paths: str, *kwargs: Unpack[PathKwargs]) -> str: ...
	def __call__(self, paths: StrPath, *kwargs: Unpack[PathKwargs]) -> str: ...

Uh oh!

Add stubs for django-environ #14573

Are you sure you want to change the base?

Add stubs for django-environ #14573

Uh oh!

Conversation

EmCeeEs commented Aug 13, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

donBarbos commented Aug 13, 2025

Uh oh!

donBarbos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brianschubert left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

donBarbos commented Aug 18, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

donBarbos Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Aug 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brianschubert Sep 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

donBarbos Aug 19, 2025 •

edited

Loading

brianschubert Sep 7, 2025 •

edited

Loading