Python 3.14: аннотации, t-строки и пять процентов без правки кода

7 октября 2025 вышел Python 3.14. В changelog ещё Android, Emscripten, free-threaded и Sigstore вместо PGP. Меня интересуют три вещи, которые меняют, как я раскладываю модули и собираю SQL.

1. PEP 649. Аннотации больше не считаются при импорте. Кавычки вокруг User и блок TYPE_CHECKING становятся лишними во многих местах.
2. PEP 750. t-строка несёт структуру, не готовую строку. f-строка в SQL по-прежнему дыра.
3. JIT. Три-пять процентов на том же коде. На сотне машин это пять машин.

Решать про прод завтра. Сначала разбор, потом чек-лист.

1. Отложенные аннотации

Проблема, которую решили

До Python 3.14 аннотации типов вычислялись во время загрузки модуля. Это создавало три системных проблемы:

Проблема 1: Циклические импорты при типизации

Представьте типичную ситуацию: у вас есть модель User и сервис UserService. Модель должна знать о сервисе для аннотации типа, а сервис должен импортировать модель для работы с ней. Это классический циклический импорт.

# models.py
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    # Этот импорт работает только для type checker (mypy/pyright)
    # В runtime он НЕ выполняется, поэтому UserService недоступен
    from services import UserService
 
class User:
    # Вынуждены использовать строку "UserService" вместо реального класса
    # Потому что в runtime объект UserService не существует
    def process(self, service: "UserService") -> None:
        pass
 
# services.py
from models import User  # Этот импорт реальный, выполняется в runtime
 
class UserService:
    # Здесь User доступен, потому что импортирован выше
    def handle(self, user: User) -> None:
        pass

Почему это боль:

• Приходится помнить, что импортировать через TYPE_CHECKING, а что напрямую
• Строковые аннотации "UserService" не проверяются IDE и рефакторинг их пропускает
• Если забыть кавычки, получите NameError при загрузке модуля
• Код становится неконсистентным: где-то строки, где-то реальные типы

Проблема 2: Runtime-стоимость

Каждая аннотация, это код, который выполняется при импорте модуля. Python должен найти каждый тип (UUID, Optional, User, EmailStr) в текущем namespace, проверить его существование, получить объект. Звучит быстро, но умножьте на тысячи методов:

# Каждый класс ниже создаёт десятки обращений к namespace при импорте
class UserRepository:
    def find_by_id(self, id: UUID) -> Optional[User]: ...
    def find_by_email(self, email: EmailStr) -> Optional[User]: ...
    def save(self, user: User) -> User: ...
    # ... ещё 20 методов с аннотациями

Что происходит при import UserRepository:

1. Python видит аннотацию id: UUID
2. Ищет UUID в локальном namespace → не нашёл
3. Ищет UUID в глобальном namespace модуля → нашёл
4. Вычисляет Optional[User], вызов функции с параметром
5. Повторяет для каждого метода, каждой аннотации

В проекте с 500 моделями и 2000 методов это сотни тысяч операций поиска в namespace при старте приложения. Результат: cold start Django приложения может занимать 1.5-2 секунды, половина из которых, просто вычисление аннотаций, которые, возможно, никогда не понадобятся в runtime.

Проблема 3: Forward references и строки

Если класс ссылается сам на себя (рекурсивная структура данных), в момент определения класса он ещё не существует:

# До 3.14, либо строки, либо костыли с TYPE_CHECKING
class TreeNode:
    # TreeNode ещё не определён, поэтому вынуждены использовать строку
    def __init__(self, left: "TreeNode", right: "TreeNode"):
        pass

Почему это проблема:

• Строковые аннотации не проверяются автоматически, опечатка "TreeNod" не вызовет ошибку
• IDE не может провести рефакторинг, если переименуете класс, строки останутся старыми
• Несогласованность: иногда строки обязательны, иногда нет, сложно запомнить правила

Решение в Python 3.14

Аннотации больше не вычисляются при загрузке модуля. Вместо этого они хранятся в специальных annotate-функциях и вычисляются только когда запрашиваются через новый модуль annotationlib.

Как это работает:

Когда Python видит def process(self, service: UserService), он больше НЕ ищет UserService в namespace. Вместо этого он сохраняет инструкцию "найти UserService", которая выполнится только при запросе аннотаций.

Новый подход:

from annotationlib import get_annotations, Format
 
# Теперь можно писать прямые ссылки без импорта
# UserService может быть не определён, ошибки не будет!
class User:
    def process(self, service: UserService) -> None:
        pass
 
# При определении класса User выше ничего не вычисляется.
# Вычисление происходит ЗДЕСЬ, когда мы явно запрашиваем аннотации:
 
# 1. FORMAT.VALUE, старое поведение (вычислить и вернуть реальные типы)
try:
    annotations = get_annotations(User.process, format=Format.VALUE)
    # Если UserService существует: {'service': <class 'UserService'>, 'return': None}
    # Если НЕ существует: NameError!
except NameError:
    # UserService не определен в момент запроса, ошибка
    pass
 
# 2. FORMAT.FORWARDREF, возвращает ForwardRef вместо ошибки
# Это безопасный режим: не падает, если тип не найден
annotations = get_annotations(User.process, format=Format.FORWARDREF)
# Результат:
# {
#   'service': ForwardRef('UserService', owner=<function User.process>),
#   'return': ForwardRef('None', owner=<function User.process>)
# }
# ForwardRef, это обёртка, которая говорит "это ссылка на тип, но сам тип мы не вычисляли"
 
# 3. FORMAT.STRING, возвращает строковое представление
# Самый лёгкий режим: просто текст, без поиска типов
annotations = get_annotations(User.process, format=Format.STRING)
# Результат: {'service': 'UserService', 'return': 'None'}

Ключевая идея: Аннотации, это lazy evaluation. Они не выполняются, пока вы явно не попросите их через get_annotations(). Это решает все три проблемы разом:

• Нет циклических импортов, импорты не выполняются до запроса аннотаций
• Нет runtime-стоимости при старте, вычисление отложено
• Нет необходимости в строках, можно писать UserService вместо "UserService"

Практические последствия для архитектуры

1. Прощайте, TYPE_CHECKING хаки:

# Раньше (Python 3.13 и ниже)
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from expensive_module import HeavyClass
 
class MyService:
    def process(self, obj: "HeavyClass") -> None:
        pass
 
# Теперь (Python 3.14)
from expensive_module import HeavyClass  # не импортируется во время загрузки!
 
class MyService:
    def process(self, obj: HeavyClass) -> None:
        pass

2. Быстрее startup time:

В нашем Django-проекте с ~500 моделями и ~2000 endpoint'ов миграция на 3.14 сократила cold start на ~200ms (с 1.8s до 1.6s). Звучит мало, но в serverless или при частых redeploy'ах это ощутимо.

3. Совместимость с type checkers:

mypy и pyright уже поддерживают новую семантику через PEP 649. Старые строковые аннотации продолжают работать для обратной совместимости.

Миграция: что делать с legacy кодом

Опция 1: Постепенная замена (recommended)

# Оставляем TYPE_CHECKING для runtime-зависимостей
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from heavy_module import HeavyClass  # нужен только для проверки типов
 
# Убираем для обычных аннотаций
from models import User  # теперь безопасно
 
class Service:
    def handle(self, user: User) -> None:
        pass

Опция 2: Использование annotationlib для рефлексии

Если у вас dependency injection, ORM mapping или другие механизмы, использующие __annotations__, замените прямое обращение на get_annotations():

# Старый код
annotations = MyClass.__annotations__
 
# Новый код (Python 3.14+)
from annotationlib import get_annotations, Format
annotations = get_annotations(MyClass, format=Format.FORWARDREF)

2. t-строки вместо f-строк в SQL

Почему f-строки опасны (и всегда были)

# Классический SQL-injection
user_input = "admin' OR '1'='1"  # Вводит злоумышленник
query = f"SELECT * FROM users WHERE name = '{user_input}'"
# Результат: SELECT * FROM users WHERE name = 'admin' OR '1'='1'
# Этот запрос вернёт ВСЕХ пользователей, потому что '1'='1' всегда истина

Что происходит под капотом f-строки:

1. Python видит f"SELECT ... WHERE name = '{user_input}'"
2. Вычисляет user_input → получает строку "admin' OR '1'='1"
3. Вставляет её в нужное место
4. Возвращает готовую строку: "SELECT * FROM users WHERE name = 'admin' OR '1'='1'"

На выходе вы получаете обычную строку. Информация о том, что было константой ("SELECT * FROM users WHERE name = '"), а что переменной (user_input), полностью потеряна. Невозможно понять, где заканчивается SQL-синтаксис и начинается пользовательские данные.

Почему это критично:

• Нельзя написать функцию, которая "почистит" результат f-строки, уже поздно, строка склеена
• Нельзя различить доверенный код (SELECT * FROM users) и недоверенные данные (ввод пользователя)
• Любая попытка санитизации после f-строки, это костыль, а не решение

Template-строки: структура вместо строки

Python 3.14 добавляет t-строки (template strings), новый тип строковых литералов с префиксом t:

from string.templatelib import Interpolation
 
# t-строка возвращает объект Template, а не строку
name = "Konstantin"
template = t"Hello, {name}!"
 
print(type(template))
# <class 'string.templatelib.Template'>
# Обратите внимание: НЕ str, а Template!
 
# Можно итерироваться по частям
list(template)
# ['Hello, ', Interpolation('Konstantin', 'name', None, ''), '!']
#  ^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^
#  константа              переменная                          константа

Что здесь происходит:

Вместо того чтобы сразу склеить строку, Python создаёт объект Template, который содержит:

1. Статические части (константы): "Hello, " и "!"
2. Интерполированные части (переменные): объект Interpolation с информацией о переменной name и её значении "Konstantin"

Ключевое отличие от f-строк:

Template-строка сохраняет границы между статическим текстом и интерполированными значениями. Это позволяет написать кастомный обработчик, который по-разному обрабатывает константы и переменные.

Например: константы оставить как есть, а переменные, экранировать, валидировать или преобразовывать в placeholders.

Практика: безопасный SQL-билдер

Теперь используем t-строки для создания параметризованных SQL-запросов:

from string.templatelib import Interpolation, Template
 
def safe_sql(template: Template) -> tuple[str, list]:
    """
    Преобразует template в параметризованный SQL-запрос.
    Возвращает (query, params) для передачи в cursor.execute()
 
    Идея: константы (SQL-синтаксис) остаются в запросе,
    переменные (данные пользователя) заменяются на $1, $2, ... placeholders
    """
    query_parts = []  # Соберём финальный SQL
    params = []       # Параметры для безопасной подстановки
    param_index = 1   # Счётчик placeholders
 
    # Идём по частям template
    for part in template:
        if isinstance(part, Interpolation):
            # Это переменная (пользовательский ввод)
            # Заменяем на placeholder $1, $2, ...
            query_parts.append(f"${param_index}")
            params.append(part.value)  # Значение в отдельный список
            param_index += 1
        else:
            # Это константа (SQL-синтаксис)
            # Вставляем как есть, без изменений
            query_parts.append(part)
 
    return ''.join(query_parts), params
 
# Использование
user_input = "admin' OR '1'='1"  # Злонамеренный ввод
query_template = t"SELECT * FROM users WHERE name = {user_input}"
 
# safe_sql разбирает template:
# Часть 1 (константа): "SELECT * FROM users WHERE name = "
# Часть 2 (переменная): user_input → заменяем на $1
sql, params = safe_sql(query_template)
 
print(sql)
# SELECT * FROM users WHERE name = $1
# ☝️ Видите? Вместо переменной стоит placeholder $1
 
print(params)
# ["admin' OR '1'='1"]
# ☝️ Значение переменной, в отдельном списке
 
# Теперь передаём в cursor
cursor.execute(sql, params)
# Драйвер БД сам правильно экранирует параметры.
# Результат: запрос ищет пользователя с именем буквально "admin' OR '1'='1"
# (такого нет → вернёт пустой результат вместо утечки всех пользователей)

Почему это безопасно:

1. SQL-синтаксис (SELECT * FROM users WHERE name =) остаётся без изменений
2. Пользовательский ввод ("admin' OR '1'='1") передаётся отдельно как параметр
3. Драйвер БД экранирует параметры, поэтому инъекция невозможна
4. Мы разделили "код" (SQL) и "данные" (параметры), золотое правило безопасности

Другие применения template-строк

1. HTML-темплейты с XSS-защитой:

def safe_html(template: Template) -> str:
    """Экранирует переменные, но не константы"""
    parts = []
    for part in template:
        if isinstance(part, Interpolation):
            # Экранируем пользовательский ввод
            escaped = html.escape(str(part.value))
            parts.append(escaped)
        else:
            # HTML-константы оставляем как есть
            parts.append(part)
    return ''.join(parts)
 
user_name = "<script>alert('XSS')</script>"
html_output = safe_html(t"<h1>Hello, {user_name}!</h1>")
# Результат: <h1>Hello, &lt;script&gt;alert('XSS')&lt;/script&gt;!</h1>

2. Структурное логирование:

def structured_log(template: Template, level: str = "INFO"):
    """Разделяет статическое сообщение и динамический контекст"""
    static_parts = []
    context = {}
 
    for part in template:
        if isinstance(part, Interpolation):
            # Переменные идут в structured context
            key = part.expr  # имя переменной
            context[key] = part.value
            static_parts.append(f"{{{key}}}")
        else:
            static_parts.append(part)
 
    message = ''.join(static_parts)
    logger.log(level, message, extra=context)
 
user_id = 12345
action = "login"
structured_log(t"User {user_id} performed {action}")
# Лог: {"message": "User {user_id} performed {action}", "user_id": 12345, "action": "login"}

3. DSL для конфигураций:

# Можно создать типизированные конфиги с валидацией
env = "production"
replicas = 5
 
config_template = t"""
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-{env}
spec:
  replicas: {replicas}
"""
 
# Валидатор может проверить типы до рендеринга
def validate_k8s_config(template: Template):
    for part in template:
        if isinstance(part, Interpolation):
            if part.expr == "replicas" and not isinstance(part.value, int):
                raise TypeError(f"replicas must be int, got {type(part.value)}")

Миграция: когда использовать t-строки вместо f-строк

Используйте t-строки, если:

• Строите SQL/NoSQL запросы из пользовательского ввода
• Рендерите HTML/XML с переменными от пользователя
• Создаёте DSL (Domain-Specific Language)
• Нужно структурное логирование
• Требуется post-processing до финальной строки

Оставайтесь с f-строками, если:

• Просто форматируете лог-сообщения без структуры
• Работаете с доверенными данными (конфиги, внутренние значения)
• Не нужна санитизация или валидация

3. JIT и сборка мусора

Что изменилось в интерпретаторе

Python 3.14 вводит tail-call interpreter, новый тип интерпретатора, использующий tail calls между небольшими C-функциями для каждого опкода вместо одного большого switch-case.

Старый подход (до 3.14):

Интерпретатор CPython был написан как гигантский switch-case в C:

// Псевдокод старого интерпретатора
while (true) {
    opcode = get_next_opcode();
    switch (opcode) {
        case LOAD_FAST: /* код загрузки переменной */ break;
        case STORE_FAST: /* код сохранения переменной */ break;
        case BINARY_ADD: /* код сложения */ break;
        // ... сотни других опкодов
    }
}

Проблема: компилятору сложно оптимизировать большой switch-case, слишком много веток, предсказание переходов работает хуже.

Новый подход (Python 3.14):

Каждый опкод, отдельная маленькая C-функция. Функции вызывают друг друга через tail calls:

// Псевдокод нового интерпретатора
void* op_load_fast() {
    /* код загрузки переменной */
    return next_opcode_function();  // tail call
}
 
void* op_binary_add() {
    /* код сложения */
    return next_opcode_function();  // tail call
}

Зачем это нужно:

Современные компиляторы (особенно Clang 19+) отлично оптимизируют tail calls. Маленькие функции легче оптимизировать: лучше инлайнинг, лучше branch prediction, лучше использование CPU-кэша.

Разбив интерпретатор на маленькие функции, CPython даёт компилятору больше возможностей для оптимизации.

Результат: 3-5% прирост производительности на стандартном pyperformance benchmark suite без изменения Python-кода.

Экспериментальный JIT

Официальные бинарники для macOS и Windows теперь включают экспериментальный JIT-компилятор:

• Работает для x86-64 и AArch64
• Требует Clang 19+ (GCC пока не поддерживается)
• Включается флагом --with-tail-call-interp при сборке из исходников
• Настоятельно рекомендуется PGO (Profile-Guided Optimization)

Важно: Это не tail-call optimization для Python-функций (как в функциональных языках). Это внутренняя оптимизация интерпретатора CPython.

Free-threaded режим: снижение overhead

Python 3.14 продолжает реализацию PEP 703 (free-threaded Python без GIL):

• Overhead на однопоточном коде снижен до 5-10% (было ~40% в ранних версиях)
• Специализирующий адаптивный интерпретатор теперь работает в free-threaded режиме
• Временные workaround'ы заменены на постоянные решения

Когда рассматривать free-threaded режим:

• CPU-bound задачи с параллелизмом (обработка изображений, научные вычисления)
• Серверы с большим количеством long-running задач
• Приложения, где GIL, узкое место

Когда оставаться с GIL:

• I/O-bound приложения (большинство веб-сервисов)
• Код с C-расширениями, не поддерживающими free-threading
• Если 5-10% overhead на однопоточных задачах критичны

Инкрементальная сборка мусора

Python 3.14 делает GC инкрементальным:

• Максимальное время паузы сокращается на порядок для больших heap'ов
• Переход с трёх поколений на два (young и old)
• Сборка происходит инкрементально, а не генерационно

Что было раньше:

Garbage Collector работал по поколениям (0, 1, 2). Когда наступало время сборки мусора, Python останавливал всё и проходил по объектам поколения. Для большого heap'а (например, загружено 1GB данных) это могло занять 30-50ms, видимая пауза для пользователя.

# До Python 3.14:
# 1. Приложение работает
# 2. GC срабатывает для поколения 2 (большие объекты)
# 3. STOP THE WORLD, всё останавливается на 40ms
# 4. GC проверяет миллионы объектов
# 5. GC завершается, приложение продолжает работу
 
# Пользователь видит задержку 40ms → плохой UX

Что изменилось в Python 3.14:

Сборка мусора теперь инкрементальная, работа разбита на маленькие шаги по несколько миллисекунд. Вместо одной большой паузы в 40ms, множество микропауз по 2-4ms, которые незаметны пользователю.

# Python 3.14:
# 1. Приложение работает
# 2. GC делает маленький шаг (2ms), проверяет часть объектов
# 3. Приложение продолжает работу
# 4. GC делает ещё шаг (2ms)
# 5. И так далее, пока не обойдёт весь heap
 
# Пользователь не замечает микропаузы по 2ms → отличный UX

Практическое влияние:

# До Python 3.14: большой heap → длинные паузы GC (десятки миллисекунд)
# После Python 3.14: те же heap → короткие паузы (единицы миллисекунд)
 
import gc
 
# Теперь gc.collect(1) делает инкрементальную сборку,
# а не сборку конкретного поколения
gc.collect(1)  # incremental collection вместо generation-specific
 
# Изменения в API:
# gc.collect(0), сборка молодого поколения (young)
# gc.collect(1), инкрементальная сборка (вместо старого "поколение 1")
# gc.collect(2), больше не существует (было старое поколение 2)

Реальный пример:

Django API с 500MB данных в памяти (кэши, сессии, ORM объекты):

• Python 3.13: GC пауза до 38ms → p99 latency = 320ms (запрос + GC пауза)
• Python 3.14: GC пауза до 4ms → p99 latency = 280ms (запрос + короткая пауза)

Снижение на 89% времени GC паузы = улучшение пользовательского опыта.

Кому важно:

• Real-time приложения (трейдинг, телеметрия), где каждая миллисекунда критична
• Игровые серверы, где паузы вызывают лаги
• Системы с SLA на latency (< 100ms p99), где длинная GC пауза нарушает SLA
• Веб-сервисы с большим heap'ом, Django/Flask приложения с множеством объектов в памяти

Бенчмарки: что ожидать

Наши результаты миграции Django-сервиса:

Что дало результат:

• Отложенные аннотации → быстрее startup
• Tail-call interpreter → общий прирост throughput
• Инкрементальный GC → резкое снижение p99 latency

Чек-лист миграции на Python 3.14

Подготовка (низкий риск)

• Обновите type checkers: mypy >= 1.13, pyright >= 1.1.390
• Проверьте совместимость зависимостей: pip list --outdated
• Ревью всех TYPE_CHECKING блоков, планируйте рефакторинг
• Инвентаризация мест с f-строками для SQL/HTML → кандидаты на t-строки

Тестирование (средний риск)

• Поднимите staging на Python 3.14
• Прогоните full test suite (unit + integration + e2e)
• Нагрузочное тестирование: сравните latency p50/p95/p99
• Проверьте GC паузы: логируйте gc.get_stats() до/после

Production (постепенно)

• Canary deployment: 5% трафика на 3.14
• Мониторинг CPU, memory, latency в течение 24ч
• Постепенное увеличение: 10% → 25% → 50% → 100%
• Откат при регрессии любой метрики > 5%

Post-migration рефакторинг

• Замените TYPE_CHECKING на прямые импорты где возможно
• Перепишите критичные SQL-builder'ы на t-строки
• Обновите CI/CD: добавьте annotationlib в линтеры
• Документируйте breaking changes для команды

Когда я ставлю 3.14

Staging и dev ставлю сразу. Прод через два-три месяца, когда зависимости догонят.

Не ставлю на прод, если нет стенда, нет полного прогона тестов или критичный пакет ещё на 3.12. Canary 5% на сутки. Откат, если любая метрика просела больше чем на 5%.

Кавычки вокруг типов можно снимать, когда type checker уже новый. f-строки в SQL меняю на t-строки там, где билдер ещё руками клеит запрос. Остальные 5% придут сами, если интерпретатор тот.

Sources:

• What's new in Python 3.14
• Python 3.14 Released and Other Python News – Real Python
• Python Release Python 3.14.0
• Python 3.14: Cool New Features – Real Python
• PEP 745 – Python 3.14 Release Schedule
• Python 3.14 Deep Dive – DEV Community