Переменные типа TypeVar в Python
Обновлено:
Мы уже умеем аннотировать функции с помощью конкретных типов данных:
int
str
list[int]
dict[str, float]
Также мы познакомились с универсальными аннотациями:
Any
Iterable
Sequence
Mapping
Но иногда функция должна работать с объектами разных типов и при этом сохранять информацию об исходном типе данных.
Для таких случаев существует TypeVar из модуля typing.
1. Проблема с Any и object
Предположим, мы хотим написать функцию, которая принимает список, создаёт его копию в обратном порядке и возвращает результат.
При этом нам совершенно не важно, что находится внутри списка.
Это могут быть:
list[int]
list[str]
list[float]
или другие списки.
Можно использовать уже знакомую аннотацию Any:
from typing import Any
def reverse_copy(
values: list[Any],
) -> list[Any]:
return values[::-1]
Такая функция может принимать списки с разными типами элементов:
numbers = [10, 20, 30]
result = reverse_copy(numbers)
print(result)
# [30, 20, 10]
Но возникает проблема.
Если мы наведём курсор на result в редакторе кода, статический анализатор будет видеть возвращаемый тип:
list[Any]
Хотя мы передали:
list[int]
и точно знаем, что функция не меняла типы элементов.
Получается, мы потеряли полезную информацию.
А если использовать object?
Можно написать:
def reverse_copy(
values: list[object],
) -> list[object]:
return values[::-1]
Но тогда возвращаемый тип будет:
list[object]
Мы снова не получим информацию о конкретном типе элементов.
Более того, здесь существует дополнительное ограничение: list[int] не считается совместимым с list[object] при статической проверке. Это связано с изменяемостью списков и особенностями их типизации.
Поэтому для подобных функций ни Any, ни object не являются лучшим решением.
Нам необходим способ связать тип элементов входного списка с типом элементов результата.
2. Аннотация TypeVar
Импортируем:
from typing import TypeVar
Теперь создадим специальную переменную типа:
T = TypeVar('T')
Здесь:
T— имя, под которым мы будем использовать переменную типа;TypeVar()— специальный объект из модуляtyping;'T'— имя переменной типа, передаваемое при её создании.
Имя T является общепринятым сокращением от Type.
Его удобно воспринимать как место для конкретного типа, который будет определён при использовании функции.
Теперь можно использовать T в аннотациях.
3. Первая функция с TypeVar
Перепишем предыдущий пример:
from typing import TypeVar
T = TypeVar('T')
def reverse_copy(
values: list[T],
) -> list[T]:
return values[::-1]
Обратите внимание на сигнатуру:
values: list[T]
и:
-> list[T]
Одна и та же переменная типа используется и для аргумента, и для результата.
Это означает:
Функция возвращает список с тем же типом элементов, что и у переданного списка.
Например:
numbers = [10, 20, 30]
result = reverse_copy(numbers)
Теперь анализатор типов может определить:
numbers → list[int]
result → list[int]
А если передать строки:
languages = ['Python', 'SQL', 'Django']
result = reverse_copy(languages)
получим:
languages → list[str]
result → list[str]
Тип возвращаемого значения определяется на основании типа переданного аргумента.
4. Как работает T
Посмотрим на эту функцию ещё раз:
def reverse_copy(
values: list[T],
) -> list[T]:
return values[::-1]
Можно представить следующую связь:
Принимаем list[int]
↓
T = int
↓
Возвращаем list[int]
Или:
Принимаем list[str]
↓
T = str
↓
Возвращаем list[str]
Или:
Принимаем list[float]
↓
T = float
↓
Возвращаем list[float]
Очень важно: TypeVar не преобразует объекты из одного типа в другой.
Он также не выполняет автоматическую проверку типов во время работы Python.
Это инструмент статической типизации, позволяющий сохранить связь между типами различных частей сигнатуры функции.
Функции, использующие такие переменные типа, называются обобщёнными — generic functions.
5. Где объявлять TypeVar
При использовании классического синтаксиса переменную типа обычно объявляют на уровне модуля, после импортов.
Например:
from collections.abc import Iterable
from typing import TypeVar
T = TypeVar('T')
def make_list(
values: Iterable[T],
) -> list[T]:
return list(values)
В результате:
numbers = make_list((10, 20, 30))
анализатор определит:
list[int]
А:
words = make_list({'Python', 'SQL'})
будет иметь тип:
list[str]
Этот пример особенно хорошо показывает преимущества TypeVar.
Функция принимает любой подходящий итерируемый объект, но сохраняет информацию о типе его элементов.
6. Другие имена переменных типа
Буква T не является обязательной.
Например:
from typing import TypeVar
S = TypeVar('S')
U = TypeVar('U')
Можно использовать и более понятные названия:
ItemT = TypeVar('ItemT')
NumberT = TypeVar('NumberT')
Распространённые соглашения:
| Имя | Значение |
|---|---|
T |
Произвольный тип |
S, U |
Дополнительные переменные типа |
KT |
Тип ключа (Key Type) |
VT |
Тип значения (Value Type) |
ItemT |
Тип элемента |
NumberT |
Тип числового значения |
Названия T, S, KT и VT часто встречаются в библиотеках и аннотациях Python.
При этом никто не запрещает выбрать другое понятное имя.
Главное, чтобы в классическом объявлении имя переменной типа совпадало со строковым именем:
T = TypeVar('T')
или:
ItemT = TypeVar('ItemT')
7. Несколько переменных типа
Иногда функция работает с двумя разными типами данных.
Например:
from typing import TypeVar
KeyT = TypeVar('KeyT')
ValueT = TypeVar('ValueT')
def create_pair(
key: KeyT,
value: ValueT,
) -> tuple[KeyT, ValueT]:
return key, value
Используем:
result = create_pair('age', 30)
Анализатор определит:
tuple[str, int]
А:
result = create_pair(100, 'Python')
будет иметь тип:
tuple[int, str]
Здесь две переменные типа независимы друг от друга.
Первая сохраняет информацию о типе первого аргумента, вторая — о типе второго.
Ограничения TypeVar
8. Перечисление допустимых типов
До этого мы создавали переменные типа без ограничений:
T = TypeVar('T')
Это позволяет использовать практически любой тип данных.
Но иногда функция должна работать только с определёнными типами.
Например, мы хотим поддерживать:
int
float
Для этого можно написать:
from typing import TypeVar
NumberT = TypeVar(
'NumberT',
int,
float,
)
Теперь переменная типа ограничена двумя вариантами.
Используем её:
def choose_smaller(
first: NumberT,
second: NumberT,
) -> NumberT:
if first < second:
return first
return second
Примеры:
print(choose_smaller(10, 20))
# 10
print(choose_smaller(3.5, 2.5))
# 2.5
Такой способ позволяет указать, что функция работает с числами из определённого набора типов.
Зачем это нужно?
Обычный:
T = TypeVar('T')
ничего не гарантирует о том, какие операции поддерживает T.
Например, не для любых объектов можно использовать:
first < second
А ограничив переменную типами int и float, мы сообщаем анализатору, что эти операции допустимы.
Важный нюанс: ограничения не означают проверку точного класса через type(). Подтипы также могут подходить, а анализатор сопоставляет результат одному из перечисленных допустимых типов.
9. Ограничения для str и bytes
Рассмотрим более наглядный пример.
from typing import TypeVar
TextT = TypeVar(
'TextT',
str,
bytes,
)
def combine_text(
first: TextT,
second: TextT,
) -> TextT:
return first + second
Функция может объединять обычные строки:
print(
combine_text('Hello, ', 'Python')
)
# Hello, Python
Или байтовые строки:
print(
combine_text(b'Hello, ', b'Python')
)
# b'Hello, Python'
Но такой вызов не соответствует аннотации:
combine_text('Hello, ', b'Python')
Почему?
Потому что TextT в рамках этого вызова должен соответствовать одному из допустимых вариантов.
Для обоих аргументов должна быть выбрана согласованная разновидность строк.
Таким образом, перечисление ограничений особенно полезно, когда функция должна работать с несколькими типами, но не допускать их произвольного смешивания.
Параметр bound
10. Ограничение через верхнюю границу типа
В TypeVar() существует необязательный параметр:
bound
Он позволяет указать верхнюю границу допустимого типа.
Например:
from typing import TypeVar
TextT = TypeVar(
'TextT',
bound=str,
)
Это означает, что TextT должен соответствовать str или его подтипу.
Почему это полезно?
Потому что в Python можно создавать собственные классы, наследующиеся от других классов.
Например, в будущем мы сможем создать собственный класс на основе str.
Аннотация с bound=str позволит сохранить информацию о таком конкретном подтипе.
11. Пример с bound=str
from typing import TypeVar
TextT = TypeVar(
'TextT',
bound=str,
)
def keep_text(value: TextT) -> TextT:
return value
Обычный вызов:
result = keep_text('Python')
даст анализатору информацию:
str
Если в будущем мы передадим экземпляр собственного класса, наследующегося от str, анализатор сможет сохранить информацию именно об этом классе.
Это одно из отличий bound от перечисления ограничений.
12. bound=Hashable
Рассмотрим ещё один полезный пример.
Импортируем:
from collections.abc import Hashable
from typing import TypeVar
Мы уже знаем, что ключи обычного словаря должны быть хешируемыми.
Поэтому можно создать:
KT = TypeVar(
'KT',
bound=Hashable,
)
Здесь:
KT
означает тип ключа.
А:
bound=Hashable
сообщает, что ключ должен поддерживать хеширование.
Например, допустимы:
int
str
tuple с хешируемыми элементами
frozenset
Но обычные изменяемые списки или словари не подходят.
13. KT и VT для словаря
Создадим сразу две переменные типа:
from collections.abc import Hashable
from typing import TypeVar
KT = TypeVar(
'KT',
bound=Hashable,
)
VT = TypeVar('VT')
Теперь напишем функцию:
def copy_dictionary(
data: dict[KT, VT],
) -> dict[KT, VT]:
return data.copy()
Что означает такая аннотация?
dict[KT, VT]
Первый параметр:
KT
описывает тип ключей.
Второй:
VT
описывает тип значений.
Например:
users = {
'Alex': 30,
'Emma': 25,
}
result = copy_dictionary(users)
Анализатор определит:
dict[str, int]
Если передать:
products = {
101: ['keyboard', 'mouse'],
102: ['monitor'],
}
result = copy_dictionary(products)
результат будет иметь тип:
dict[int, list[str]]
Таким образом, мы сохранили сразу две важные характеристики:
- тип ключей;
- тип значений.
При этом copy() создаёт поверхностную копию словаря. Если значения являются изменяемыми объектами, они не копируются рекурсивно.
14. bound с несколькими допустимыми типами
В bound можно использовать объединение типов:
from typing import TypeVar
TextT = TypeVar(
'TextT',
bound=str | bytes,
)
Это означает:
TextTможет соответствоватьstr,bytesили совместимому подтипу одного из них.
Например:
def return_unchanged(value: TextT) -> TextT:
return value
Вызов:
result = return_unchanged('Python')
сохраняет тип str.
А:
result = return_unchanged(b'Python')
сохраняет тип bytes.
Такое ограничение отличается от:
TextT = TypeVar(
'TextT',
str,
bytes,
)
15. Разница между bound и перечислением типов
Это одно из самых важных отличий.
Вариант №1. Перечисление ограничений
TextT = TypeVar(
'TextT',
str,
bytes,
)
Анализатор должен выбрать один из перечисленных типов: str или bytes.
Если мы передадим экземпляр класса, который наследуется от str, для такой переменной результат обычно будет определён как str, а не как конкретный дочерний класс.
То есть тип сводится к одному из заданных ограничений.
Кроме того, в функции с несколькими аргументами одного TextT это помогает требовать согласованность типов, как в нашем примере combine_text().
Вариант №2. Верхняя граница
TextT = TypeVar(
'TextT',
bound=str | bytes,
)
Здесь анализатор может сохранить более конкретный подтип.
Также при наличии нескольких аргументов он может выбрать общий тип внутри указанной границы, в том числе объединение str | bytes.
Поэтому bound=str | bytes не заменяет ограничения str, bytes, если задача заключается именно в запрете смешивания обычных строк и байтовых строк.
Сравнение
| Запись | Что означает |
|---|---|
TypeVar('T') |
Произвольный тип |
TypeVar('T', int, float) |
Выбор из заданных ограничений |
TypeVar('T', str, bytes) |
Один из двух заданных строковых типов |
TypeVar('T', bound=str) |
str или его подтип |
TypeVar('T', bound=Hashable) |
Любой совместимый хешируемый тип |
TypeVar('T', bound=str \| bytes) |
Тип, совместимый с указанным объединением |
У одного TypeVar нельзя одновременно указать и перечисление ограничений, и bound.
Новый синтаксис Python 3.12
16. Переменная типа прямо в определении функции
Начиная с Python 3.12 появился более компактный синтаксис, описанный в PEP 695.
Теперь переменную типа необязательно заранее создавать через:
TypeVar()
Например, классический вариант:
from typing import TypeVar
T = TypeVar('T')
def reverse_copy(
values: list[T],
) -> list[T]:
return values[::-1]
В Python 3.12+ можно записать так:
def reverse_copy[T](
values: list[T],
) -> list[T]:
return values[::-1]
Обратите внимание:
def reverse_copy[T]
Переменная типа T объявляется непосредственно после названия функции.
Её можно использовать в аннотациях параметров и результата этой функции.
Импортировать TypeVar в этом случае не требуется.
17. Новый синтаксис с ограничениями
В Python 3.12+ можно указать ограничения непосредственно в квадратных скобках.
Например, верхнюю границу:
from collections.abc import Hashable
def return_key[T: Hashable](
key: T,
) -> T:
return key
Здесь:
T: Hashable
соответствует идее:
T = TypeVar(
'T',
bound=Hashable,
)
А перечисление ограничений можно записать так:
def combine_text[T: (str, bytes)](
first: T,
second: T,
) -> T:
return first + second
Здесь:
T: (str, bytes)
соответствует:
T = TypeVar(
'T',
str,
bytes,
)
Важна разница между:
T: str | bytes
и:
T: (str, bytes)
Первый вариант задаёт верхнюю границу, второй — перечисление допустимых ограничений.
18. Какой синтаксис использовать?
Оба подхода встречаются в современном Python.
Классический:
from typing import TypeVar
T = TypeVar('T')
def reverse_copy(
values: list[T],
) -> list[T]:
return values[::-1]
Новый, Python 3.12+:
def reverse_copy[T](
values: list[T],
) -> list[T]:
return values[::-1]
Новый синтаксис удобен, когда переменная типа нужна только одной функции.
Например, в небольших самостоятельных обобщённых функциях.
Классический синтаксис тоже остаётся актуальным. Он полезен для совместимости со старыми версиями Python, существующими библиотеками и кодом, где переменные типов объявлены отдельно.
При этом повторное использование одной переменной T в нескольких независимых функциях не означает, что все эти функции обязаны работать с одним общим конкретным типом.
Каждая функция самостоятельно устанавливает связь между своими входными и выходными типами.
19. TypeVar не выполняет проверку во время работы
Например:
from typing import TypeVar
T = TypeVar('T')
def reverse_copy(
values: list[T],
) -> list[T]:
return values[::-1]
Аннотация:
list[T]
не заставляет интерпретатор Python проверять тип каждого элемента.
Точно так же:
bound=Hashable
не создаёт автоматическую проверку через isinstance() или hash() при вызове функции.
Ограничения предназначены для статических анализаторов, таких как mypy.
Если нужна настоящая проверка во время выполнения, её следует реализовать отдельно.
20. Когда действительно нужен TypeVar
TypeVar особенно полезен, когда необходимо сохранить связь между типами аргументов и результата.
Например:
from typing import TypeVar
T = TypeVar('T')
def get_last(
values: list[T],
) -> T:
return values[-1]
Если передать:
numbers = [10, 20, 30]
result = get_last(numbers)
анализатор определит:
int
Если передать:
names = ['Alex', 'Emma']
result = get_last(names)
он определит:
str
Обратите внимание: здесь функция возвращает уже не список, а один элемент исходного типа.
Поэтому:
values: list[T]
связано с:
-> T
Именно эта связь делает TypeVar полезным.
Функция предполагает непустой список: при пустом списке обращение к values[-1] вызовет IndexError.
Главное по теме
TypeVar импортируется из:
from typing import TypeVar
Он позволяет создавать переменные типа:
T = TypeVar('T')
И использовать их для связи типов аргументов и результата:
def reverse_copy(
values: list[T],
) -> list[T]:
return values[::-1]
Теперь:
list[int] → list[int]
list[str] → list[str]
list[float] → list[float]
Можно использовать несколько независимых переменных типа:
KT = TypeVar('KT')
VT = TypeVar('VT')
Например:
dict[KT, VT]
Ограничения можно задавать перечислением:
NumberT = TypeVar(
'NumberT',
int,
float,
)
Или через верхнюю границу:
KT = TypeVar(
'KT',
bound=Hashable,
)
Перечисление ограничений позволяет выбрать один из заданных типов.
bound допускает совместимые подтипы и помогает сохранять более точную информацию об исходном типе.
Начиная с Python 3.12 можно объявлять переменные типа непосредственно в функциях:
def reverse_copy[T](
values: list[T],
) -> list[T]:
return values[::-1]
Но классический синтаксис с TypeVar() по-прежнему поддерживается.
Главная идея: TypeVar нужен не просто для обозначения произвольного типа, а прежде всего для сохранения отношений между типами разных частей функции.
Поэтому в функциях, которые принимают и возвращают данные одного типа, он часто гораздо полезнее, чем Any или object.