repository·master·Indexed 23 days ago
https://github.com/typeddjango/django-stubsMypy stubs and a custom mypy plugin for the Django framework, providing precise static typing and type inference. Includes the django-stubs-ext package for runtime monkey-patching to support generic Django classes and features like WithAnnotations for annotated QuerySet results.
The django-stubs-ext package detects your installed Django version at runtime and applies only the necessary patches. The primary patch adds a __class_getitem__ method to generic Django classes to support type hinting syntax. This method is a no-op and is safe to use in production:
@classmethod
def __class_getitem__(cls, *args, **kwargs):
return clsInstall the django-stubs-ext package via pip. This package provides necessary runtime monkey-patching for django-stubs features that cannot be handled by type stubs alone (such as generic Django classes lacking a __class_getitem__ method).
pip install django-stubs-extBy default, django.http.HttpRequest.user is typed as User | AnonymousUser. If you are in a context (like a view decorated with @login_required) where you know the user is authenticated, you can create a specialized subclass to avoid type errors:
from django.http import HttpRequest
from my_user_app.models import MyUser
class AuthenticatedHttpRequest(HttpRequest):
user: MyUserUse AuthenticatedHttpRequest in your type annotations for views where authentication is guaranteed.
from django.http import HttpRequest
from my_user_app.models import MyUser
class AuthenticatedHttpRequest(HttpRequest):
user: MyUserTo enable the django-stubs plugin in mypy, you must explicitly list it in your configuration file. You must also specify the django_settings_module or ensure the DJANGO_SETTINGS_MODULE environment variable is set.
# mypy.ini or setup.cfg
[mypy]
plugins =
mypy_django_plugin.main
[mypy.plugins.django-stubs]
django_settings_module = "myproject.settings"Install django-stubs with the compatible-mypy extra to provide type stubs and a custom mypy plugin for the Django framework. This helps resolve type inference issues caused by Django's dynamic Python patterns.
pip install 'django-stubs[compatible-mypy]'If using pyproject.toml, add the plugin to the [tool.mypy] section and the settings to the [tool.django-stubs] section.
[tool.mypy]
plugins = ["mypy_django_plugin.main"]
[tool.django-stubs]
django_settings_module = "myproject.settings"To enable the required runtime extensions for django-stubs, call django_stubs_ext.monkeypatch() in your Django application. This call should be made exactly once, typically in your top-level settings file.
import django_stubs_ext
django_stubs_ext.monkeypatch()When overriding built-in methods in a custom Manager without specifying generics, you may encounter an error stating the return type is incompatible with the supertype BaseManager (e.g., error: Return type "MyModel" of "create" incompatible with return type "_T" in supertype "BaseManager").
To fix this, declare your manager with your model as the type variable:
class MyManager(models.Manager["MyModel"]):
def create(self, **kwargs) -> "MyModel":
...from django.db import models
class MyManager(models.Manager["MyModel"]):
def create(self, **kwargs) -> "MyModel":
passDjango's QuerySet and Manager classes do not support the __class_getitem__ magic method at runtime, which causes a TypeError when using type annotations like QuerySet[MyModel] or Manager[MyModel].
You can resolve this using the django-stubs-ext helper package.
django-stubs-ext monkeypatchingInstall the package:
pip install django-stubs-extApply the monkeypatch in your top-level settings file:
import django_stubs_ext
django_stubs_ext.monkeypatch()Handling django.contrib.auth.forms: Because these forms cannot be imported until Django is initialized, you must perform manual monkeypatching in your first AppConfig.ready() method.
Note for Django < 5.1: Use extra_classes=[SetPasswordForm, AdminPasswordChangeForm] instead of mixins.
Use strings for the type hints to avoid runtime errors:
query: 'QuerySet[MyModel]'pip install django-stubs-extIf you use custom settings management (e.g., django-split-settings or django-configurations), mypy may fail to infer attributes on the django.conf.settings object.
You can disable strict checking by setting strict_settings = false in your configuration file. This causes mypy to treat unknown settings attributes as Any instead of raising errors.
Configuration via pyproject.toml:
[tool.django-stubs]
strict_settings = falseConfiguration via mypy.ini:
[mypy.plugins.django-stubs]
strict_settings = falseThe django-stubs Mypy plugin works by intercepting various Mypy lifecycle events to inject Django-specific type information. It handles several key areas:
__init__ methods are correctly typed based on model fields..filter(), .get(), .annotate(), .values(), and .prefetch_related() to ensure the returned types reflect the actual fields and annotations being used.ManyToManyField) and ensures that reverse relations and forward relations are correctly typed.Meta classes in Django Forms to ensure proper inheritance and typing.By using these hooks, the plugin transforms generic Django objects into specific, typed entities that Mypy can validate against your actual database schema and model definitions.
pyproject.toml under [tool.django-stubs] or in mypy.ini under [mypy.plugins.django-stubs].