Resolve configured AUTH_USER_MODEL with a get_type_analyze_hook (#2335)

It's nothing special really. We declare a `TypeAlias` in the pyi, thus getting a fullname, somewhere under `django.contrib.auth`. We then build a type analyze hook for that fullname. And the hook simulates what `django.contrib.auth.get_user_model` does

The alias is set up to point to `AbstractBaseUser`, so for a type checker other than mypy nothing should've changed

Author: flaeppe

django-stubs/contrib/auth/__init__.pyi

@@ -1,7 +1,7 @@
 from typing import Any
 
 from django.contrib.auth.backends import BaseBackend
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import _UserModel
 from django.contrib.auth.models import AnonymousUser
 from django.db.models.options import Options
 from django.http.request import HttpRequest
@@ -18,19 +18,17 @@ REDIRECT_FIELD_NAME: str
 
 def load_backend(path: str) -> BaseBackend: ...
 def get_backends() -> list[BaseBackend]: ...
-def authenticate(request: HttpRequest | None = ..., **credentials: Any) -> AbstractBaseUser | None: ...
-async def aauthenticate(request: HttpRequest | None = ..., **credentials: Any) -> AbstractBaseUser | None: ...
-def login(
-    request: HttpRequest, user: AbstractBaseUser | None, backend: type[BaseBackend] | str | None = ...
-) -> None: ...
+def authenticate(request: HttpRequest | None = ..., **credentials: Any) -> _UserModel | None: ...
+async def aauthenticate(request: HttpRequest | None = ..., **credentials: Any) -> _UserModel | None: ...
+def login(request: HttpRequest, user: _UserModel | None, backend: type[BaseBackend] | str | None = ...) -> None: ...
 async def alogin(
-    request: HttpRequest, user: AbstractBaseUser | None, backend: type[BaseBackend] | str | None = ...
+    request: HttpRequest, user: _UserModel | None, backend: type[BaseBackend] | str | None = ...
 ) -> None: ...
 def logout(request: HttpRequest) -> None: ...
 async def alogout(request: HttpRequest) -> None: ...
-def get_user_model() -> type[AbstractBaseUser]: ...
-def get_user(request: HttpRequest | Client) -> AbstractBaseUser | AnonymousUser: ...
-async def aget_user(request: HttpRequest | Client) -> AbstractBaseUser | AnonymousUser: ...
+def get_user_model() -> type[_UserModel]: ...
+def get_user(request: HttpRequest | Client) -> _UserModel | AnonymousUser: ...
+async def aget_user(request: HttpRequest | Client) -> _UserModel | AnonymousUser: ...
 def get_permission_codename(action: str, opts: Options) -> str: ...
-def update_session_auth_hash(request: HttpRequest, user: AbstractBaseUser) -> None: ...
-async def aupdate_session_auth_hash(request: HttpRequest, user: AbstractBaseUser) -> None: ...
+def update_session_auth_hash(request: HttpRequest, user: _UserModel) -> None: ...
+async def aupdate_session_auth_hash(request: HttpRequest, user: _UserModel) -> None: ...

django-stubs/contrib/auth/backends.pyi

@@ -1,19 +1,18 @@
 from typing import Any, TypeVar
 
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import AbstractBaseUser, _UserModel
 from django.contrib.auth.models import AnonymousUser, Permission
 from django.db.models import QuerySet
 from django.db.models.base import Model
 from django.http.request import HttpRequest
 from typing_extensions import TypeAlias
 
-_AnyUser: TypeAlias = AbstractBaseUser | AnonymousUser
-
-UserModel: Any
+UserModel: TypeAlias = type[_UserModel]
+_AnyUser: TypeAlias = _UserModel | AnonymousUser
 
 class BaseBackend:
-    def authenticate(self, request: HttpRequest | None, **kwargs: Any) -> AbstractBaseUser | None: ...
-    def get_user(self, user_id: Any) -> AbstractBaseUser | None: ...
+    def authenticate(self, request: HttpRequest | None, **kwargs: Any) -> _UserModel | None: ...
+    def get_user(self, user_id: Any) -> _UserModel | None: ...
     def get_user_permissions(self, user_obj: _AnyUser, obj: Model | None = ...) -> set[str]: ...
     def get_group_permissions(self, user_obj: _AnyUser, obj: Model | None = ...) -> set[str]: ...
     def get_all_permissions(self, user_obj: _AnyUser, obj: Model | None = ...) -> set[str]: ...
@@ -22,7 +21,7 @@ class BaseBackend:
 class ModelBackend(BaseBackend):
     def authenticate(
         self, request: HttpRequest | None, username: str | None = ..., password: str | None = ..., **kwargs: Any
-    ) -> AbstractBaseUser | None: ...
+    ) -> _UserModel | None: ...
     def has_module_perms(self, user_obj: _AnyUser, app_label: str) -> bool: ...
     def user_can_authenticate(self, user: _AnyUser | None) -> bool: ...
     def with_perm(
@@ -31,7 +30,7 @@ class ModelBackend(BaseBackend):
         is_active: bool = ...,
         include_superusers: bool = ...,
         obj: Model | None = ...,
-    ) -> QuerySet[AbstractBaseUser]: ...
+    ) -> QuerySet[_UserModel]: ...
 
 class AllowAllUsersModelBackend(ModelBackend): ...
 

django-stubs/contrib/auth/base_user.pyi

@@ -4,6 +4,7 @@ from django.db import models
 from django.db.models.base import Model
 from django.db.models.expressions import Combinable
 from django.db.models.fields import BooleanField
+from typing_extensions import TypeAlias
 
 _T = TypeVar("_T", bound=Model)
 
@@ -41,3 +42,8 @@ class AbstractBaseUser(models.Model):
     @classmethod
     @overload
     def normalize_username(cls, username: Any) -> Any: ...
+
+# This is our "placeholder" type the mypy plugin refines to configured 'AUTH_USER_MODEL'
+# wherever it is used as a type. The most recognised example of this is (probably)
+# `HttpRequest.user`
+_UserModel: TypeAlias = AbstractBaseUser  # noqa: PYI047

django-stubs/contrib/auth/decorators.pyi

@@ -1,13 +1,14 @@
 from collections.abc import Callable, Iterable
 from typing import TypeVar, overload
 
-from django.contrib.auth.models import AbstractBaseUser, AnonymousUser
+from django.contrib.auth.base_user import _UserModel
+from django.contrib.auth.models import AnonymousUser
 from django.http.response import HttpResponseBase
 
 _VIEW = TypeVar("_VIEW", bound=Callable[..., HttpResponseBase])
 
 def user_passes_test(
-    test_func: Callable[[AbstractBaseUser | AnonymousUser], bool],
+    test_func: Callable[[_UserModel | AnonymousUser], bool],
     login_url: str | None = ...,
     redirect_field_name: str | None = ...,
 ) -> Callable[[_VIEW], _VIEW]: ...

django-stubs/contrib/auth/forms.pyi

@@ -2,16 +2,17 @@ from collections.abc import Iterable
 from typing import Any, TypeVar
 
 from django import forms
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import AbstractBaseUser, _UserModel
 from django.contrib.auth.tokens import PasswordResetTokenGenerator
 from django.core.exceptions import ValidationError
 from django.db import models
 from django.db.models.fields import _ErrorMessagesDict
 from django.forms.fields import _ClassLevelWidgetT
 from django.forms.widgets import Widget
 from django.http.request import HttpRequest
+from typing_extensions import TypeAlias
 
-UserModel: type[AbstractBaseUser]
+UserModel: TypeAlias = type[_UserModel]
 _User = TypeVar("_User", bound=AbstractBaseUser)
 
 class ReadOnlyPasswordHashWidget(forms.Widget):
@@ -47,11 +48,11 @@ class AuthenticationForm(forms.Form):
     password: forms.Field
     error_messages: _ErrorMessagesDict
     request: HttpRequest | None
-    user_cache: Any
+    user_cache: _UserModel | None
     username_field: models.Field
     def __init__(self, request: HttpRequest | None = ..., *args: Any, **kwargs: Any) -> None: ...
     def confirm_login_allowed(self, user: AbstractBaseUser) -> None: ...
-    def get_user(self) -> AbstractBaseUser: ...
+    def get_user(self) -> _UserModel: ...
     def get_invalid_login_error(self) -> ValidationError: ...
     def clean(self) -> dict[str, Any]: ...
 
@@ -66,7 +67,7 @@ class PasswordResetForm(forms.Form):
         to_email: str,
         html_email_template_name: str | None = ...,
     ) -> None: ...
-    def get_users(self, email: str) -> Iterable[AbstractBaseUser]: ...
+    def get_users(self, email: str) -> Iterable[_UserModel]: ...
     def save(
         self,
         domain_override: str | None = ...,

django-stubs/contrib/auth/middleware.pyi

@@ -1,10 +1,10 @@
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import _UserModel
 from django.contrib.auth.models import AnonymousUser
 from django.http.request import HttpRequest
 from django.utils.deprecation import MiddlewareMixin
 
-def get_user(request: HttpRequest) -> AnonymousUser | AbstractBaseUser: ...
-async def auser(request: HttpRequest) -> AnonymousUser | AbstractBaseUser: ...
+def get_user(request: HttpRequest) -> AnonymousUser | _UserModel: ...
+async def auser(request: HttpRequest) -> AnonymousUser | _UserModel: ...
 
 class AuthenticationMiddleware(MiddlewareMixin):
     def process_request(self, request: HttpRequest) -> None: ...

django-stubs/contrib/auth/password_validation.pyi

@@ -2,10 +2,7 @@ from collections.abc import Mapping, Sequence
 from pathlib import Path, PosixPath
 from typing import Any, Protocol, type_check_only
 
-from django.db.models.base import Model
-from typing_extensions import TypeAlias
-
-_UserModel: TypeAlias = Model
+from django.contrib.auth.base_user import _UserModel
 
 @type_check_only
 class PasswordValidator(Protocol):

django-stubs/contrib/auth/tokens.pyi

@@ -1,17 +1,17 @@
 from datetime import date, datetime
 from typing import Any
 
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import _UserModel
 
 class PasswordResetTokenGenerator:
     key_salt: str
     secret: str | bytes
     secret_fallbacks: list[str | bytes]
     algorithm: str
-    def make_token(self, user: AbstractBaseUser) -> str: ...
-    def check_token(self, user: AbstractBaseUser | None, token: str | None) -> bool: ...
-    def _make_token_with_timestamp(self, user: AbstractBaseUser, timestamp: int, secret: str | bytes = ...) -> str: ...
-    def _make_hash_value(self, user: AbstractBaseUser, timestamp: int) -> str: ...
+    def make_token(self, user: _UserModel) -> str: ...
+    def check_token(self, user: _UserModel | None, token: str | None) -> bool: ...
+    def _make_token_with_timestamp(self, user: _UserModel, timestamp: int, secret: str | bytes = ...) -> str: ...
+    def _make_hash_value(self, user: _UserModel, timestamp: int) -> str: ...
     def _num_seconds(self, dt: datetime | date) -> int: ...
     def _now(self) -> datetime: ...
 

django-stubs/contrib/auth/views.pyi

@@ -1,13 +1,14 @@
 from typing import Any
 
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import _UserModel
 from django.contrib.auth.forms import AuthenticationForm
 from django.http.request import HttpRequest
 from django.http.response import HttpResponse, HttpResponseRedirect
 from django.views.generic.base import TemplateView
 from django.views.generic.edit import FormView
+from typing_extensions import TypeAlias
 
-UserModel: Any
+UserModel: TypeAlias = type[_UserModel]
 
 class RedirectURLMixin:
     next_page: str | None
@@ -65,7 +66,7 @@ class PasswordResetConfirmView(PasswordContextMixin, FormView):
     token_generator: Any
     validlink: bool
     user: Any
-    def get_user(self, uidb64: str) -> AbstractBaseUser | None: ...
+    def get_user(self, uidb64: str) -> _UserModel | None: ...
 
 class PasswordResetCompleteView(PasswordContextMixin, TemplateView):
     title: Any

django-stubs/http/request.pyi

@@ -4,7 +4,7 @@ from io import BytesIO
 from re import Pattern
 from typing import Any, Awaitable, BinaryIO, Callable, Literal, NoReturn, TypeVar, overload, type_check_only
 
-from django.contrib.auth.base_user import AbstractBaseUser
+from django.contrib.auth.base_user import _UserModel
 from django.contrib.auth.models import AnonymousUser
 from django.contrib.sessions.backends.base import SessionBase
 from django.contrib.sites.models import Site
@@ -55,9 +55,9 @@ class HttpRequest(BytesIO):
     # django.contrib.admin views:
     current_app: str
     # django.contrib.auth.middleware.AuthenticationMiddleware:
-    user: AbstractBaseUser | AnonymousUser
+    user: _UserModel | AnonymousUser
     # django.contrib.auth.middleware.AuthenticationMiddleware:
-    auser: Callable[[], Awaitable[AbstractBaseUser | AnonymousUser]]
+    auser: Callable[[], Awaitable[_UserModel | AnonymousUser]]
     # django.middleware.locale.LocaleMiddleware:
     LANGUAGE_CODE: str
     # django.contrib.sites.middleware.CurrentSiteMiddleware