Всем привет! Наверное, каждый разработчик рано или поздно приходит к мысли, что аннотированный код писать удобнее. Такой код проще читать, он выглядит более предсказуемым, и мы сразу видим контракт, задокументированный нашими аннотациями. Да, вручную добавлять аннотации типов в Python — занятие довольно медитативное. Но в повседневной разработке оно часто воспринимается как рутина, особенно если речь идёт о тяжёлых фреймворках вроде DRF.

Каждый раз, объявляя новую вьюху, сериализатор или их методы, вы послушно пишете: request: Request, -> Response, serializer: UserSerializer. И было бы здорово, если бы всё это появлялось автоматически. Конечно, можно отправить новый код в нейросеть — и с довольно высокой вероятностью она справится. Но это всё равно потраченные токены и время, и для такой простой задачи кажется не совсем целесообразным. Поэтому в этой статье я постараюсь определить минимальный набор инструментов, который позволит избавиться от ручного написания аннотаций во вьюхах, сериализаторах, а также в собственных функциях и методах, сделав этот процесс максимально простым и незаметным.

Наш целевой вектор

Мы хотим автоматически добавлять аннотации во вьюхи, слои API и бизнес-логику, написанную на чистом Python.

Популярные пакеты вроде django-autotyping умеют работать только с моделями Django и практически бесполезны для API-слоя: они не видят вьюхи и сериализаторы. Поэтому мы соберём другой, полностью рабочий конвейер за несколько шагов:

  1. Поставим под капот переводчик магии Django и DRF на язык типов без конфликтов версий

  2. Будем использовать динамическую генерацию типов: инструмент сам подсмотрит типы во время прогона тестов и впишет аннотации прямо в код

  3. Настроим автоматический вынос «опасных» импортов в блок if TYPE_CHECKING:, чтобы защитить проект от циклических зависимостей, а также подстрахуемся от падений от сигнатур в среде выполнения

  4. Добавим реактивный линтер, который автоматически отформатирует импорты для новых типов и приведёт сами типы к современному стандарту языка.


Шаг 1. Базовый фундамент и укрощение настроек MyPy

Чтобы ваша IDE и статические анализаторы вообще понимали контекст Django REST Framework — что такое Request, откуда у сериализатора берётся метод .is_valid() и т.д., — нужен набор файлов деклараций типов (стабы). К счастью, такой пакет уже давно написан сторонними разработчиками и фактически стал стандартом: это django-stubs.

pip install "djangorestframework-stubs[compatible-mypy]"

Пакет django-stubs (базовые типы Django) уже входит в состав djangorestframework-stubs (стабы для DRF) как обязательная зависимость и установится автоматически. А флаг [compatible-mypy] подберёт именно ту версию mypy, с которой этот релиз стабов гарантированно протестирован и не упадёт с внутренними ошибками типизатора. Важно понимать, что эти инструменты работают только на этапе анализа — внутри вашей IDE или при запуске mypy — и никак не влияют на работу проекта в рантайме.

Заглянем в конфигурацию пакета

Она находится в корне проекта, в файле pyproject.toml. Давайте разберём блок [tool.mypy] построчно, чтобы понять, как управлять строгостью типизации:

[tool.mypy]
python_version = "3.13"

# Подключаем плагины, которые «оживляют» магию моделей, менеджеров и сериализаторов
plugins = [
    "mypy_django_plugin.main",
    "mypy_drf_plugin.main"
]

# Включаем проверку тел функций, у которых нет аннотаций. 
check_untyped_defs = true

# Самый строгий режим: запрещает объявлять функции без аннотаций аргументов или return.
disallow_untyped_defs = true

# Запрещает неявное использование Optional. 
no_implicit_optional = true

# Ругается, если функция с явной аннотацией типа возвращает Any.
warn_return_any = true

# Включаем строгую проверку работы с None (защита от ошибок AttributeError: 'NoneType' object has no attribute...).
strict_optional = true

# Заставляет mypy показывать коды ошибок в терминале (например, [attr-defined]), чтобы их можно было точечно глушить через type: ignore.
show_error_codes = true

[tool.django-stubs]
# Указываем mypy, где искать настройки Django, чтобы он смог прочитать реестр ваших моделей
django_settings_module = "my_project.settings"

Шаг 2. Автотипизация кода через MonkeyType

Поскольку статически угадать типы аргументов во вьюхах сложно, мы используем динамический подход. Для этого заставим инструмент MonkeyType (популярная библиотека динамического анализа типов) «подсмотреть», какие типы данных реально проходят через ваши вьюхи во время выполнения тестов, и физически вписать их в код. Когда вы запускаете тесты API через pytest, через методы вьюх гарантированно проходят живые объекты Request и Response. По тому же принципу этот пакет поможет автоматически типизировать и наш собственный код, написанный на чистом Python.

Подрубаем CLI-контекст для Django (критически важно)

Если просто запустить генерацию типов в Django-проекте, то вы соберёте все классические ошибки: сначала ImproperlyConfigured, а затем AppRegistryNotReady: Apps aren't loaded yet. Это происходит потому, что при выполнении команды генерации инструмент напрямую импортирует ваши файлы с вьюхами, а окружение Django к этому моменту ещё не инициализировано. Чтобы элегантно решить эту проблему, мы используем встроенный в MonkeyType метод cli_context. Создадим в корне проекта конфигурационный файл monkeytype_config.py:

import os
from contextlib import contextmanager
import django
from monkeytype.config import DefaultConfig

class DjangoAwareConfig(DefaultConfig):
    """Конфиг MonkeyType, который корректно инициализирует Django внутри CLI-контекста."""

    @contextmanager
    def cli_context(self, command: str):
        # Указываем путь к настройкам проекта
        os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_sandbox.settings")
        # Принудительно запускаем инициализацию приложений Django до импорта модулей!
        django.setup()
        yield

CONFIG = DjangoAwareConfig()

Магия автоматизации и секретный флаг

Если в вашем проекте для тестов используется pytest, а в файле pytest.ini уже указана переменная DJANGO_SETTINGS_MODULE, то следующая команда выполнится успешно даже без переменной окружения и без отдельного конфигурационного файла. Но поскольку он уже написан, не будем усложнять себе жизнь. Команда прогонит все тесты проекта (при желании можно указать путь до модуля или файла) и сохранит собранные типы в локальную SQLite-базу.

monkeytype run -m pytest

Теперь применим эти типы к нашему коду. Для этого запускаем команду, которая применит сгенерированные типы к нашему модулю, и передаём секретный флаг — --pep_563.

monkeytype apply --pep_563 sandbox.views

Мы видим успешный вывод в консоли — значит, магия сработала. Давайте посмотрим, что изменилось.

Код до применения команды:

from rest_framework import generics, status
from rest_framework.response import Response

from sandbox.models import Customer
from sandbox.serializers import CustomerSerializer
from sandbox.services import ServiceError, acquire_customer_data



class CreateCustomerView(generics.GenericAPIView):
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer

    def post(self, request, *args, **kwargs):
        try:
            customer_data = acquire_customer_data(request.data.get('customer_id'))
        except ServiceError:
            return Response(status=status.HTTP_400_BAD_REQUEST)

        serializer = self.get_serializer(data=customer_data)
        serializer.is_valid(raise_exception=True)
        serializer.save()

        return Response(serializer.data, status=status.HTTP_201_CREATED)

Код после:

from __future__ import annotations
from rest_framework import generics, status
from rest_framework.response import Response

from sandbox.models import Customer
from sandbox.serializers import CustomerSerializer
from sandbox.services import ServiceError, acquire_customer_data
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from rest_framework.request import Request



class CreateCustomerView(generics.GenericAPIView):
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer

    def post(self, request: Request, *args, **kwargs) -> Response:
        try:
            customer_data = acquire_customer_data(request.data.get('customer_id'))
        except ServiceError:
            return Response(status=status.HTTP_400_BAD_REQUEST)

        serializer = self.get_serializer(data=customer_data)
        serializer.is_valid(raise_exception=True)
        serializer.save()

        return Response(serializer.data, status=status.HTTP_201_CREATED)

Код теста (для информации):

import json

import pytest
from django.urls import reverse
from rest_framework import status

from sandbox.models import Customer


@pytest.mark.django_db
def test_create_customer_ok(client) -> None:

    response = client.post(
        reverse('create_customer'),
        data=json.dumps({'customer_id': 0}),
        content_type='application/json',
    )

    assert response.status_code == status.HTTP_201_CREATED
    assert Customer.objects.count() == 1
    assert response.json()['username'] == 'Tester'
    assert response.json()['category'] == 'regular'

В результате в коде появляются аннотации типов аргументов метода и возвращаемых значений, а также две важные строки: from future import annotations и if TYPE_CHECKING.

Кому-то может показаться, что использовать одновременно from future import annotations и if TYPE_CHECKING: — это избыточно. Но на самом деле эти конструкции решают разные задачи, работают на разных уровнях и вместе дают полноценную защиту от падения проекта.

if TYPE_CHECKING защищает от падения ПРИ ИМПОРТИРОВАНИИ — то есть в среде выполнения. Этот блок определяет, какие модули Python будет реально загружать в память при старте проекта. Если оставить открытым импорт Request или ваших моделей, Python при запуске обязан зайти в эти файлы. А если между вашими модулями есть тяжёлая циклическая зависимость — например, View импортирует Serializer, а Serializer в ответ импортирует View — проект может упасть с ошибкой ImportError ещё до того, как дойдёт до вызова функций. Но в среде выполнения флаг TYPE_CHECKING всегда равен False, поэтому Python просто проигнорирует и пропустит этот блок. Циклическая зависимость уничтожена.

from future import annotations защищает от падения В СИГНАТУРЕ. Поскольку среда выполнения Python пропустила вышеописанный блок импортов, в памяти физически не существует класса Request. Когда интерпретатор дойдёт до строки def post(self, request: Request), он споткнётся и выдаст: NameError: name 'Request' is not defined. Раньше это приходилось исправлять вручную, обёртывая типы в кавычки: request: 'Request'. Теперь же одна эта директива автоматически превращает Request в строку 'Request' на уровне синтаксического дерева. Python спокойно читает сигнатуру, не требуя наличия живого класса в памяти.

Итог такого симбиоза: if TYPE_CHECKING: убирает физический импорт файла, а from future import annotations избавляет от необходимости писать кавычки вокруг типов. А с флагом --pep_563 MonkeyType умеет генерировать эту связку сам — profit!

Шаг 3. Ruff — наводим идеальный порядок

После выполнения команды MonkeyType импорты могут оказаться неотсортированными, а типы в аннотациях — записанными в устаревшем формате. Для наглядности прогоняем команду на слое сервиса, который вызывается из нашей вьюхи. Поскольку тест интеграционный (на ручку), он честно проходит всю цепочку View → Serivce → Client. А значит, мы собрали все нужные типы сразу во всех слоях.

monkeytype apply sandbox.services

Код до:

from sandbox.clients import get_customer_data, get_customer_extra


class ServiceError(Exception):
    """Service Error."""


def acquire_customer_data(customer_id):
    try:
        customer_data = get_customer_data(customer_id)
        customer_extra_data = get_customer_extra(customer_data['username'])
        customer_data.update(customer_extra_data.to_dict())
    except Exception as exc:
        raise ServiceError from exc

    return customer_data

Код после:

from sandbox.clients import get_customer_data, get_customer_extra
from datetime import date
from typing import Dict, Union


class ServiceError(Exception):
    """Service Error."""


def acquire_customer_data(customer_id: int) -> Dict[str, Union[str, date, int]]:
    try:
        customer_data = get_customer_data(customer_id)
        customer_extra_data = get_customer_extra(customer_data['username'])
        customer_data.update(customer_extra_data.to_dict())
    except Exception as exc:
        raise ServiceError from exc

    return customer_data

Помимо неотсортированных импортов, видно, что используются старые типы — Dict, Union, хотя у нас уже Python 3.13.

На помощь нам приходит линтер и форматер кода Ruff, который умеет приводить типы к современному стандарту. Добавим в pyproject.toml нужные настройки линтера.

[tool.ruff]
target-version = "py313"
preview = true
unsafe-fixes = true

[tool.ruff.lint]
select = [
    "F",   # Находит пропущенные импорты
    "UP",  # pyupgrade (переводит типы на новый синтаксис)
    "I",   # isort (автоматическая сортировка импортов)
    "ANN", # flake8-annotations (контроль наличия типов)
]
ignore = [
    "django-model-without-dunder-str",
    "missing-type-args",
    "missing-type-kwargs",
    "missing-type-self",
    "missing-type-cls",
]

[tool.ruff.lint.flake8-annotations]
mypy-init-return = true

Теперь прогоним линтер с параметром фикса на нашем файле:

ruff check --fix sandbox/services.py

Ruff мгновенно приведёт новые импорты в порядок, отсортирует их по алфавиту, обновит устаревший синтаксис до современного вида вроде str | None и подсветит редкие места, до которых тесты не смогли дотянуться.

from datetime import date

from sandbox.clients import get_customer_data, get_customer_extra


class ServiceError(Exception):
    """Service Error."""


def acquire_customer_data(customer_id: int) -> dict[str, str | date | int]:
    try:
        customer_data = get_customer_data(customer_id)
        customer_extra_data = get_customer_extra(customer_data['username'])
        customer_data.update(customer_extra_data.to_dict())
    except Exception as exc:
        raise ServiceError from exc

    return customer_data

Итог: идеальный рабочий конвейер

Вместо ручного написания типов во вьюхах и собственном коде наш процесс выглядит так:

  1. Пишем код API как обычно, не отвлекаясь на аннотации типов

  2. Покрываем его интеграционными тестами с честными вызовами всех слоёв

  3. Запускаем monkeytype run -m pytest

  4. Применяем собранные типы командой monkeytype apply --pep_563 <имя_модуля>

  5. Запускаем ruff check . --fix — линтер наводит швейцарский порядок

  6. Перед пушем проверяем всё через быстрый запуск mypy . (это можно вынести в pre-commit)

В результате при минимуме ручной работы мы получаем предсказуемый, хорошо читаемый и типизированный код, а также надёжную защиту от циклических зависимостей. И всё это — без LLM. Ещё один плюс TDD в нашу копилку.

А как вы автоматизируете типы в своих API‑проектах? Уже пользуетесь такой автогенерацией, доверяете это нейросети или по-старинке пишете всё вручную? Поделитесь в комментариях — будет интересно почитать!

Комментарии (0)