Автоматические аннотации типов в Python — и даже без LLM

Всем привет! Наверное, каждый разработчик рано или поздно приходит к мысли, что аннотированный код писать удобнее. Такой код проще читать, он выглядит более предсказуемым, и мы сразу видим контракт, задокументированный нашими аннотациями. Да, вручную добавлять аннотации типов в Python — занятие довольно медитативное. Но в повседневной разработке оно часто воспринимается как рутина, особенно если речь идёт о тяжёлых фреймворках вроде DRF.
Каждый раз, объявляя новую вьюху, сериализатор или их методы, вы послушно пишете: request: Request, -> Response, serializer: UserSerializer. И было бы здорово, если бы всё это появлялось автоматически. Конечно, можно отправить новый код в нейросеть — и с довольно высокой вероятностью она справится. Но это всё равно потраченные токены и время, и для такой простой задачи кажется не совсем целесообразным. Поэтому в этой статье я постараюсь определить минимальный набор инструментов, который позволит избавиться от ручного написания аннотаций во вьюхах, сериализаторах, а также в собственных функциях и методах, сделав этот процесс максимально простым и незаметным.
Наш целевой вектор
Мы хотим автоматически добавлять аннотации во вьюхи, слои API и бизнес-логику, написанную на чистом Python.
Популярные пакеты вроде django-autotyping умеют работать только с моделями Django и практически бесполезны для API-слоя: они не видят вьюхи и сериализаторы. Поэтому мы соберём другой, полностью рабочий конвейер за несколько шагов:
Поставим под капот переводчик магии Django и DRF на язык типов без конфликтов версий
Будем использовать динамическую генерацию типов: инструмент сам подсмотрит типы во время прогона тестов и впишет аннотации прямо в код
Настроим автоматический вынос «опасных» импортов в блок
if TYPE_CHECKING:, чтобы защитить проект от циклических зависимостей, а также подстрахуемся от падений от сигнатур в среде выполненияДобавим реактивный линтер, который автоматически отформатирует импорты для новых типов и приведёт сами типы к современному стандарту языка.
Шаг 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 — инструмент, разработанный инженерами Instagram, — «подсмотреть», какие типы данных реально проходят через ваши вьюхи во время выполнения тестов, и физически вписать их в код. Когда вы запускаете тесты 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.pyRuff мгновенно приведёт новые импорты в порядок, отсортирует их по алфавиту, обновит устаревший синтаксис до современного вида вроде 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Итог: идеальный рабочий конвейер
Вместо ручного написания типов во вьюхах и собственном коде наш процесс выглядит так:
Пишем код API как обычно, не отвлекаясь на аннотации типов
Покрываем его интеграционными тестами с честными вызовами всех слоёв
Запускаем
monkeytype run -m pytestПрименяем собранные типы командой
monkeytype apply --pep_563 <имя_модуля>Запускаем
ruff check . --fix— линтер наводит швейцарский порядокПеред пушем проверяем всё через быстрый запуск
mypy .(это можно вынести в pre-commit)
В результате при минимуме ручной работы мы получаем предсказуемый, хорошо читаемый и типизированный код, а также надёжную защиту от циклических зависимостей. И всё это — без LLM. Ещё один плюс TDD в нашу копилку.
А как вы автоматизируете типы в своих API‑проектах? Уже пользуетесь такой автогенерацией, доверяете это нейросети или по-старинке пишете всё вручную? Поделитесь в комментариях — будет интересно почитать!
KioskNews shows a cleaned-up reading view extracted from the publisher’s page — the original always lives on their site, not ours.