Add stubs for django-environ by EmCeeEs · Pull Request #14573 · python/typeshed

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:

brianschubert

Thanks! Looks good overall, see remarks below

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.

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

    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.

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

+
+# 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

+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

@@ -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

+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

+_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

+
+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

+    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

+
+    __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

+    __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

+# 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

Yeah, this was quite complicated. I simplified it to just dict[Any, Any] for now.

brianhelba · 2025-12-03T04:26:18Z

In a lot of my own django-environ usage, it's very useful to have the pattern:

OPTIONAL_SETTING: str | None = environ.Env().str("DJANGO_OPTIONAL_SETTING", default=None)

This is allowed by the library behavior, I'm wondering if the type stubs could also allow something like:

_DefaultT = TypeVar("_DefaultT")

class Env:
    @typing.overload
    def str(self, var: _str, default: _DefaultT = ..., multiline: _bool = False) -> _DefaultT: ...
    @typing.overload
    def str(self, var: _str, multiline: _bool = False) -> _str:

Regarding this idea:

Is this the correct typing syntax to express this? It feels weird that this omits explicit use of NoValue.
Should the type annotations permit this all? It's behaviorally allowed by the downstream library and is practically useful to me, but is this too abusive of strong typing? Personally, I think it's fine.
Should this be implemented in a different PR? This PR seems stalled, so maybe it's better to make this change separately? It is just widening / liberalizing the type rules for the default parameter, so compatibility should be fine.

brianhelba · 2025-12-03T04:28:25Z

@EmCeeEs @brianschubert Thanks for all your efforts here!

This PR seems to be inactive now, but I'm very interested in seeing it merged. Is it possible for me to provide any help to finish it?

joke2k · 2026-02-21T02:00:18Z

Hi all! I’m actively maintaining this project and I’d be very interested in shipping a 1.0 release with proper typing support. Happy to collaborate to make that happen.

…ron-types

This reverts commit 0aaac7e.

github-actions · 2026-05-10T05:14:53Z

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

JelleZijlstra · 2026-05-10T05:16:23Z

I pushed changes addressing @brianschubert's feedback; is this good to go in now?

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

Comment thread stubs/django-environ/METADATA.toml Outdated

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.

This comment has been minimized.

Sign in to view

brianschubert reviewed Sep 7, 2025

View reviewed changes

brianhelba mentioned this pull request Mar 29, 2026

Add type checking with MyPy to tests joke2k/django-environ#601

Open

JelleZijlstra and others added 2 commits May 9, 2026 21:51

Address Brian feedback

a91c034

[pre-commit.ci] auto fixes from pre-commit.com hooks

18b34a3

This comment has been minimized.

Sign in to view

JelleZijlstra added 5 commits May 9, 2026 22:02

?

0aaac7e

Merge remote-tracking branch 'upstream/main' into feature/django-envi…

82fa423

…ron-types

Revert "?"

4251c0b

This reverts commit 0aaac7e.

dash

33de664

stubtest

952beed

		@@ -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!

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!

This comment has been minimized.

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!

Choose a reason for hiding this comment

Uh oh!

brianhelba commented Dec 3, 2025

Uh oh!

brianhelba commented Dec 3, 2025

Uh oh!

joke2k commented Feb 21, 2026

Uh oh!

This comment has been minimized.

github-actions Bot commented May 10, 2026

Uh oh!

JelleZijlstra commented May 10, 2026

Uh oh!

Reviewers

Assignees

donbarbos Aug 19, 2025 •

edited

Loading

brianschubert Sep 7, 2025 •

edited

Loading