Dev Blog

Анотації типів і PyCharm ​

Анотації типів у Python 3.14 ​

Анотації документують контракт і допомагають IDE та статичному аналізатору. Python сам не перевіряє, чи передали саме зазначений тип. Наприклад, множення рядка на ціле виконується навіть у функції, анотованій як арифметична. Це не підстава передавати неправильні типи: код може працювати випадково й зламатися пізніше. https://docs.python.org/3.14/library/typing.html.

Пишіть анотації для параметрів і результатів власних функцій. list[int] означає список цілих, tuple[int, str] – пару з двох різних типів, dict[str, float] – словник рядкових ключів і дійсних значень. float | None дозволяє число або відсутність результату. -> None застосовують до дії без корисного поверненого значення. Для *grades: float анотація описує кожний аргумент, хоча всередині grades є кортежем. Для **prices: float вона описує кожне значення.

typing.Any послаблює статичні перевірки. Це не синонім «будь-який тип, який аналізатор уважно перевірить». Початківцю краще назвати точний тип або допустиме об’єднання, ніж приховати проблему через Any. Відсутність попередження не доводить правильність формули, тому приклади й граничні перевірки залишаються необхідними.

Відкладене обчислення анотацій ​

У Python 3.14 анотації функцій за замовчуванням обчислюються відкладено, коли до них звертаються. Це відрізняється і від негайного обчислення в попередніх версіях, і від зберігання рядків після from __future__ import annotations. Для наведених програм Python 3.14 цей імпорт не потрібний; він досі підтримується й змінює семантику, тому не слід називати його забороненим або універсально видаляти зі старих проєктів.

Модуль annotationlib пропонує get_annotations та формати VALUE, FORWARDREF, STRING. Для показу підписів функцій зручний STRING; результат є словником текстових описів. Безпосередній доступ до __annotations__ за звичайної семантики дає обчислені значення. Інтроспекція анотацій не є перевіркою правильності фактичного аргументу. https://docs.python.org/3.14/library/annotationlib.html.

py
from annotationlib import Format, get_annotations


def label(code: int) -> str:
    return f"N{code}"


print(get_annotations(label, format=Format.STRING))
print(label.__annotations__["return"] is str)
{'code': 'int', 'return': 'str'}
True

Обчислення анотацій може виконувати вирази. У звичайному прикладному коді не потрібно самостійно читати їх заради кожного виклику. Деталі відкладеної моделі описані в https://peps.python.org/pep-0649/ та https://peps.python.org/pep-0749/.

Робота з функціями в PyCharm ​

Поставте курсор у дужках виклику format_price і натисніть Ctrl+P (Parameter Info): IDE показує параметри, типи та значення за замовчуванням. Ctrl+Q відкриває Quick Documentation із рядком документації. Комбінації наведено для стандартної Windows-розкладки; інша Keymap може їх змінювати. https://www.jetbrains.com/help/pycharm/viewing-reference-information.html.

Знімок екрана

PyCharm, format_price call, Ctrl+P and Ctrl+Q in two crops.

Рис. 3.6. Параметри та документація функції

Рефакторинг Extract Function (Ctrl+Alt+M) допомагає винести виділений фрагмент у функцію. Перевірте, які змінні стали параметрами і який результат повертається. Change Signature (Ctrl+F6) змінює параметри та відповідні місця виклику. Перед підтвердженням перегляньте запропоновані зміни, після нього повторіть контрольні запуски. Довідка про рефакторинги: https://www.jetbrains.com/help/pycharm/extract-method.html та https://www.jetbrains.com/help/pycharm/change-signature.html. Автоматична зміна тексту не перевіряє математичний зміст вашого контракту.

Для функції area спробуйте в редакторі area("3", 4). Інспекція має вказати невідповідність str очікуваному float. Не залишайте такий виклик у підсумковій програмі. Статичний аналіз mypy та конфігурацію перевірок розглянемо в темі 16.

Знімок екрана

PyCharm: area("3", 4), hover highlighted string argument.

Рис. 3.7. Інспекція типу аргументу

Типові помилки та перевірка контрактів ​

Якщо програма друкує None, з’ясуйте, чи є return на кожному потрібному шляху. Якщо стан «переходить» між викликами, перевірте змінювані значення за замовчуванням і глобальні об’єкти. Якщо виникає UnboundLocalError, знайдіть усі присвоєння імені в тілі. Не додавайте global механічно: можливо, потрібен параметр.

Рекурсивний алгоритм перевіряйте окремо для бази, одного кроку, кількох кроків і забороненого входу. Запишіть величину, яка строго зменшується: число дисків, показник степеня, довжину проміжку. Для пошуку також потрібні порожній набір, перший та останній елементи, відсутнє значення. Для статистики перевірте один елемент, однакові оцінки й порожній результат після вилучення.

Розділяйте неправильний формат і неправильну область значень. У цій темі перевірку тексту можна виконати до int; для готових функцій допустима чітко записана передумова. Обробку винятків і захищене перетворення довільного тексту розглянемо в темі 4. Анотація не замінює жодної з цих перевірок.