Аннотации типов в Python и проверка с mypy

Обновлено:

В Python существует механизм аннотаций типов (type hints).

Аннотации позволяют указывать, какие типы данных мы ожидаем получить в переменных, параметрах функций и возвращаемых значениях.

Например:

name: str = 'Alex'
age: int = 30
price: float = 19.99

Здесь мы не просто создали переменные, но и указали предполагаемые типы объектов, с которыми они будут работать.

Аннотации особенно полезны при разработке больших программ, когда разные функции взаимодействуют друг с другом и важно понимать, какие данные они принимают и возвращают.


1. Аннотации переменных

Обычное создание переменной:

message = 'Hello'

С аннотацией:

message: str = 'Hello'

После имени переменной ставится двоеточие:

:

Затем указывается предполагаемый тип:

str

И далее обычное присваивание:

=

Общая конструкция:

variable: type = value

Другие примеры:

number: int = 100

temperature: float = 23.5

is_active: bool = True

Синтаксис аннотирования переменных через двоеточие появился в Python 3.6, в рамках PEP 526.

Стандарт аннотаций типов PEP 484 появился в Python 3.5, а синтаксис аннотаций параметров и возвращаемых значений функций существовал ещё раньше.


2. Можно указать тип без значения

Например:

username: str

Мы сообщили, что переменная username предназначена для строки.

Но никакое значение пока не присвоили.

Позже можно написать:

username = 'Alex'

Важно: одна аннотация сама по себе не создаёт объект со значением.

Если попытаться прочитать переменную до присваивания:

username: str

print(username)

получим NameError.


3. Аннотации не изменяют динамическую типизацию Python

Рассмотрим:

message: str = 'Hello'

message = 100

print(message)

Обычный Python выполнит этот код и выведет:

100

Почему?

Потому что аннотации не запрещают присваивание объектов другого типа во время выполнения программы.

Python по-прежнему остаётся языком с динамической типизацией.

Но с помощью специальных инструментов мы можем проверить, соответствует ли код указанным аннотациям.

Один из таких инструментов — mypy.


4. Установка mypy

mypy — это инструмент статической проверки типов Python.

Он анализирует код и пытается найти несоответствия между аннотациями и фактическими операциями.

Установить его можно через терминал:

pip install mypy

Также можно использовать:

python -m pip install mypy

На системах, где интерпретатор запускается через python3:

python3 -m pip install mypy

Команда с python -m pip позволяет явно использовать pip соответствующего интерпретатора Python.

Для простых учебных примеров достаточно установить mypy в ту среду Python, с которой мы работаем. Некоторые операционные системы ограничивают установку пакетов непосредственно в системный Python — в таком случае используется виртуальное окружение, которое мы разберём отдельно.


5. Проверяем файл через mypy

Создадим файл:

main.py

С кодом:

message: str = 'Hello'

message = 'Python'

print(message)

Откроем терминал в папке с файлом и напишем:

mypy main.py

Если проверка прошла успешно, увидим сообщение примерно следующего вида:

Success: no issues found in 1 source file

Теперь изменим код:

message: str = 'Hello'

message = 100

Снова выполним:

mypy main.py

Теперь mypy сообщит об ошибке несовместимости типов:

Incompatible types in assignment

Потому что мы указали:

message: str

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

100

который относится к классу int.

Проверка файла по пути

Если файл находится не в текущей папке, можно указать относительный путь:

mypy lessons/main.py

Или абсолютный путь.

Также можно запускать:

python -m mypy main.py

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


6. Статическая проверка не запускает программу

Важное преимущество mypy заключается в том, что он может находить ошибки типов без выполнения самой программы.

Например:

value: int = 'Python'

Мы можем даже не запускать этот файл.

mypy уже способен определить, что тип значения не соответствует аннотации.

Но важно понимать: mypy проверяет совместимость типов и некоторые связанные с ними ошибки. Он не гарантирует логическую правильность алгоритма и не заменяет обычное тестирование программы.


Несколько допустимых типов

7. Оператор |

Иногда переменная может содержать значения разных типов.

Например:

value: str | int = 'Hello'

Здесь:

str | int

означает:

Значение может быть либо str, либо int.

Поэтому можно написать:

value: str | int = 'Hello'

value = 100

value = 'Python'

Такие присваивания соответствуют указанной аннотации.

Но:

value = 3.14

уже не соответствует ей, потому что float не входит в перечень разрешённых типов.


8. Больше двух типов

Можно указать сразу несколько:

value: str | int | float = 100

Теперь предполагается, что переменная может содержать:

str
int
float

Такой синтаксис называется объединением типов — union type.

Оператор | для объединения типов появился в Python 3.10, в рамках PEP 604.

Раньше для этого использовался typing.Union. В современном коде обычно удобнее записывать типы непосредственно через |.


9. Аннотация None

Обычно для аннотации используется название класса:

int
float
str
list

Но для отсутствующего значения часто используется непосредственно:

None

Например:

result: None = None

Мы знаем, что сам объект None относится к классу NoneType.

Но для обычных аннотаций принято использовать именно:

None

Особенно часто None применяется вместе с другим типом:

user_id: int | None = None

Теперь значение может быть:

100

или:

None

Например:

user_id: int | None = None

user_id = 150

Это удобный способ показать, что значение может отсутствовать.


Аннотации списков

10. Просто list

Самый простой вариант:

numbers: list = [10, 20, 30]

Здесь мы сообщили, что переменная содержит список.

Но не указали, какие именно объекты должны находиться внутри него.

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


11. list[int]

Например:

numbers: list[int] = [
    10,
    20,
    30,
]

Аннотация:

list[int]

означает:

Список, элементы которого должны быть целыми числами.

Количество элементов при этом не ограничено.

Можно передать:

numbers: list[int] = []

или:

numbers: list[int] = [1, 2, 3, 4, 5]

Но такой код:

numbers: list[int] = [
    10,
    20,
    'Python',
]

не соответствует аннотации, поскольку среди элементов находится строка.

mypy сможет обнаружить это несоответствие.

Синтаксис параметризации встроенных коллекций, например list[int] и dict[str, int], стал доступен в обычном виде начиная с Python 3.9 благодаря PEP 585.


12. Список строк

names: list[str] = [
    'Alex',
    'Emma',
    'Daniel',
]

Теперь мы явно указали:

list[str]

То есть каждый элемент списка предполагается строкой.


13. Несколько типов внутри списка

Можно использовать объединение типов:

numbers: list[int | float] = [
    10,
    20.5,
    30,
    40.75,
]

Здесь каждый элемент может быть:

int

или:

float

Допустимо также указать больше типов:

values: list[str | int | float] = [
    'Python',
    100,
    3.14,
]

Вложенные списки

14. list[list[int]]

Предположим, у нас есть список, внутри которого находятся другие списки:

matrix = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]

Его можно аннотировать так:

matrix: list[list[int]] = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9],
]

Читаем изнутри наружу:

int
↓
list[int]
↓
list[list[int]]

То есть:

  1. внутренние элементы — целые числа;
  2. внутренние коллекции — списки целых чисел;
  3. внешний объект — список таких списков.

Аннотации кортежей

15. tuple отличается от list

Список можно аннотировать так:

numbers: list[int] = [
    10,
    20,
    30,
]

Количество элементов произвольное.

Но у tuple используется немного другой принцип.

Он позволяет описать тип каждого элемента на конкретной позиции.


16. Кортеж из одного элемента

numbers: tuple[int] = (
    10,
)

Аннотация:

tuple[int]

означает:

Кортеж, содержащий ровно один элемент типа int.

Например:

numbers: tuple[int] = (
    10,
    20,
)

уже не соответствует такой аннотации.

Потому что в кортеже два элемента, а мы указали один.


17. Кортеж из двух элементов

coordinates: tuple[int, int] = (
    10,
    20,
)

Здесь мы ожидаем два элемента:

первый  → int
второй  → int

Можно указывать разные типы:

user: tuple[str, int, bool] = (
    'Alex',
    30,
    True,
)

Теперь структура строго определена:

первый  → str
второй  → int
третий  → bool

Это удобно для фиксированных наборов данных.


18. Кортеж с произвольным количеством элементов

Если мы хотим разрешить любое количество целых чисел, используется:

tuple[int, ...]

Например:

numbers: tuple[int, ...] = (
    10,
    20,
    30,
    40,
    50,
)

Три точки:

...

означают, что количество элементов не фиксировано.

Допустимы:

numbers: tuple[int, ...] = ()
numbers: tuple[int, ...] = (10,)
numbers: tuple[int, ...] = (10, 20, 30)

То есть элементов может быть от нуля и больше.


19. Несколько типов при произвольной длине

values: tuple[int | str, ...] = (
    10,
    'Python',
    20,
    'SQL',
)

Каждый элемент может быть:

int

или:

str

При этом количество элементов не ограничено.


20. Сравнение аннотаций list и tuple

Аннотация Значение
list[int] Список целых чисел произвольной длины
tuple[int] Кортеж ровно из одного целого числа
tuple[int, int] Кортеж ровно из двух целых чисел
tuple[str, int] Кортеж из строки и целого числа
tuple[int, ...] Кортеж из любого количества целых чисел
tuple[int \| str, ...] Кортеж произвольной длины из строк и целых чисел

Это одно из главных отличий аннотаций списков и кортежей.


Аннотации словарей

21. Просто dict

Можно написать:

user: dict = {
    'name': 'Alex',
    'age': 30,
}

Мы указали, что объект является словарём, но ничего не сообщили о типах ключей и значений.

Для точного описания используется:

dict[key_type, value_type]

22. Ключи и значения

Например:

scores: dict[str, int] = {
    'Alex': 100,
    'Emma': 85,
    'Daniel': 90,
}

Аннотация:

dict[str, int]

означает:

ключ     → str
значение → int

Другой пример:

translations: dict[str, str] = {
    'cat': 'кот',
    'dog': 'собака',
    'house': 'дом',
}

Здесь и ключи, и значения являются строками.


23. Несколько типов ключей и значений

data: dict[str | int, str | float] = {
    'name': 'Alex',
    'price': 100.5,
    10: 'ten',
}

Ключ может быть:

str
int

Значение может быть:

str
float

24. Словарь со списками

Например:

phone_book: dict[str, list[str]] = {
    'Alex Brown': [
        '+995111111111',
        '+995222222222',
    ],
    'Emma Wilson': [
        '+995333333333',
    ],
}

Читаем аннотацию:

dict[str, list[str]]

Так:

dict
↓
ключ → str
↓
значение → list[str]

То есть ключом является строка, а значением — список строк.


25. Более сложная вложенность

data: dict[
    str | int,
    str | list[float],
] = {
    'name': 'Alex',
    'prices': [10.5, 20.75],
    100: 'product',
}

Здесь допустимы:

Ключи:

str | int

Значения:

str | list[float]

Аннотации могут быть достаточно глубоко вложенными.

Например:

dict[str, dict[str, list[int]]]

означает словарь, в котором:

  • внешние ключи — строки;
  • значения — другие словари;
  • внутренние ключи — строки;
  • внутренние значения — списки целых чисел.

Такая запись позволяет точно описывать сложные структуры данных.


Аннотации множеств

26. set

Множество аннотируется аналогично списку.

Например:

numbers: set[int] = {
    10,
    20,
    30,
}

Или:

technologies: set[str] = {
    'Python',
    'SQL',
    'Django',
}

Можно использовать объединение типов:

values: set[int | str] = {
    10,
    'Python',
    20,
    'SQL',
}

27. frozenset

Неизменяемые множества аннотируются похожим образом:

numbers: frozenset[int] = frozenset(
    (10, 20, 30)
)

Или:

languages: frozenset[str] = frozenset(
    ('Python', 'Java', 'Go')
)

Как и с обычным set, внутри квадратных скобок указывается предполагаемый тип элементов.


Другие коллекции

28. Аннотация deque

Мы ещё будем изучать класс:

deque

Он находится в модуле:

collections

И представляет двустороннюю очередь — коллекцию, удобную для добавления и удаления элементов с обоих концов.

Аннотация похожа на аннотацию списка:

from collections import deque


numbers: deque[int] = deque(
    [10, 20, 30]
)

Или:

from collections import deque


names: deque[str] = deque(
    ['Alex', 'Emma']
)

Для многих стандартных коллекций используется тот же принцип:

НазваниеТипа[ТипЭлемента]

Но количество и смысл параметров зависят от конкретной коллекции.

Например, у dict указываются два типа — для ключей и значений.

А у Counter, который мы изучим позже, в записи Counter[str] указывается тип подсчитываемых элементов, а сами количества являются целыми числами.


Аннотации констант

29. Константы аннотируются как обычные переменные

Например:

MAX_ATTEMPTS: int = 5

APP_NAME: str = 'Python Learning'

TAX_RATE: float = 0.15

Синтаксис совершенно обычный:

NAME: type = value

Аннотация сама по себе не делает переменную неизменяемой.

То есть Python всё равно разрешит:

MAX_ATTEMPTS = 10

Существуют дополнительные возможности аннотирования констант, например Final, но их рассмотрим позже.


Аннотации функций

30. Самое важное применение

На практике аннотации особенно полезны при определении функций и методов.

В первую очередь мы хотим описать:

  1. какие аргументы принимает функция;
  2. какие типы значений ожидаются;
  3. какой тип результата функция возвращает.

Например, обычная функция:

def add_numbers(first, second):
    return first + second

Нам заранее неизвестно, для каких типов данных она предназначена.

Технически мы можем передать:

add_numbers(10, 20)

или:

add_numbers('Hello', 'Python')

Оба вызова могут выполниться, хотя их смысл совершенно разный.


31. Аннотируем параметры

Напишем:

def add_numbers(
    first: int,
    second: int,
):
    return first + second

Теперь мы явно указали:

first  → int
second → int

То есть функция предназначена для сложения целых чисел.

Аннотация параметра записывается так:

parameter: type

32. Аннотация возвращаемого значения

Чтобы показать, какой тип функция возвращает, используется стрелка:

->

Например:

def add_numbers(
    first: int,
    second: int,
) -> int:
    return first + second

Аннотация:

-> int

означает:

Функция должна возвращать целое число.

Теперь сигнатура функции описывает весь её основной интерфейс:

принимает int и int
↓
возвращает int

33. Необязательные параметры

Аннотация совместима со значениями по умолчанию:

def add_numbers(
    first: int,
    second: int = 10,
) -> int:
    return first + second

Здесь:

second: int = 10

означает:

  • параметр имеет тип int;
  • он необязательный;
  • его значение по умолчанию равно 10.

Можно вызвать:

print(add_numbers(5))
# 15

Или:

print(add_numbers(5, 20))
# 25

34. Проверка аргументов функции

Рассмотрим:

def add_numbers(
    first: int,
    second: int,
) -> int:
    return first + second

Правильный вызов:

result = add_numbers(
    10,
    20,
)

Но если написать:

result = add_numbers(
    '10',
    '20',
)

обычный Python выполнит конкатенацию строк и вернёт:

1020

Однако mypy обнаружит, что мы передали строки туда, где ожидались целые числа.

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

Аннотации помогают обнаружить подобную ошибку ещё до запуска.


35. Проверка возвращаемого значения

Создадим функцию:

def calculate_average(
    first: int,
    second: int,
) -> int:
    return (first + second) / 2

Здесь мы указали:

-> int

Но выражение:

(first + second) / 2

использует обычное деление:

/

Результат которого в данном случае относится к классу:

float

Поэтому mypy обнаружит несоответствие возвращаемого значения.

Корректная аннотация:

def calculate_average(
    first: int,
    second: int,
) -> float:
    return (first + second) / 2

Теперь сигнатура соответствует фактическому результату.


36. Аннотация None при отсутствии результата

Некоторые функции ничего явно не возвращают.

Например:

def show_message(
    message: str,
) -> None:
    print(message)

Аннотация:

-> None

показывает, что функция не предназначена для возвращения полезного значения.

Она выполняет действие — в данном случае выводит сообщение на экран.


37. Функция может возвращать разные типы

Например:

def find_first_positive(
    numbers: list[int],
) -> int | None:
    for number in numbers:
        if number > 0:
            return number

    return None

Функция принимает:

list[int]

и возвращает:

int | None

Почему?

Если положительное число найдено:

return number

возвращается int.

Если нет:

return None

возвращается None.

Пример:

print(
    find_first_positive(
        [-10, -5, 20, 30]
    )
)
# 20

А:

print(
    find_first_positive(
        [-10, -5, -2]
    )
)
# None

Такая аннотация сразу сообщает разработчику, что функция может не найти нужное значение.


38. Аннотация содержимого списка помогает внутри функции

Предположим, функция получает список строк:

def normalize_names(
    names: list[str],
) -> list[str]:
    result = []

    for name in names:
        result.append(
            name.strip().title()
        )

    return result

Здесь мы указали:

names: list[str]

Поэтому анализатор типов понимает, что:

names

— список строк.

Следовательно, переменная:

name

при обычном обходе этого списка предполагается строкой.

А значит, редактор может предлагать подходящие строковые методы:

strip()
title()
upper()
lower()
replace()

Это значительно облегчает работу с кодом.


Зачем нужны аннотации

39. Читаемость кода

Сравним:

def process_data(data, limit):
    ...

По одной сигнатуре непонятно:

  • что такое data;
  • что такое limit;
  • что должна возвращать функция.

А теперь:

def get_short_words(
    words: list[str],
    max_length: int,
) -> list[str]:
    return [
        word
        for word in words
        if len(word) <= max_length
    ]

Мы сразу понимаем:

words      → список строк
max_length → целое число
результат  → список строк

Даже не читая тело функции, можно получить достаточно много полезной информации.


40. Автоматическая проверка типов

mypy может обнаруживать:

  • передачу аргументов неподходящих типов;
  • несовместимое присваивание переменной;
  • неправильный тип возвращаемого значения;
  • использование методов, которых нет у предполагаемого типа;
  • некоторые другие ошибки совместимости типов.

Например:

def get_total(
    numbers: list[int],
) -> int:
    return sum(numbers)

Вызов:

get_total(
    ['10', '20', '30']
)

не соответствует контракту функции.

mypy способен обнаружить эту ошибку без запуска программы.


41. Автодополнение в редакторе

Допустим:

def process_names(names):
    for name in names:
        ...

Без аннотаций редактору может быть сложно определить предполагаемый тип name.

Он может попытаться вывести его из других частей программы, но не всегда сможет сделать это точно.

Если написать:

def process_names(
    names: list[str],
) -> None:
    for name in names:
        print(name.upper())

редактор получает гораздо более точную информацию.

Теперь при вводе:

name.

Visual Studio Code, PyCharm и другие современные среды разработки могут показывать подходящие методы класса str.

Это:

  • ускоряет написание кода;
  • уменьшает количество опечаток;
  • облегчает изучение доступных методов;
  • помогает заранее замечать несовместимые операции.

Аннотации улучшают не только подсказки, но и сам анализ кода редактором.


42. Удобство сопровождения программы

Представим, что функцию написал другой разработчик.

def calculate_discount(
    price: float,
    discount: float,
) -> float:
    return price * (
        1 - discount / 100
    )

Уже по определению понятно, что ожидаются числовые значения.

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

Аннотации также помогают при изменениях кода: если мы поменяли тип возвращаемого значения или параметра, анализатор может показать другие участки программы, которые теперь используют функцию неправильно.


43. Аннотации — это документация интерфейса

Сигнатура:

def get_usernames(
    users: dict[int, str],
) -> list[str]:
    return list(users.values())

фактически описывает небольшой контракт:

Получаем словарь:

ключ     → int
значение → str

Возвращаем:

list[str]

Это позволяет понять назначение функции без отдельного длинного объяснения типов аргументов.


Нужно ли аннотировать абсолютно все переменные?

44. Обычно нет

Например:

name = 'Alex'

age = 30

numbers = [10, 20, 30]

Python-анализаторы и редакторы часто могут самостоятельно определить тип этих объектов.

Поэтому нет необходимости всегда писать:

name: str = 'Alex'

age: int = 30

numbers: list[int] = [
    10,
    20,
    30,
]

Такой код корректен, но аннотации здесь могут оказаться избыточными.


45. Когда переменную полезно аннотировать

Например, при создании пустого списка:

results = []

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

Можно явно написать:

results: list[int] = []

Теперь намерение понятно.

Или при работе с несколькими допустимыми типами:

response: str | None = None

Такая аннотация помогает понять, что переменная может содержать строку или отсутствие значения.


46. Основное внимание — функциям и методам

В профессиональной разработке особенно полезно аннотировать сигнатуры функций и методов:

def calculate_total(
    prices: list[float],
    discount: float = 0,
) -> float:
    return (
        sum(prices)
        * (1 - discount / 100)
    )

Мы сразу видим:

  • какие типы ожидаются;
  • какие параметры необязательные;
  • какой тип возвращается.

Поэтому для наших учебных и будущих коммерческих проектов хорошим правилом будет:

Аннотировать параметры и возвращаемые значения собственных функций и методов, особенно если они используются в других частях программы.

Локальные переменные аннотируем дополнительно там, где это улучшает читаемость или помогает анализатору типов.


47. Аннотация object

В Python существует базовый класс:

object

Практически все привычные нам Python-объекты являются экземплярами object.

Поэтому можно написать:

value: object = 100

Затем:

value = 'Python'

Или:

value = [10, 20, 30]

Такие значения подходят под аннотацию:

object

48. object в параметрах функций

Например:

def show_value(
    value: object,
) -> None:
    print(value)

Можно передать:

show_value(100)

show_value('Python')

show_value([10, 20, 30])

show_value(None)

Все эти объекты допустимы.

Аннотация:

value: object

показывает:

Функция принимает объект произвольного типа.


49. У object есть ограничение

Аннотация:

object

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

Например:

def process_value(
    value: object,
) -> None:
    print(value.upper())

mypy сообщит, что у обычного object метод upper() не гарантирован.

Почему?

Потому что мы можем передать:

100

а у int нет метода:

upper()

Поэтому аннотация:

object

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

Но для функций, работающих с конкретными типами данных, лучше использовать более точные аннотации.

Например:

def process_value(
    value: str,
) -> None:
    print(value.upper())

50. Аннотации не являются проверкой isinstance()

Важно не путать две разные задачи.

Аннотация:

def show_name(name: str) -> None:
    print(name)

сообщает ожидаемый тип.

Но она не заставляет интерпретатор проверять его при каждом вызове.

А:

isinstance(value, str)

выполняет настоящую проверку типа во время работы программы.

То есть:

Аннотации + mypy
→ статический анализ кода

isinstance()
→ проверка при выполнении программы

Аннотации не заменяют isinstance(), когда программе действительно требуется проверять тип входящих данных во время выполнения.


51. Синтаксис аннотаций в разных версиях Python

Возможность Версия
Аннотации параметров и результата функции Python 3.0
Стандарт type hints — PEP 484 Python 3.5
Аннотации переменных name: type — PEP 526 Python 3.6
list[int], dict[str, int], tuple[int, ...] — PEP 585 Python 3.9
Объединение типов int \| str — PEP 604 Python 3.10

Поэтому все основные примеры из этого конспекта предназначены для Python 3.10 и новее.

В старых версиях часть аннотаций записывалась через специальные объекты модуля typing.


52. Краткая таблица аннотаций

Аннотация Значение
int Целое число
float Вещественное число
str Строка
bool Логическое значение
None Отсутствующее значение
int \| str Целое число или строка
int \| None Целое число или None
list[int] Список целых чисел
list[str] Список строк
list[list[int]] Список списков целых чисел
tuple[str, int] Кортеж из строки и целого числа
tuple[int, ...] Кортеж произвольной длины из целых чисел
dict[str, int] Словарь со строковыми ключами и целочисленными значениями
dict[str, list[int]] Словарь, где значения — списки целых чисел
set[str] Множество строк
frozenset[int] Неизменяемое множество целых чисел
deque[int] Двусторонняя очередь целых чисел
object Объект произвольного типа

Главное по теме

Аннотации позволяют описывать предполагаемые типы объектов.

Переменная:

username: str = 'Alex'

Несколько допустимых типов:

value: int | str = 100

Список:

numbers: list[int] = [
    10,
    20,
    30,
]

Кортеж:

coordinates: tuple[int, int] = (
    10,
    20,
)

Словарь:

user: dict[str, int] = {
    'age': 30,
    'score': 100,
}

Множество:

numbers: set[int] = {
    10,
    20,
    30,
}

Функция:

def add_numbers(
    first: int,
    second: int,
) -> int:
    return first + second

Основные преимущества аннотаций:

  1. Читаемость. Сразу видно, какие типы данных ожидаются и возвращаются.
  2. Статическая проверка. Инструменты вроде mypy обнаруживают многие ошибки типов до запуска программы.
  3. Автодополнение. Редакторы лучше понимают доступные методы и свойства объектов.
  4. Сопровождение. Проще изменять функции и находить участки программы, которые перестали соответствовать их интерфейсам.
  5. Документирование кода. Аннотации помогают другим разработчикам понимать назначение функций.

При этом Python остаётся языком с динамической типизацией: сами аннотации не запрещают присваивание объектов другого типа и не выполняют автоматическую проверку во время работы программы.

В первую очередь будем аннотировать параметры и возвращаемые значения функций и методов, а обычные переменные — там, где это действительно полезно.


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

Дополнительные возможности модуля typing, более сложные аннотации и инструменты типизации изучим в следующих темах.