Type annotations for Django models

Django models (and other components) are hard to annotate because there is a lot of magic behind them, good news is that a group of cool developers have already done the hard work for us.

django-stubs provides a set of stubs and mypy plugins which provide static types and type inference for Django.

For instance, having the following model:

from django.contrib.auth import get_user_model
from django.db import models

User = get_user_model()

class Post(models.Model):
    title = models.CharField(max_length=255)
    pubdate = models.DateTimeField()
    author = models.ForeignKey(User, on_delete=models.CASCADE)

mypy would complain saying:

demo$ mypy .
demo/models.py:9: error: Need type annotation for 'title'
demo/models.py:10: error: Need type annotation for 'pubdate'
demo/models.py:11: error: Need type annotation for 'author'
Found 3 errors in 1 file (checked 5 source files)

To fix it, it’s enough to install the package

pip install django-stubs

and create a setup.cfg file with the following:

mypy_path = ./demo
plugins =

strict_optional = True

django_settings_module = demo.settings

(Don’t forget to update mypy_path and django_settings_module to point to the directory of your settings module, according to how yours is named)

Once this is done, mypy will be able to infer and check annotations for Django models (and other components).

demo$ mypy .
Success: no issues found in 5 source files

Here is an example of the usage in a small view:

from django.db.models.query import QuerySet
from django.http import HttpRequest, HttpResponse
from django.shortcuts import render

from demo.models import Post

def _get_posts() -> 'QuerySet[Post]':
    return Post.objects.all()

def posts(request: HttpRequest, template: str="posts.html") -> HttpResponse:
    return render(request, template, {'posts': _get_posts()})

Once again, mypy is happy with the provided annotations:

demo$ mypy .
Success: no issues found in 7 source files

On the same note, a package for Django Rest Framework is also available: djangorestframework-stubs.

Leave a Comment