Add stubs for django-environ

[EmCeeEs]

Types for django-environ.

[github-actions[bot]]

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

[github-actions[bot]]

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

[donbarbos]

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.

[github-actions[bot]]

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: "name", "with_app_command"  [misc]
+ discord/ext/commands/hybrid.py:834: 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:858: 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:883: 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/hybrid.py:935: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
- discord/ext/commands/bot.py:291: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
+ discord/ext/commands/bot.py:291: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]
- discord/ext/commands/bot.py:315: error: Overlap between argument names and ** TypedDict items: "name", "with_app_command"  [misc]
+ discord/ext/commands/bot.py:315: error: Overlap between argument names and ** TypedDict items: "with_app_command", "name"  [misc]

[github-actions[bot]]

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

[donbarbos]

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.

[github-actions[bot]]

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]

[brianhelba]

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:

1. Is this the correct typing syntax to express this? It feels weird that this omits explicit use of NoValue.
2. 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.
3. 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]

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