This package contains type stubs and a custom mypy plugin to provide more precise static types and type inference for Django framework. Django uses some Python "magic" that makes having precise types for some code patterns problematic. This is why we need this project. The final goal is to be able to get precise types for most common patterns.

Installation

pip install 'django-stubs[compatible-mypy]'

To make mypy aware of the plugin, you need to add

[mypy]
plugins =
    mypy_django_plugin.main

[mypy.plugins.django-stubs]
django_settings_module = "myproject.settings"

in your mypy.ini or setup.cfg file.

pyproject.toml configurations are also supported:

[tool.mypy]
plugins = ["mypy_django_plugin.main"]

[tool.django-stubs]
django_settings_module = "myproject.settings"

Two things happening here:

1. We need to explicitly list our plugin to be loaded by mypy
2. You can either specify django_settings_module as seen above, or let django_stubs use the DJANGO_SETTINGS_MODULE variable from your environment.

This fully working typed boilerplate can serve you as an example.

Version compatibility

We rely on different django and mypy versions:

What "partial" support means, and why we don't pin to the exact Django/mypy version, is explained in https://github.com/typeddjango/django-stubs/discussions/2101#discussioncomment-9276632.

Features

Type checking of Model Meta attributes

[!NOTE] If you are using the mypy plugin and have django_stub_ext installed, your model Meta classes will be automatically type-checked without further changes.

By inheriting from the TypedModelMeta class, you can ensure you're using correct types for attributes:

from django.db import models
from django_stubs_ext.db.models import TypedModelMeta

class MyModel(models.Model):
    example = models.CharField(max_length=100)

    class Meta(TypedModelMeta):
        ordering = ["example"]
        constraints = [
            models.UniqueConstraint(fields=["example"], name="unique_example"),
        ]

Other typed base classes

• django_stubs_ext.db.router.TypedDatabaseRouter can be used as base when implementing custom database routers.

Settings

django-stubs has a few settings, which you can list in:

• pyproject.toml, under the table [tool.django-stubs]
• mypy.ini under the table [mypy.plugins.django-stubs]

The supported settings are:

• django_settings_module, a string, default to os.getenv(DJANGO_SETTINGS_MODULE).

Specify the import path of your settings module, the same as Django’s DJANGO_SETTINGS_MODULE environment variable.

• strict_settings, a boolean, default true.

Set to false if using dynamic settings, as described below.

• strict_model_abstract_attrs, a boolean, default true.

Set to false if you want to keep .objects, .DoesNotExist, and .MultipleObjectsReturned attributes on models.Model type. See here why this is dangerous to do by default.

FAQ

Is this an official Django project?

No, it is not. We are independent from Django at the moment. There's a proposal to merge our project into the Django itself. You can show your support by liking the PR.

Is it safe to use this in production?

Yes, it is! This project does not affect your runtime at all. It only affects mypy type checking process.

But, it does not make any sense to use this project without mypy.

mypy crashes when I run it with this plugin installed

The current implementation uses Django's runtime to extract information about models, so it might crash if your installed apps or models.py are broken.

In other words, if your manage.py runserver crashes, mypy will crash too. You can also run mypy with --tb option to get extra information about the error.

I cannot use QuerySet or Manager with type annotations

You can get a TypeError: 'type' object is not subscriptable when you will try to use QuerySet[MyModel], Manager[MyModel] or some other Django-based Generic types.

This happens because these Django classes do not support __class_getitem__ magic method in runtime.

1. You can go with our django_stubs_ext helper, that patches all the types we use as Generic in django.

Install it:

bash pip install django-stubs-ext # as a production dependency

And then place in your top-level settings:

```python import django_stubs_ext

django_stubs_ext.monkeypatch() ```

You can add extra types to patch with django_stubs_ext.monkeypatch(extra_classes=[YourDesiredType])

If you use generic symbols in django.contrib.auth.forms, you will have to do the monkeypatching manually in your first AppConfig.ready. This is currently required because django.contrib.auth.forms cannot be imported until django is initialized.

```python
import django_stubs_ext
from django.apps import AppConfig

class ClientsConfig(AppConfig):
    name = "clients"

    def ready(self) -> None:
        from django.contrib.auth.forms import SetPasswordMixin, SetUnusablePasswordMixin

        # For Django version prior to 5.1, use `extra_classes=[SetPasswordForm, AdminPasswordChangeForm]` instead.
        django_stubs_ext.monkeypatch(extra_classes=[SetPasswordMixin, SetUnusablePasswordMixin])
```

1. You can use strings instead: 'QuerySet[MyModel]' and 'Manager[MyModel]', this way it will work as a type for mypy and as a regular str in runtime.

How can I create a HttpRequest that's guaranteed to have an authenticated user?

Django's built in HttpRequest has the attribute user that resolves to the type

Union[User, AnonymousUser]

where User is the user model specified by the AUTH_USER_MODEL setting.

If you want a HttpRequest that you can type-annotate with where you know that the user is authenticated you can subclass the normal HttpRequest class like so:

from django.http import HttpRequest
from my_user_app.models import MyUser


class AuthenticatedHttpRequest(HttpRequest):
    user: MyUser

And then use AuthenticatedHttpRequest instead of the standard HttpRequest for when you know that the user is authenticated. For example in views using the @login_required decorator.

Why am I getting incompatible return type errors on my custom managers?

If you declare your custom managers without generics and override built-in methods you might see an error message about incompatible error messages, something like this:

from django.db import models

class MyManager(model.Manager):
    def create(self, **kwargs) -> "MyModel":
        pass

will cause this error message:

error: Return type "MyModel" of "create" incompatible with return type "_T" in supertype "BaseManager"

This is happening because the Manager class is generic, but without specifying generics the built-in manager methods are expected to return the generic type of the base manager, which is any model. To fix this issue you should declare your manager with your model as the type variable:

class MyManager(models.Manager["MyModel"]):
    ...

How do I annotate cases where I called QuerySet.annotate?

Django-stubs provides a special type, django_stubs_ext.WithAnnotations[Model, <Annotations>], which indicates that the Model has been annotated, meaning it requires extra attributes on the model instance.

You should provide a TypedDict of these attributes, e.g. WithAnnotations[MyModel, MyTypedDict], to specify which annotated attributes are present.

Currently, the mypy plugin can recognize that specific names were passed to QuerySet.annotate and include them in the type, but does not record the types of these attributes.

The knowledge of the specific annotated fields is not yet used in creating more specific types for QuerySet's values, values_list, or filter methods, however knowledge that the model was annotated is used to create a broader type result type for values/values_list, and to allow filtering on any field.

from typing import TypedDict
from django_stubs_ext import WithAnnotations
from django.db import models
from django.db.models.expressions import Value


class MyModel(models.Model):
    username = models.CharField(max_length=100)


class MyTypedDict(TypedDict):
    foo: str


def func(m: WithAnnotations[MyModel, MyTypedDict]) -> str:
    print(m.bar)  # Error, since field "bar" is not in MyModel or MyTypedDict.
    return m.foo  # OK, since we said field "foo" was allowed


func(MyModel.objects.annotate(foo=Value("")).get(id=1))  # OK
func(MyModel.objects.annotate(bar=Value("")).get(id=1))  # Error

Why am I getting incompatible argument type mentioning _StrPromise?

The lazy translation functions of Django (such as gettext_lazy) return a Promise instead of str. These two types cannot be used interchangeably. The return type of these functions was therefore changed to reflect that.

If you encounter this error in your own code, you can either cast the Promise to str (causing the translation to be evaluated), or use the StrPromise or StrOrPromise types from django-stubs-ext in type hints. Which solution to choose depends depends on the particular case. See working with lazy translation objects in the Django documentation for more information.

If this is reported on Django code, please report an issue or open a pull request to fix the type hints.

How to use a custom library to handle Django settings?

Using something like django-split-settings or django-configurations will make it hard for mypy to infer your settings.

This might also be the case when using something like:

try:
    from .local_settings import *
except Exception:
    pass

So, mypy would not like this code:

from django.conf import settings

settings.CUSTOM_VALUE  # E: 'Settings' object has no attribute 'CUSTOM_VALUE'

To handle this corner case we have a special setting strict_settings (True by default), you can switch it to False to always return Any and not raise any errors if runtime settings module has the given value, for example pyproject.toml:

[tool.django-stubs]
strict_settings = false

or mypy.ini:

[mypy.plugins.django-stubs]
strict_settings = false

And then:

# Works:
reveal_type(settings.EXISTS_AT_RUNTIME)  # N: Any

# Errors:
reveal_type(settings.MISSING)  # E: 'Settings' object has no attribute 'MISSING'

How to use type[Model] annotation with .objects attribute?

Let's say you have a function similar to this one, which accepts a model type and accesses its .object attribute:

from django.db import models

def assert_zero_count(model_type: type[models.Model]) -> None:
    assert model_type.objects.count() == 0

This code will raise an error from mypy:

error: "type[Model]" has no attribute "objects"  [attr-defined]

It is a common problem: some type[models.Model] types won't have .objects available. Notable example: abstract models. See the reasoning here.

So, instead for the general case you should write:

def assert_zero_count(model_type: type[models.Model]) -> None:
    assert model_type._default_manager.count() == 0

Configurable with strict_model_abstract_attrs = false to skip removing .objects, .DoesNotExist, and .MultipleObjectsReturned attributes from model.Model if you are using our mypy plugin.

Use this setting on your own risk, because it can hide valid errors.

How to type a custom models.Field?

[!NOTE] This require type generic support, see this section to enable it.

Django models.Field (and subclasses) are generic types with two parameters: - _ST: type that can be used when setting a value - _GT: type that will be returned when getting a value

When you create a subclass, you have two options depending on how strict you want the type to be for consumers of your custom field.

1. Generic subclass:

from typing import TypeVar, reveal_type
from django.db import models

_ST = TypeVar("_ST", contravariant=True)
_GT = TypeVar("_GT", covariant=True)

class MyIntegerField(models.IntegerField[_ST, _GT]):
    ...

class User(models.Model):
    my_field = MyIntegerField()


reveal_type(User().my_field) # N: Revealed type is "int"
User().my_field = "12"  # OK (because Django IntegerField allows str and will try to coerce it)

1. Non-generic subclass (more strict):

from typing import reveal_type
from django.db import models

# This is a non-generic subclass being very explicit
# that it expects only int when setting values.
class MyStrictIntegerField(models.IntegerField[int, int]):
    ...

class User(models.Model):
    my_field = MyStrictIntegerField()


reveal_type(User().my_field) # N: Revealed type is "int"
User().my_field = "12" # E: Incompatible types in assignment (expression has type "str", variable has type "int")

See mypy section on generic classes subclasses.

Related projects

• awesome-python-typing - Awesome list of all typing-related things in Python.
• djangorestframework-stubs - Stubs for Django REST Framework.
• pytest-mypy-plugins - pytest plugin that we use for testing mypy stubs and plugins.
• wemake-django-template - Create new typed Django projects in seconds.

Contributing

This project is open source and community driven. As such we encourage contributions big and small. You can contribute by doing any of the following:

1. Contribute code (e.g. improve stubs, add plugin capabilities, write tests etc) - to do so please follow the contribution guide.
2. Assist in code reviews and discussions in issues.
3. Identify bugs and issues and report these
4. Ask and answer questions on StackOverflow

You can always also reach out in gitter to discuss your contributions!