Django REST Framework Type Stubs

3.16.9 · active · verified Thu Apr 09

djangorestframework-stubs provides PEP-484 type stubs for the Django REST Framework (DRF) library, enabling static type checking with tools like MyPy. It ensures type correctness for DRF components, improving code quality and maintainability. The current version is 3.16.9, with new releases often accompanying updates to DRF, Django, or MyPy.

Warnings

breaking Version 3.16.9 is the *last* release that officially supports `django-stubs` 5.2 and `djangorestframework` 3.16. Subsequent versions will target newer DRF (3.17+) and `django-stubs` (6.0+) versions, potentially requiring concurrent upgrades.
Fix: Plan to upgrade `djangorestframework` and `django-stubs` alongside `djangorestframework-stubs` to maintain type checking compatibility and prevent errors.
breaking The workaround for the `ModelSerializer.instance` field when `many=True` was removed in version 3.16.3. This change might affect custom `ModelSerializer` implementations that relied on the previous behavior for correct typing.
Fix: Review `ModelSerializer` implementations, especially those with `many=True`, and adjust their typing to align with DRF's standard type expectations. Consult GitHub issue #827 if type errors or regressions occur.
gotcha The `types-requests` dependency became optional in version 3.16.8. If your project uses `rest_framework.test.RequestsClient` (e.g., in test suites), you must now install `djangorestframework-stubs` with the `[requests]` extra to ensure proper type hints.
Fix: If `RequestsClient` is used, update your installation command to `pip install djangorestframework-stubs[requests]`.
gotcha Maintaining compatibility across `djangorestframework-stubs`, `djangorestframework`, `django-stubs`, and `mypy` is crucial. Mismatched versions can lead to incorrect type checking results, MyPy errors, or missing type information.
Fix: Always refer to the `djangorestframework-stubs` release notes and documentation for recommended version ranges for its dependencies, especially when performing upgrades. Pinning versions in `requirements.txt` is advisable.

Install

pip install djangorestframework-stubs Base installation
pip install djangorestframework-stubs[requests] With requests client support (for RequestsClient)

Imports

ModelSerializer
```
from rest_framework.serializers import ModelSerializer
```
Stubs provide type hints for symbols imported from djangorestframework itself; you do not import directly from `djangorestframework-stubs`.
ViewSet
```
from rest_framework.viewsets import ViewSet
```
Stubs provide type hints for symbols imported from djangorestframework itself; you do not import directly from `djangorestframework-stubs`.
Request
```
from rest_framework.request import Request
```
Stubs provide type hints for symbols imported from djangorestframework itself; you do not import directly from `djangorestframework-stubs`.

Quickstart

This example showcases type-hinted Django REST Framework components. When `djangorestframework-stubs` is installed alongside `django-stubs` and `mypy` with the respective plugins configured, your static type checker will enforce type correctness for DRF-specific constructs like `serializers`, `views`, and `requests` at development time.

import os
from django.db import models
from rest_framework import serializers, viewsets
from rest_framework.response import Response
from rest_framework.request import Request # For type hinting

# A minimal Django model (assuming Django and django-stubs are installed)
class MyModel(models.Model):
    name: models.CharField = models.CharField(max_length=100)
    value: models.IntegerField = models.IntegerField()

    def __str__(self) -> str:
        return self.name

# A DRF ModelSerializer for MyModel
class MyModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = ['id', 'name', 'value']

# A DRF ViewSet for MyModel
class MyModelViewSet(viewsets.ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer

    # Example of a custom action with type hints
    def list(self, request: Request, *args, **kwargs) -> Response:
        # With djangorestframework-stubs installed, MyPy can check types here.
        # For instance, ensuring 'request.user' (if present) is accessed correctly.
        queryset = self.filter_queryset(self.get_queryset())
        serializer = self.get_serializer(queryset, many=True)
        return Response(serializer.data)

# To utilize these stubs, configure MyPy (e.g., in pyproject.toml or mypy.ini):
# [tool.mypy]
# plugins = [
#     "mypy_django_plugin.main",
#     "mypy_drf_plugin.main"
# ]
# strict = true

# Then run: `mypy your_app_name/`

# This code focuses on demonstrating type hinting for DRF components,
# not on running a live Django/DRF application.

view raw JSON →