Урок 44. Документация. Аннотации типов

📁 Блок: Python Fundamentals / Функции и качество кода ⏱️ Время изучения: ~100 мин 🎯 Сложность: Начальная — средняя
#def #return #help #print #from #import #copy #add #factorial #range #for #in #set #frozenset #split #count #get #zip #id #append #lambda #len #str #items #join #if #not #pop #strip #mkdir #sum #upper #is #class

⚡ Кратко: что важно

Docstring — это строка документации сразу после def/class/module, которую можно посмотреть через help() или __doc__.

Аннотации типов (type hints) описывают ожидаемые типы аргументов и результата функции, но Python не проверяет их во время выполнения.

Современный Python 3.9+ позволяет писать list[int] и dict[str, int]; раньше для этого нужен был модуль typing.

Топ-3 ошибки: путать print и return при аннотации возвращаемого типа; думать, что аннотации блокируют неправильные типы; изменять изменяемый аргумент внутри функции без копии.

О чём этот урок

Урок учит писать понятный сопровождаемый код: документировать функции через docstrings, читать справку с help(), добавлять аннотации типов для параметров и возвращаемых значений, использовать встроенные generic-типы и модуль typing, а также учитывать, как изменяемые и неизменяемые объекты передаются в функции.

Цели

  • писать docstrings для функций, классов и модулей в формате reST/Epytext;
  • использовать help() и __doc__ для просмотра документации;
  • добавлять аннотации типов к переменным, параметрам и возвращаемым значениям;
  • применять list[int], tuple[str, int], dict[str, int], set[str];
  • использовать Any, Union/|, Optional и Callable из typing;
  • объяснять разницу между передачей изменяемых и неизменяемых объектов.

Что повторить заранее

  • Урок 43 — Summary session 11
  • функции, параметры и возвращаемое значение;
  • списки, словари, кортежи, множества;
  • изменяемые и неизменяемые типы.

Разделы урока

📖 Теория

Понятная теория по источнику

🔖 Справочник

Синтаксис, функции и методы

💻 Примеры

Запускаемые примеры Python

📦 Репозиторий

Примеры кода из репозитория 060326-Python: docstring, аннотации типов и изменяемые аргументы

⚖️ Старый vs Новый

Учебный стиль и современная практика

📝 Задания

Практика по возрастанию сложности

✅ Решения

Решения с пояснениями

🐛 Ошибки

Типичные ошибки и исправления

🏠 Домашнее задание

LMS-текст, план и проверка

🔗 Ресурсы

Документация и полезные ссылки

Что дальше