conditional_escape() should return SafeString

[levic]

Bug report

What's wrong

The stub definition for conditional_escape says that it returns a str

The django code follows one of two paths:

• if already escaped, then call __html__ (this calls into SafeString/SafeData which just returns the same object back).
• it not escaped then call escape which returns a new SafeString

Running mypy on test.py:

from django.utils.html import conditional_escape
from django.utils.safestring import mark_safe
from django.utils.safestring import SafeString
from typing import TYPE_CHECKING

a = SafeString("<")
b = conditional_escape("<")
c = mark_safe("<")

if TYPE_CHECKING:
    reveal_type(a)
    reveal_type(b)
    reveal_type(c)

print(a.__class__)
print(b.__class__)
print(c.__class__)

mypy output is:

test.py:11: note: Revealed type is "django.utils.safestring.SafeString"
test.py:12: note: Revealed type is "builtins.str"
test.py:13: note: Revealed type is "django.utils.safestring.SafeString"

runtime output is:

<class 'django.utils.safestring.SafeString'>
<class 'django.utils.safestring.SafeString'>
<class 'django.utils.safestring.SafeString'>

How is that should be

mypy output:

test.py:11: note: Revealed type is "django.utils.safestring.SafeString"
test.py:12: note: Revealed type is "django.utils.safestring.SafeString"
test.py:13: note: Revealed type is "django.utils.safestring.SafeString"

System information

• OS: MacOS
• python version: 3.10
• django version: 3.2
• mypy version: 1.2.0
• django-stubs version: 4.2.0
• django-stubs-ext version: 4.2.0

Pedantic Note

Strictly speaking django allows for objects that implement __html__ and are not instances of SafeData.

To be 100% correct the declarations would have to create a protocol for objects that implement __html__, but IMO that's a somewhat obscure edge case. I note also that the existing mark_safe type definition already assumes SafeData so just marking conditional_escape as returning SafeString wouldn't be introducing an issue that doesn't already exist.