# Домашнее задание №4 — lesson_04: аннотации и докстринги

В личном репозитории дисциплины создайте lesson_04/. Папки lesson_01,
lesson_02 и lesson_03 не изменяйте. Основа работы — ваш проект Student Tools
из домашнего задания темы 02: скопируйте его в lesson_04 и добавьте две
функции, чтобы в проекте встретились случаи разного вида.

Функция save_report в новом модуле app/services/report_file.py записывает
готовый отчёт в текстовый файл в кодировке UTF-8, возвращает число записанных
строк и перезаписывает существующий файл. Функция grade_bounds в
app/services/calculator.py возвращает пару «минимум, максимум» и возбуждает
ValueError на пустом списке. Обе вызываются из main.py и покрыты тестами:
обычный и пустой список для расчёта, запись в существующий и в новый файл.

Работа делается в два шага, как тема. Сначала весь проект получает аннотации
типов: у каждой функции типы параметров, кроме self, и тип результата, у
коллекций — тип содержимого (list[int], tuple[int, int], dict[str, int]).
Команда mypy app должна отвечать Success: no issues found. Any и
# type: ignore вместо аннотаций не допускаются.

Затем задокументируйте проект в формате Google. Докстринги обязательны у всех
модулей пакета app, у пакета в app/__init__.py, у публичных функций и классов.
В описаниях укажите то, чего не видно из подписи: ограничения на входные
данные, единицы измерения, порядок значений в результате, перезапись файла.
У функций с raise заполните раздел Raises. Типы из аннотаций не дублируйте,
тело функции не пересказывайте.

Включите проверки в pyproject.toml: раздел [tool.mypy] с
disallow_untyped_defs = true; для Ruff — набор «D», конвенция google, для
папки tests правила D отключены. Команда ruff check app должна отвечать
All checks passed!. Строк _summary_ и _description_ в коде остаться не должно.

Состав папки: app/ с докстрингами, main.py, tests/ (не меньше семи тестов),
pyproject.toml, .vscode/settings.json (формат докстрингов и режим проверки
типов basic), requirements.txt с ruff и mypy, README.md и
docs/help.txt с сохранённым выводом справки по двум модулям:

    python -c "import app.services.calculator as m; help(m)" > docs/help.txt
    python -c "import app.services.report_file as m; help(m)" >> docs/help.txt

В README добавьте два раздела к тем, что были в теме 02: выбранный формат
докстрингов и команда проверки с её выводом. В Git не должны попасть .venv/,
__pycache__/, .env и файл отчёта, созданный при запуске.

Перед сдачей скачайте свою работу в отдельную папку, создайте новое окружение,
установите зависимости и проверьте: запуск, python -m pytest -v, mypy app,
ruff check app,
поиск по строкам _summary_ и _description_, чтение docs/help.txt подряд.

Сдача: задача в своём репозитории, ветка lesson-04-docstrings, запрос на
слияние в main со ссылкой в ответ. В описании запроса укажите формат, команду
проверки и её вывод.

Критерии: аннотации типов и чистый mypy 2, докстринги модулей, пакета и
функций в формате Google 2, ограничения и исключения 2, настроенные проверки
mypy и Ruff 2, новые функции, тесты и README 2. Максимум 10 баллов.