ТИПЫ
Аннотации типов
Пять шагов: что такое аннотация, как записать тип, как запустить проверку в Pylance и mypy, какие ошибки она находит и как расставить аннотации в своём проекте.
МДК.01.01 · разработка программных модулей · тема 04 · после структуры проекта
11 глав
Аннотации типов
и документация кода
Какие значения принимает функция,
что она обещает и как это проверить
Проект разложен по модулям и пакетам в теме 02, функции разнесены по файлам в практикуме темы 03. Эта тема отвечает на следующий вопрос: как понять, что делает функция из соседнего модуля, не читая её тело. Разбор идёт на одном проекте — «Отчёт кафе», его архив скачивается в первой главе.
Тема из двух частей. Первая — аннотации типов: как записать, какие значения принимает и возвращает функция, какие типы бывают и как Pylance и mypy проверяют вызовы до запуска программы. Вторая — документация: виды документации кода, устройство докстринга и PEP 257, четыре формата записи, двенадцать разобранных случаев, генератор заготовок в VS Code и проверка, которая находит пропущенные описания.
Сборка сайта документации на Sphinx — следующая тема. Здесь пишется то, из чего этот сайт собирается.
ПланГлавы темы
Порядок в списке — порядок изучения. Сначала аннотации: понятие, типы, проверка и практика на проекте. Итог этой практики — стартовый код второй части, про документацию: понятия и форматы, разбор случаев, рабочее место, практика и домашняя работа.
ДОКСТРИНГИ
Что и в каком виде описывают
Виды документации, устройство докстринга, стандарт и четыре формата записи.
РАБОТА
Код, редактор, проверка
Разбор случаев на небольших функциях, настройка VS Code и работа со своим проектом.
ДАЛЬШЕ
Сайт документации
Следующая тема: из написанных докстрингов собирается сайт с оглавлением и поиском.
5.1Sphinx: первый запуск и состав папокследующая тема5.2conf.py, autodoc и napoleonследующая тема5.3Файлы .rst, automodule и sphinx-apidocследующая тема5.4Темы оформления и публикация на Pagesследующая тема
ФайлыМатериалы темы
Разбор во всех главах идёт на одном проекте. «Отчёт кафе» читает файл смены, считает выручку по официантам и печатает отчёт: десять модулей по пакетам, двенадцать тестов. Архивов три — по одному на этап. Каждый следующий получается из предыдущего: сначала в код добавляют аннотации, потом описания.
↓
1 · Без аннотаций и описанийZIP · главы 4.1–4.5, 17 ошибок mypy
↓
2 · С аннотациями, без описанийZIP · главы 4.6–4.11, 33 замечания Ruff
↓
3 · С аннотациями и описаниямиZIP · эталон, все проверки чистые
↓
Домашняя работа №4MD · состав папки lesson_04 и критерии
ИтогЧто остаётся после темы
К концу темы студент
Пишет аннотации типовУ параметров, результатов и переменных; коллекции с типом содержимого,
Order | None, Iterator, Callable.Проверяет типы до запускаPylance в режиме
basic подчёркивает неверные вызовы, mypy app отвечает Success, строка его вывода читается по частям.Различает виды документацииКомментарий, докстринг, аннотация, README и собранный сайт — с пониманием, где каждый хранится и кто его читает.
Пишет докстринг в формате GoogleКраткая строка, разделы
Args, Returns, Raises, Yields, Attributes — по месту.Отличает нужное от лишнегоВ описании нет повтора подписи, пересказа тела и оценок кода; есть ограничения, единицы измерения и побочные действия.
Настроил рабочее местоГенератор заготовок в VS Code с форматом проекта и правила проверки в
pyproject.toml.Проверяет описания программой
ruff check проходит без замечаний, расхождение докстринга с подписью находится правилом D417.Сдал аннотированный и задокументированный пакетПапка
lesson_04 в личном репозитории, запрос на слияние, сохранённый вывод справки.
Тема 04 · Аннотации типов и документация кода · МДК.01.01 · 2 курс