Support passing lazy strings to utils.text functions

[ds-cbo]

Currently, we get many of the following errors when trying to pass our Django code through mypy:

error: Argument 1 to "capfirst" has incompatible type "_StrPromise"; expected "Optional[str]"  [arg-type]

Looking at the Django source code for capfirst it has been decorated with @keep_lazy_text meaning it also supports _StrPromise next to str.

I've updated the typing of all similar functions to reflect this support.

[intgr]

Thanks, this is useful.

The current patch may cause some false positives for users when upgrading though. For example this code was previously fine, but after the change:

from django.utils.text import wrap

def takes_str(value: str):
    pass

result = wrap("teststring", 80)
reveal_type(result)  # Revealed type is "Union[builtins.str, django.utils.functional._StrPromise]"
takes_str(result)  # Argument 1 to "takes_str" has incompatible type "Union[str, _StrPromise]"; expected "str"

The solution is to define TypeVar, to teach mypy that result type is dependent on input type.

_StrOrPromiseT = TypeVar("_StrOrPromiseT", bound=_StrOrPromise)

def wrap(text: _StrOrPromiseT, width: int) -> _StrOrPromiseT: ...

Now type checkers know that if you pass in str, the result will also be str.

Looks like it can be useful to define another TypeVar also for the case of _StrOrPromise | None

It looks like get_text_list is a more complex case and may not be worth it, feel free to use regular _StrOrPromise there. It may be possible to make it work with @overload.

[intgr]

Maybe this is of interest for @mschoettle too.

[intgr]

Thanks! Waiting for CI to pass.