Этот тренажер посвящён документированию функций в Python с помощью docstring. Хорошая документация — это не просто формальность, а реальный инструмент, который помогает другим разработчикам (и тебе через полгода) понять, что делает код. В заданиях ты научишься писать docstring в разных форматах, разберёшься с тем, как Python хранит документацию, и потренируешься читать чужие docstring. Мы рассмотрим однострочные и многострочные варианты, форматы Google Style и reStructuredText, а также поработаем с атрибутом __doc__. Задания идут от простого к сложному — начнём с базового синтаксиса и закончим полноценным документированием функций с параметрами и возвращаемыми значениями.
- Модуль 1: Основы синтаксиса Python
- Модуль 2: Переменные и типы данных
- Модуль 3: Операторы
- Арифметические операторы (+, -, *, /).
- Целочисленное деление и остаток (// и %).
- Возведение в степень (**).
- Операторы сравнения.
- Логические операторы (and, or, not).
- Операторы присваивания (=, +=, -=).
- Операторы принадлежности (in, not in).
- Операторы идентичности (is, is not).
- Битовые операторы.
- Тернарный оператор.
- Модуль 4: Ввод и вывод данных
- Модуль 5: Условные конструкции
- Модуль 6: Циклы
- Модуль 7: Строки
- Модуль 8: Списки
- Модуль 9: Кортежи
- Модуль 10: Словари
- Модуль 11: Множества
- Модуль 12: Функции
- Модуль 13: Встроенные функции
- Модуль 14: Работа с файлами
- Модуль 15: Обработка исключений
- Модуль 16: Модули и пакеты
- Модуль 17: ООП - Основы
- Модуль 18: ООП - Продвинутый уровень
- Модуль 19: Декораторы
- Модуль 20: Генераторы и итераторы
- Модуль 21: Регулярные выражения
- Модуль 22: Дата и время
- Модуль 23: Математические операции
- Модуль 24: Работа с сетью
- Модуль 25: Асинхронное программирование
- Модуль 26: Многопоточность
- Модуль 27: Тестирование
- Модуль 28: Базы данных
- Модуль 29: Алгоритмы и структуры данных
- Модуль 30: Продвинутые возможности
Базовый синтаксис docstring
Docstring размещается сразу после объявления функции и заключается в специальные кавычки. Дополните код, чтобы функция имела корректную строку документации.
def greet(name):
input1SВозвращает приветствие для указанного имени.input2S
return f"Привет, {name}!"Доступ к документации функции
Python сохраняет docstring функции в специальном атрибуте. Проанализируйте код и определите, что будет выведено на экран.
def add(a, b):
"""Складывает два числа."""
return a + b
print(add.__doc__)Исправьте расположение docstring
Docstring должен располагаться в определённом месте, иначе Python не распознает его как документацию. Найдите и исправьте ошибку в коде.
def multiply(x, y): result = x * y """Умножает x на y и возвращает результат.""" return resultФорматы документирования
Существует несколько популярных стилей написания docstring. Сопоставьте название формата с его характерной особенностью.
Функция без docstring
Что вернёт обращение к атрибуту __doc__ у функции, которая не имеет docstring? Введите результат.
def empty_function():
pass
print(empty_function.__doc__)Однострочные и многострочные docstring
Распределите примеры docstring по категориям: какие являются однострочными (помещаются в одну строку), а какие — многострочными.
Docstring в формате Google Style
Заполните пропуски в docstring, используя токены из банка. Функция принимает имя и возраст, возвращает отформатированную строку.
def create_profile(name, age):
"""Создаёт строку профиля пользователя.
input1S
name: Имя пользователя.
input2S Возраст пользователя.
input3S
Строка вида 'Имя: X, Возраст: Y'.
"""
return f"Имя: {name}, Возраст: {age}"Docstring в формате reStructuredText
Формат reStructuredText (Sphinx) использует специальные директивы для документирования. Заполните пропуски, чтобы получить корректный docstring.
def divide(a, b):
"""Делит одно число на другое.
input1S a: Делимое.
input2S b: Делитель.
input3S Результат деления.
:raises ZeroDivisionError: Если b равен нулю.
"""
return a / bСтруктура многострочного docstring
Расставьте строки docstring в правильном порядке согласно соглашениям PEP 257 и Google Style.
Функция help() и docstring
Встроенная функция help() выводит справку о функции. Что будет показано для функции с docstring?
def square(n):
"""Возвращает квадрат числа."""
return n ** 2
help(square)Исправьте docstring с ошибкой
В этом коде docstring написан с нарушением синтаксиса Python. Найдите и исправьте ошибку.
def validate_email(email): "Проверяет корректность email-адреса. Args: email: Строка с email. Returns: True если email корректен, иначе False." return '@' in emailСоберите функцию с полным docstring
Соберите функцию calculate_area, которая вычисляет площадь прямоугольника. Функция должна иметь docstring в формате Google Style с секциями Args и Returns. Одна строка лишняя.
def calculate_area(width, height): """Вычисляет площадь прямоугольника. Args: width: Ширина прямоугольника. height: Высота прямоугольника. Returns: Площадь прямоугольника. """ return width * height Parameters:Документирование исключений
Помимо параметров и возвращаемого значения, docstring может описывать исключения, которые функция может выбросить. Заполните пропуски.
def get_element(items, index):
"""Возвращает элемент списка по индексу.
Args:
items: Список элементов.
index: Индекс элемента.
Returns:
Элемент списка.
input1S
input2S Если индекс выходит за границы списка.
TypeError: Если items не является списком.
"""
if not isinstance(items, list):
raise TypeError("items должен быть списком")
return items[index]Доступ к docstring через __doc__
Изучите код и определите, что будет выведено. Обратите внимание на форматирование вывода.
def test():
"""Первая строка.
Вторая строка."""
pass
print(test.__doc__.split('\n')[0])Полный docstring с типами
Дополните docstring функции, добавив информацию о типах параметров и возвращаемого значения в формате Google Style.
def repeat_string(text, times):
"""Повторяет строку указанное количество раз.
Args:
text input1S: Исходная строка.
times input2S: Количество повторений.
Returns:
input3S: Строка, повторённая times раз.
"""
return text * times