Аннотации из 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 описывает объект, который поддерживает сразу три возможности:

  1. Итерацию — его можно обходить.
  2. Получение длины через len().
  3. Проверку принадлежности через 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

и другие возможности аннотирования, связанные с файлами, пользовательскими классами и более сложными интерфейсами.


Документация