Аннотации из typing и collections.abc в Python
Обновлено:
Мы уже знакомы с основными аннотациями Python:
int
float
str
list[int]
dict[str, int]
Также мы изучили несколько более универсальных аннотаций:
from typing import Any
from collections.abc import (
Callable,
Iterable,
)
Теперь познакомимся с другими возможностями модулей typing и collections.abc.
Эти модули позволяют описывать не только конкретные типы данных, но и возможности, которыми должен обладать объект.
Например, мы можем указать, что функция ожидает объект, который:
- поддерживает хеширование;
- имеет длину;
- является итерируемым;
- поддерживает индексы;
- допускает изменение элементов;
- хранит пары «ключ — значение».
Это помогает делать функции более универсальными, сохраняя возможность статической проверки типов.
Модуль typing
Аннотация Final
1. Константы и статическая проверка
Импортируем:
from typing import Final
Мы уже знаем, что константы в Python принято записывать заглавными буквами:
MAX_ATTEMPTS = 5
Но Python не запрещает изменить такую переменную:
MAX_ATTEMPTS = 10
Даже если мы укажем:
MAX_ATTEMPTS: int = 5
mypy разрешит заменить одно целое число другим.
Почему?
Потому что аннотация int определяет тип значения, но не запрещает последующие присваивания.
2. Запрещаем переприсваивание через Final
from typing import Final
MAX_ATTEMPTS: Final[int] = 5
Теперь мы явно сообщаем анализатору типов:
Это имя должно получить значение один раз и не должно переприсваиваться.
Например:
MAX_ATTEMPTS = 10
mypy обнаружит ошибку, даже несмотря на то, что новое значение тоже является целым числом.
Можно указать только Final:
from typing import Final
MAX_ATTEMPTS: Final = 5
APP_NAME: Final = 'Python Course'
Или явно указать тип:
MAX_ATTEMPTS: Final[int] = 5
APP_NAME: Final[str] = 'Python Course'
Оба способа допустимы.
Важный нюанс
Final не делает объект физически неизменяемым и не запрещает присваивание во время выполнения Python.
Например:
from typing import Final
NUMBERS: Final[list[int]] = [10, 20]
NUMBERS.append(30)
Статическая проверка разрешит изменение содержимого списка.
Но запретит переприсвоить имя:
NUMBERS = [100, 200]
Таким образом, Final защищает от переприсваивания имени на уровне статической проверки, а не от любого изменения объекта.
Аннотация Literal
3. Ограничение конкретными значениями
Импортируем:
from typing import Literal
Иногда нам нужно указать не просто тип данных, а конкретные допустимые значения.
Например, функция принимает только три цвета:
red
green
blue
Для этого используется Literal.
from typing import Literal
def describe_color(
color: Literal['red', 'green', 'blue'],
) -> str:
return f'Selected color: {color}'
Теперь:
print(describe_color('red'))
# Selected color: red
print(describe_color('green'))
# Selected color: green
соответствуют аннотации.
А:
describe_color('yellow')
не соответствует ей.
mypy обнаружит, что значение 'yellow' не входит в перечень разрешённых.
При этом сам Python не запрещает такой вызов во время выполнения: ограничения Literal предназначены прежде всего для статической проверки.
4. Literal в возвращаемом значении
Literal можно использовать не только для параметров, но и для результата функции.
Например:
from typing import Literal
def get_status(
is_active: bool,
) -> Literal['active', 'inactive']:
if is_active:
return 'active'
return 'inactive'
Теперь анализатор знает, что функция возвращает не произвольную строку, а одно из двух конкретных значений:
active
inactive
Если случайно написать:
return 'unknown'
это не будет соответствовать объявленному Literal.
5. Объединение нескольких Literal
Допустим, у нас есть несколько групп допустимых режимов работы.
from typing import Literal
ReadMode = Literal[
'read',
'read_binary',
]
WriteMode = Literal[
'write',
'write_binary',
]
AppendMode = Literal[
'append',
'append_binary',
]
Можно создать общую аннотацию:
FileMode = Literal[
ReadMode,
WriteMode,
AppendMode,
]
Теперь FileMode объединяет все допустимые значения из трёх групп.
Например:
def describe_mode(
mode: FileMode,
) -> str:
return f'Режим: {mode}'
Используем:
print(describe_mode('read'))
# Режим: read
А значение:
describe_mode('delete')
будет отклонено статическим анализатором.
Такой подход удобен, когда допустимых значений достаточно много и их хочется разделить на смысловые группы.
Мы также создали здесь псевдонимы типов. Их отдельные современные способы объявления изучим позже.
Аннотация NoReturn
6. Функции, которые никогда не возвращаются
Импортируем:
from typing import NoReturn
Обычно мы аннотируем результат функции конкретным типом:
def get_number() -> int:
return 100
Или:
def show_message() -> None:
print('Hello')
Но существуют функции, которые вообще никогда не завершаются обычным возвратом управления вызывающему коду.
Например, функция может:
- всегда возбуждать исключение;
- завершать программу;
- выполнять бесконечный цикл.
Для таких случаев существует NoReturn.
7. Функция, которая возбуждает исключение
from typing import NoReturn
def stop_with_error(
message: str,
) -> NoReturn:
raise RuntimeError(message)
Здесь используется ключевое слово:
raise
Оно позволяет возбуждать исключения. Подробно рассмотрим его в следующих темах.
Функция:
stop_with_error('Не удалось продолжить работу')
не возвращает обычный результат.
Она прерывает нормальное выполнение возбуждением исключения.
Поэтому аннотация:
-> NoReturn
соответствует её назначению.
Отличие от None
-> None
означает, что функция нормально завершается, но не возвращает полезного значения.
А:
-> NoReturn
означает, что функция вообще не возвращает управление обычным способом.
Например, она всегда возбуждает исключение или завершает программу.
Для подобных случаев в современном typing также существует Never. Пока достаточно знать NoReturn.
Аннотации Optional и Union
8. Optional
Импортируем:
from typing import Optional
Раньше для аннотации значения, которое могло быть определённого типа или None, часто использовали:
Optional[str]
Например:
from typing import Optional
def get_username(
user_id: int,
) -> Optional[str]:
if user_id == 1:
return 'Alex'
return None
Начиная с Python 3.10, такую аннотацию удобнее записывать через |:
def get_username(
user_id: int,
) -> str | None:
if user_id == 1:
return 'Alex'
return None
Это два равнозначных способа описать один тип.
Проверим:
from typing import Optional
print(
Optional[str] == (str | None)
)
# True
В современном коде обычно будем использовать:
str | None
9. Optional не означает просто необязательный параметр
Это важный момент.
Например:
def calculate_price(
price: int,
discount: int = 0,
) -> int:
return price - discount
Параметр discount необязательный, потому что имеет значение по умолчанию.
Но его тип:
int
Он не обязан принимать None.
Поэтому писать:
discount: int | None = 0
здесь нет необходимости.
А вот:
def greet(
name: str | None = None,
) -> str:
if name is None:
return 'Hello, guest'
return f'Hello, {name}'
действительно позволяет передать либо строку, либо None.
Важно: если мы пишем:
name: str = None
то такая аннотация не соответствует значению по умолчанию.
Нужно явно разрешить None:
name: str | None = None
10. Union
Импортируем:
from typing import Union
Union позволяет указать несколько допустимых типов данных.
Например, раньше часто писали:
Union[int, float]
Теперь можно использовать:
int | float
Проверим:
from typing import Union
print(
Union[int, str] == (int | str)
)
# True
Обе аннотации описывают один и тот же набор допустимых типов.
Пример функции:
def double_number(
number: int | float,
) -> int | float:
return number * 2
Она может принимать целые и вещественные числа.
print(double_number(10))
# 20
print(double_number(2.5))
# 5.0
В современном Python обычно используем |, поскольку такая запись короче и лучше читается.
11. Псевдонимы объединённых типов
Иногда одно и то же объединение типов используется много раз.
Например:
Number = int | float
Теперь можно написать:
def double_number(
number: Number,
) -> Number:
return number * 2
Такую конструкцию можно использовать как простой псевдоним типа.
Но в современном Python существуют и специальные способы объявления псевдонимов типов.
К ним мы вернёмся позже.
Модуль collections.abc
Теперь рассмотрим несколько аннотаций, описывающих возможности объектов и коллекций.
Почти все эти объекты можно использовать не только в аннотациях, но и для проверки через:
isinstance()
Аннотация Hashable
12. Хешируемые объекты
Импортируем:
from collections.abc import Hashable
Hashable означает, что объект поддерживает хеширование.
То есть для него предусмотрена работа с:
hash()
Например:
from collections.abc import Hashable
def get_object_hash(
value: Hashable,
) -> int:
return hash(value)
Передать можно:
print(get_object_hash(100))
print(get_object_hash('Python'))
print(get_object_hash((10, 20)))
Но обычный список не является хешируемым:
get_object_hash([10, 20])
Такой вызов не соответствует аннотации и при выполнении приведёт к TypeError.
Проверка через isinstance()
from collections.abc import Hashable
print(isinstance(100, Hashable))
# True
print(isinstance('Python', Hashable))
# True
print(isinstance((10, 20), Hashable))
# True
print(isinstance([10, 20], Hashable))
# False
Аннотация Sized
13. Объекты, имеющие длину
Импортируем:
from collections.abc import Sized
Sized описывает объекты, для которых работает:
len()
Например:
from collections.abc import Sized
def get_length(
value: Sized,
) -> int:
return len(value)
Можно передать:
print(get_length('Python'))
# 6
print(get_length([10, 20, 30]))
# 3
print(get_length({'a': 1, 'b': 2}))
# 2
Функции всё равно, какой именно тип данных поступил.
Главное — чтобы объект поддерживал получение длины.
Проверка через isinstance()
from collections.abc import Sized
print(isinstance([10, 20], Sized))
# True
print(isinstance('Python', Sized))
# True
print(isinstance(100, Sized))
# False
Аннотация Collection
14. Коллекция с несколькими возможностями
Импортируем:
from collections.abc import Collection
Аннотация Collection описывает объект, который поддерживает сразу три возможности:
- Итерацию — его можно обходить.
- Получение длины через
len(). - Проверку принадлежности через
in.
То есть можно представить:
Collection
↓
Iterable
Sized
Container
Container — это интерфейс проверки принадлежности через in.
Подробно его отдельно разбирать пока не будем.
15. Пример с Collection
from collections.abc import Collection
def contains_word(
words: Collection[str],
target: str,
) -> bool:
return target in words
Теперь можно передать список строк:
print(
contains_word(
['Python', 'SQL', 'Django'],
'SQL',
)
)
# True
Или множество:
print(
contains_word(
{'Python', 'SQL', 'Django'},
'Java',
)
)
# False
В обоих случаях функция работает с коллекцией строк.
Какие объекты относятся к Collection
Из знакомых нам:
list
tuple
str
range
dict
set
frozenset
Все они поддерживают перечисленные возможности.
16. Iterable не всегда является Collection
Мы уже знаем:
from collections.abc import Iterable
Iterable гарантирует возможность итерации.
Но это не означает, что объект обязательно поддерживает len() или отдельный интерфейс проверки принадлежности.
Например, существуют итераторы и генераторы.
С ними мы познакомимся в следующей теме.
Пока просто посмотрим на два примера:
from collections.abc import (
Collection,
Iterable,
)
iterator = iter([10, 20, 30])
print(isinstance(iterator, Iterable))
# True
print(isinstance(iterator, Collection))
# False
И генераторное выражение:
generator = (
number
for number in range(3)
)
print(isinstance(generator, Iterable))
# True
print(isinstance(generator, Collection))
# False
Оба объекта можно обходить, но они не являются Collection.
Важно: оператор in в Python может работать даже с объектом без отдельного метода проверки принадлежности — через последовательную итерацию. Поэтому для Collection важно именно наличие всех трёх предусмотренных интерфейсом возможностей.
Аннотация Reversible
17. Объекты, поддерживающие обратный обход
Импортируем:
from collections.abc import Reversible
Reversible описывает итерируемый объект, поддерживающий обратный обход.
Для этого в Python существует встроенная функция:
reversed()
Подробно её разберём в следующей теме.
Пока посмотрим на пример:
from collections.abc import Reversible
def reverse_items(
items: Reversible[str],
) -> list[str]:
return list(reversed(items))
Используем:
print(
reverse_items(
['Python', 'SQL', 'Django']
)
)
# ['Django', 'SQL', 'Python']
Какие объекты подходят
Из знакомых нам:
list
tuple
str
range
dict
При этом dict поддерживает обратную итерацию начиная с Python 3.8. В обратном порядке выдаются его ключи.
А обычный:
set
не поддерживает обратный обход, поскольку не имеет определённого порядка элементов.
Обычные генераторы и итераторы также не обязаны поддерживать reversed().
Аннотация Sequence
18. Упорядоченные последовательности
Импортируем:
from collections.abc import Sequence
Sequence означает последовательность.
Это более конкретный интерфейс, чем Collection.
Объекты Sequence поддерживают:
- итерацию;
len();in;- обращение по индексам;
- срезы для стандартных последовательностей;
- обратный обход;
- методы
count()иindex().
В частности, при работе с последовательностью мы можем использовать:
items[0]
len(items)
items.count(value)
items.index(value)
19. Пример с Sequence
from collections.abc import Sequence
def get_first(
items: Sequence[str],
) -> str:
return items[0]
Можно передать список:
print(
get_first(
['Python', 'SQL']
)
)
# Python
Или кортеж:
print(
get_first(
('Django', 'Flask')
)
)
# Django
Оба объекта поддерживают индексацию.
При этом функция предполагает, что последовательность непустая. Если передать пустую коллекцию, обращение к индексу 0 приведёт к IndexError.
20. Какие объекты являются Sequence
На данном этапе:
list
tuple
str
range
Позже мы познакомимся с:
deque
который тоже соответствует интерфейсу Sequence.
Например:
from collections.abc import Sequence
print(isinstance([10, 20], Sequence))
# True
print(isinstance((10, 20), Sequence))
# True
print(isinstance('Python', Sequence))
# True
print(isinstance(range(10), Sequence))
# True
print(isinstance({10, 20}, Sequence))
# False
Словари и множества не являются последовательностями.
Например, у set нет обычных числовых индексов, а dict использует ключи вместо последовательных индексов.
Аннотация SupportsIndex
21. Объекты, подходящие для индексирования
Импортируем:
from typing import SupportsIndex
SupportsIndex описывает объект, который можно использовать в операциях, требующих целочисленный индекс.
Например, обычный int поддерживает этот интерфейс.
from typing import SupportsIndex
print(isinstance(10, SupportsIndex))
# True
print(isinstance(3.5, SupportsIndex))
# False
22. Пример использования SupportsIndex
from collections.abc import Sequence
from typing import SupportsIndex
def get_item(
items: Sequence[str],
index: SupportsIndex,
) -> str:
return items[index]
Используем:
languages = [
'Python',
'Java',
'Go',
]
print(get_item(languages, 1))
# Java
Здесь параметр:
index: SupportsIndex
показывает, что функция ожидает объект, подходящий для индексирования.
Если мы напишем:
index: int
это тоже будет корректным вариантом для обычных целочисленных индексов.
Но SupportsIndex точнее описывает необходимую возможность и допускает некоторые другие объекты, реализующие соответствующий интерфейс.
Аннотация MutableSequence
23. Изменяемые последовательности
Импортируем:
from collections.abc import MutableSequence
Аннотация MutableSequence описывает изменяемую последовательность.
Она обладает возможностями Sequence, но дополнительно поддерживает изменение содержимого:
- замену элементов;
- добавление элементов;
- удаление элементов;
- изменение длины последовательности.
Например:
from collections.abc import MutableSequence
def replace_first(
items: MutableSequence[str],
new_value: str,
) -> None:
if items:
items[0] = new_value
Используем:
languages = [
'Python',
'Java',
'Go',
]
replace_first(
languages,
'JavaScript',
)
print(languages)
Результат:
['JavaScript', 'Java', 'Go']
Функция изменяет исходную коллекцию.
24. Sequence и MutableSequence
Если функция только читает элементы:
def get_first(
items: Sequence[str],
) -> str:
return items[0]
удобно использовать Sequence.
Если же функция собирается изменять последовательность:
def replace_first(
items: MutableSequence[str],
new_value: str,
) -> None:
if items:
items[0] = new_value
лучше использовать MutableSequence.
Из знакомых нам объектов:
list
соответствует MutableSequence.
А:
tuple
str
range
не соответствуют, поскольку не позволяют изменять элементы.
Позже мы познакомимся с:
deque
который также поддерживает этот интерфейс.
Проверка через isinstance()
from collections.abc import MutableSequence
print(isinstance([10, 20], MutableSequence))
# True
print(isinstance((10, 20), MutableSequence))
# False
print(isinstance('Python', MutableSequence))
# False
Аннотация Mapping
25. Словареподобные объекты
Импортируем:
from collections.abc import Mapping
Mapping описывает объекты, которые предоставляют интерфейс:
ключ → значение
Самый знакомый нам пример:
dict
Но существуют и другие словареподобные структуры данных.
Например:
defaultdict
Counter
MappingProxyType
Их изучим позже.
Важно: Mapping описывает именно интерфейс работы с ключами и значениями, а не конкретный способ хранения данных. Такой объект не обязательно должен быть построен на хеш-таблице.
26. Пример с Mapping
from collections.abc import Mapping
def get_age(
user: Mapping[str, int],
) -> int | None:
return user.get('age')
Используем:
user = {
'age': 30,
'score': 100,
}
print(get_age(user))
# 30
Здесь:
Mapping[str, int]
означает:
ключи → str
значения → int
Функции не важно, является объект именно dict или другим подходящим отображением.
Главное, чтобы он поддерживал необходимый интерфейс.
Mapping и dict
Аннотация:
dict[str, int]
означает, что мы ожидаем именно словарь.
А:
Mapping[str, int]
позволяет передавать разные объекты с подходящим интерфейсом ключей и значений.
Поэтому для функций, которые только читают данные, Mapping часто оказывается более универсальным выбором.
Если нужно изменять пары словаря, существует отдельный интерфейс MutableMapping, который разберём позднее.
Сравнение интерфейсов коллекций
27. От общего к более конкретному
Мы познакомились с несколькими аннотациями, описывающими разные возможности объектов.
Упрощённо их можно представить так:
Iterable
↓
Можно обходить объект
Sized
↓
Можно получить длину
Collection
↓
Итерация + длина + принадлежность
Sequence
↓
Упорядоченная последовательность
с индексами, count(), index()
и обратным обходом
MutableSequence
↓
Последовательность,
которую можно изменять
Reversible описывает возможность обратного обхода, а Sequence объединяет её с другими возможностями последовательности.
Mapping — отдельная разновидность коллекции с интерфейсом «ключ — значение».
Hashable и SupportsIndex описывают самостоятельные возможности объектов.
28. Проверка разных типов коллекций
Посмотрим на небольшой пример:
from collections.abc import (
Collection,
Iterable,
Mapping,
MutableSequence,
Reversible,
Sequence,
Sized,
)
values = [10, 20, 30]
print(isinstance(values, Iterable))
# True
print(isinstance(values, Sized))
# True
print(isinstance(values, Collection))
# True
print(isinstance(values, Reversible))
# True
print(isinstance(values, Sequence))
# True
print(isinstance(values, MutableSequence))
# True
print(isinstance(values, Mapping))
# False
Обычный список поддерживает практически все перечисленные возможности последовательностей.
Но он не является отображением ключей на значения.
29. Краткая таблица аннотаций из typing
| Аннотация | Назначение |
|---|---|
Any |
Значение произвольного типа без обычных ограничений статической проверки |
Final |
Запрет переприсваивания имени для статического анализатора |
Literal |
Ограничение конкретными допустимыми значениями |
NoReturn |
Функция никогда не возвращает управление обычным способом |
Optional[T] |
T \| None |
Union[T1, T2] |
T1 \| T2 |
SupportsIndex |
Объект поддерживает получение целочисленного индекса |
Все перечисленные объекты импортируются из:
typing
30. Краткая таблица аннотаций из collections.abc
| Аннотация | Назначение |
|---|---|
Hashable |
Поддерживает хеширование |
Sized |
Поддерживает len() |
Iterable |
Поддерживает итерацию |
Callable |
Является вызываемым объектом |
Collection |
Поддерживает итерацию, длину и принадлежность |
Reversible |
Поддерживает обратный обход |
Sequence |
Последовательность с индексами и дополнительными методами |
MutableSequence |
Изменяемая последовательность |
Mapping |
Отображение ключей на значения |
Импортируем их из:
collections.abc
Например:
from collections.abc import (
Callable,
Collection,
Hashable,
Iterable,
Mapping,
MutableSequence,
Reversible,
Sequence,
Sized,
)
Главное по теме
Модуль:
typing
содержит специальные конструкции для описания типов, допустимых значений и ограничений статической проверки.
Например:
Final[int]
Literal['red', 'green']
str | None
Модуль:
collections.abc
содержит абстрактные интерфейсы, которые позволяют описывать возможности объектов, не привязываясь к одному конкретному классу.
Например:
Iterable[int]
означает, что объект можно обходить.
Sized
означает, что у объекта можно получить длину.
Sequence[str]
означает, что мы ожидаем последовательность строк с поддержкой индексации.
MutableSequence[str]
означает, что эту последовательность можно изменять.
Mapping[str, int]
означает, что объект предоставляет словареподобный интерфейс.
Главная задача этих аннотаций — описывать именно те возможности, которые действительно нужны функции.
Например, если функция только обходит элементы, нет необходимости требовать именно list.
Достаточно:
Iterable
Если она должна обращаться к элементам по индексам — используем более конкретный интерфейс.
Если должна изменять последовательность — используем MutableSequence.
Так функции становятся универсальнее, а статический анализатор получает достаточно информации для проверки.
Что будем изучать дальше
В ближайших темах познакомимся с:
- итераторами;
- генераторами;
- встроенной функцией
reversed(); - другими возможностями работы с итерируемыми объектами.
Для них существуют дополнительные аннотации, например Iterator и Generator.
Позже также разберём:
IO
TextIO
BinaryIO
и другие возможности аннотирования, связанные с файлами, пользовательскими классами и более сложными интерфейсами.