Add stubs for django-environ #14573

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

Types for django-environ.

github-actions · 2025-08-13T16:27:47Z

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

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:

donBarbos · 2025-08-13T19:06:14Z

stubs/django-environ/environ/__init__.pyi

+__copyright__: str
+__version__: str
+__license__: str
+__author_email__: str
+__maintainer__: str
+__maintainer_email__: str
+__url__: str
+__description__: str


I think these variables can be marked as Final (but need to import Final from typing)

Suggested change

__copyright__: str

__version__: str

__license__: str

__author_email__: str

__maintainer__: str

__maintainer_email__: str

__url__: str

__description__: str

__copyright__: Final[str]

__version__: Final[str]

__license__: Final[str]

__author_email__: Final[str]

__maintainer__: Final[str]

__maintainer_email__: Final[str]

__url__: Final[str]

__description__: Final[str]

donBarbos · 2025-08-13T19:06:55Z

stubs/django-environ/environ/compat.pyi

+REDIS_DRIVER: str
+DJANGO_POSTGRES: str
+PYMEMCACHE_DRIVER: str


Suggested change

REDIS_DRIVER: str

DJANGO_POSTGRES: str

PYMEMCACHE_DRIVER: str

REDIS_DRIVER: Final[str]

DJANGO_POSTGRES: Final[str]

PYMEMCACHE_DRIVER: Final[str]

donBarbos · 2025-08-13T19:08:28Z

stubs/django-environ/environ/compat.pyi

+def choose_rediscache_driver(): ...
+def choose_postgres_driver(): ...
+def choose_pymemcache_driver(): ...


Suggested change

def choose_rediscache_driver(): ...

def choose_postgres_driver(): ...

def choose_pymemcache_driver(): ...

def choose_rediscache_driver() -> str: ...

def choose_postgres_driver() -> str: ...

def choose_pymemcache_driver() -> str: ...

donBarbos · 2025-08-13T19:09:53Z

stubs/django-environ/environ/environ.pyi

+_Str = str
+_Bytes = bytes
+_Bool = bool
+_Int = int
+_Float = float
+_List = list
+_Tuple = tuple
+_Dict = dict


Looks like internal types, I think it's okay to miss them

Suggested change

_Str = str

_Bytes = bytes

_Bool = bool

_Int = int

_Float = float

_List = list

_Tuple = tuple

_Dict = dict

donBarbos · 2025-08-13T19:12:38Z

stubs/django-environ/environ/environ.pyi

+    ENVIRON: MutableMapping[_Str, _Str]
+    NOTSET: ClassVar[NoValue]
+    BOOLEAN_TRUE_STRINGS: ClassVar[_BooleanTrueStrings]
+    URL_CLASS: ClassVar[type[ParseResult]]
+    POSTGRES_FAMILY: ClassVar[_List[_Str]]
+    DEFAULT_DATABASE_ENV: ClassVar[_Str] = "DATABASE_URL"
+    DB_SCHEMES: ClassVar[_Dict[_Str, _Str]]


no need to use aliases for builtin types, it's more confusing

Suggested change

ENVIRON: MutableMapping[_Str, _Str]

NOTSET: ClassVar[NoValue]

BOOLEAN_TRUE_STRINGS: ClassVar[_BooleanTrueStrings]

URL_CLASS: ClassVar[type[ParseResult]]

POSTGRES_FAMILY: ClassVar[_List[_Str]]

DEFAULT_DATABASE_ENV: ClassVar[_Str] = "DATABASE_URL"

DB_SCHEMES: ClassVar[_Dict[_Str, _Str]]

ENVIRON: MutableMapping[str, str]

NOTSET: ClassVar[NoValue]

BOOLEAN_TRUE_STRINGS: ClassVar[_BooleanTrueStrings]

URL_CLASS: ClassVar[type[ParseResult]]

POSTGRES_FAMILY: ClassVar[list[str]]

DEFAULT_DATABASE_ENV: ClassVar[str] = "DATABASE_URL"

DB_SCHEMES: ClassVar[dict[str, str]]

I didn't change everything, but you get the idea :)

This won't work because the Env class defines methods def str(...), def list(...), etc. overwriting the builtin types. That was the reason for the aliases. ;) Alternatively, I could explicitly use builtins.str, builtins.list, etc. everywhere in the Env class. What do you think?

Ah, that makes sense now :)

I think the typical approach for dealing with conflicts like that is to import the builtins symbols under an alias, e.g. from builtins import list as _list. Please also add a comment mentioning the conflict

brianschubert

Thanks! Looks good overall, see remarks below

brianschubert · 2025-08-13T19:06:27Z

stubs/django-environ/environ/__init__.pyi

+__copyright__: str
+__version__: str
+__license__: str
+__author_email__: str
+__maintainer__: str
+__maintainer_email__: str
+__url__: str
+__description__: str


These look like they can be marked as Final

brianschubert · 2025-08-13T19:06:33Z

stubs/django-environ/environ/compat.pyi

@@ -0,0 +1,9 @@
+class ImproperlyConfigured(Exception): ...


This re-exports ImproperlyConfigured from django, so I think you could use

Suggested change

class ImproperlyConfigured(Exception): ...

from django.core.exceptions import ImproperlyConfigured as ImproperlyConfigured

You'll need to add a django-stubs requirement to METADATA.toml. See some of the other django stubs for examples

brianschubert · 2025-08-13T19:06:38Z

stubs/django-environ/environ/compat.pyi

+def choose_rediscache_driver(): ...
+def choose_postgres_driver(): ...
+def choose_pymemcache_driver(): ...
+
+REDIS_DRIVER: str
+DJANGO_POSTGRES: str
+PYMEMCACHE_DRIVER: str


Suggested change

def choose_rediscache_driver(): ...

def choose_postgres_driver(): ...

def choose_pymemcache_driver(): ...

REDIS_DRIVER: str

DJANGO_POSTGRES: str

PYMEMCACHE_DRIVER: str

def choose_rediscache_driver() -> str: ...

def choose_postgres_driver() -> str: ...

def choose_pymemcache_driver() -> str: ...

REDIS_DRIVER: Final[str]

DJANGO_POSTGRES: Final[str]

PYMEMCACHE_DRIVER: Final[str]

brianschubert · 2025-08-13T19:07:10Z

stubs/django-environ/environ/environ.pyi

+# Some type aliases to make our life easier
+_Str = str
+_Bytes = bytes
+_Bool = bool
+_Int = int
+_Float = float
+_List = list
+_Tuple = tuple
+_Dict = dict


I'm not sure I see the value of these aliases. Can you switch to using the builtin types directly?

brianschubert · 2025-08-13T19:07:17Z

stubs/django-environ/environ/environ.pyi

+_T = TypeVar("_T")
+_Cast: TypeAlias = Callable[[_Str], _T]
+_SchemeValue: TypeAlias = _Cast[Any] | tuple[_Cast[Any], Any]
+_BooleanTrueStrings: TypeAlias = tuple[str, ...]


It looks like this alias is only used once, so I'm not sure it really pulls its weight. I'd suggest inlining it below

brianschubert · 2025-08-13T19:08:46Z

stubs/django-environ/environ/environ.pyi

+_Dict = dict
+
+_T = TypeVar("_T")
+_Cast: TypeAlias = Callable[[_Str], _T]


See comment on parse_value

brianschubert · 2025-08-13T19:09:03Z

stubs/django-environ/environ/environ.pyi

+    def db_url_config(cls, url: _Str | ParseResult, engine: _Str | None = None) -> _Dict: ...
+    @classmethod
+    def cache_url_config(cls, url: _Str | ParseResult, backend: _Str | None = None) -> _Dict: ...
+    @classmethod
+    def email_url_config(cls, url: _Str | ParseResult, backend: _Str | None = None) -> _Dict: ...
+    @classmethod
+    def channels_url_config(cls, url: _Str | ParseResult, backend: _Str | None = None) -> _Dict: ...
+    @classmethod
+    def search_url_config(cls, url: _Str | ParseResult, engine: _Str | None = None) -> _Dict: ...


These could return TypedDicts since the keys appear to be fixed

brianschubert · 2025-08-13T19:09:08Z

stubs/django-environ/environ/environ.pyi

+    @classmethod
+    def read_env(
+        cls,
+        env_file: _Str | os.PathLike[_Str] | None = None,


This could use StrPath (import from _typeshed)

brianschubert · 2025-08-13T19:09:12Z

stubs/django-environ/environ/environ.pyi

+class FileAwareEnv(Env):
+    ENVIRON: FileAwareMapping
+
+class _PathKwargs(TypedDict, total=False):


Suggested change

class _PathKwargs(TypedDict, total=False):

@type_check_only

class _PathKwargs(TypedDict, total=False):

brianschubert · 2025-08-13T19:09:36Z

stubs/django-environ/environ/fileaware_mapping.pyi

+    env: dict[str, str]
+    cache: bool
+    files_cache: dict[str, str]
+    def __init__(self, env: dict[str, str] | None = None, cache: bool = True) -> None: ...


Looks like env could be relaxed to MutableMapping[str, str]

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

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

	class ImproperlyConfigured(Exception): ...
	from django.core.exceptions import ImproperlyConfigured as ImproperlyConfigured

	class _PathKwargs(TypedDict, total=False):
	@type_check_only
	class _PathKwargs(TypedDict, total=False):

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.

github-actions bot commented Aug 13, 2025

Uh oh!

donBarbos commented Aug 13, 2025

Uh oh!

donBarbos left a comment

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 Aug 15, 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!

brianschubert left a comment

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 Aug 13, 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!

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!

Uh oh!

brianschubert Aug 15, 2025 •

edited

Loading

brianschubert Aug 13, 2025 •

edited

Loading