VS Code:
генератор и проверка

Категория

Рабочее место

Уровень

Начальный

Опирается на

Главы 4.7–4.9, тема 02

Зачем это знать

Не набирать разделы руками и не искать пропуски глазами

§1Что редактор делает без расширений

Расширение Python от Microsoft вместе с языковым сервером Pylance устанавливается в VS Code одним пакетом и выполняет две задачи из этой темы.

Заготовку докстринга по подписи функции встроенные средства не создают. Для этого ставят отдельное расширение.

§2Расширение autoDocstring

autoDocstring — расширение VS Code, которое читает подпись функции и вставляет заготовку докстринга: краткую строку, раздел с параметрами по именам аргументов, раздел результата и раздел исключений, если в теле есть raise. Текст описаний пишет человек, разметку и перечень имён — расширение.

Установка: откройте панель расширений (CtrlCmd + Shift + X), введите в поиске идентификатор и нажмите Install.

njpwerner.autodocstring

Расширение ищут по идентификатору: в поиске есть несколько расширений с похожими названиями, и идентификатор отличает нужное однозначно.

§3Как вызвать генератор

Разберём вставку на функции revenue_by_waiter из файла app/services/orders.py стартового архива. Порядок такой:

1. Откройте файл и поставьте курсор на строку с def — ту, у которой нужно описание.
2. Нажмите End (CtrlCmd + →) и затем Enter: под подписью появится пустая строка с отступом тела.
3. Вызовите генератор любым из трёх способов: наберите три двойные кавычки и нажмите Enter; либо нажмите CtrlCmd + Shift + 2; либо откройте палитру команд (CtrlCmd + Shift + P) и выберите Generate Docstring.
4. Заполните поля заготовки, переходя между ними клавишей Tab.

После вызова генератора в файл вставляется такая заготовка:

def revenue_by_waiter(orders: list[Order], top: int = 0) -> dict[str, int]:
    """_summary_

    Args:
        orders (list[Order]): _description_
        top (int, optional): _description_. Defaults to 0.

    Raises:
        ValueError: _description_

    Returns:
        dict[str, int]: _description_
    """

Что сделало расширение и что осталось человеку:

§4Настройка формата в проекте

По умолчанию расширение вставляет формат google. Формат задают явно, чтобы у всех в команде получалась одинаковая разметка. Настройка хранится в файле .vscode/settings.json внутри проекта и попадает в репозиторий вместе с кодом.

{
  "autoDocstring.docstringFormat": "google",
  "autoDocstring.startOnNewLine": false,
  "autoDocstring.includeName": false,
  "autoDocstring.guessTypes": true,
  "autoDocstring.quoteStyle": "\"\"\""
}

Значение параметра docstringFormat выбирается из перечня форматов расширения:

Для проектов курса подходит google-notypes: типы остаются в подписи функции и в докстринге не повторяются. Начать можно с google и убирать типы вручную, пока формат не стал привычным.

§5Где лежат настройки

У VS Code два уровня настроек. Настройки проекта лежат в папке .vscode рядом с кодом и действуют на всех, кто откроет этот репозиторий. Настройки пользователя действуют на все проекты этого компьютера и в репозиторий не попадают.

Оба файла открываются через палитру команд: Preferences: Open Workspace Settings (JSON) для проекта и Preferences: Open User Settings (JSON) для пользователя. Путь при этом искать не нужно.

§6Полезные параметры генератора

§7Свой шаблон

Встроенные форматы меняются через шаблон на языке mustache: в нём подстановки вида {{name}} заменяются данными из подписи функции. Шаблон кладут в репозиторий и указывают путь в настройках проекта.

{{summaryPlaceholder}}
{{#parametersExist}}

Args:
{{#args}}
    {{var}}: {{descriptionPlaceholder}}
{{/args}}
{{/parametersExist}}
{{#exceptionsExist}}

Raises:
{{#exceptions}}
    {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{/exceptionsExist}}
{{#returnsExist}}

Returns:
    {{descriptionPlaceholder}}
{{/returnsExist}}

{
  "autoDocstring.customTemplatePath": ".vscode/docstring.mustache"
}

Этот шаблон отличается от встроенного google одним: типы в разделе Args: не подставляются, потому что они уже есть в подписи. Разделы Args:, Raises: и Returns: вставляются только тогда, когда у функции есть параметры, raise в теле и возвращаемое значение.

§8Сниппет вместо расширения

Заготовку можно вставлять и средствами самого редактора, без расширения. Сниппет — шаблон текста, который вставляется по короткому слову и клавише Tab. Сниппеты проекта лежат в файле с расширением .code-snippets в папке .vscode.

{
  "Докстринг в формате Google": {
    "scope": "python",
    "prefix": "dsg",
    "body": [
      "\"\"\"${1:Действие функции одним предложением.}",
      "",
      "Args:",
      "    ${2:параметр}: ${3:ограничения и смысл}",
      "",
      "Returns:",
      "    ${4:что означает результат}",
      "\"\"\""
    ],
    "description": "Заготовка докстринга с разделами Args и Returns"
  }
}

Наберите dsg и нажмите Tab — вставится этот текст, курсор встанет в первое поле, переход между полями по Tab. Имена параметров сниппет не подставляет: он вставляет заранее записанный текст, одинаковый для любой функции. Зато установки он не требует и работает в любой сборке редактора.

§9Проверка докстрингов программой

Генератор вставляет разметку, но не показывает места, где описания нет. Их находит проверка кода. В курсе используется Ruff — программа проверки кода на Python, в которую входят правила pydocstyle: они отвечают за докстринги и обозначаются кодами с буквой D.

Правила включаются в файле pyproject.toml в корне проекта:

[tool.ruff.lint]
select = ["E", "F", "D"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
"tests/*" = ["D"]

Три части этого файла означают следующее. Набор "D" включает правила о докстрингах вместе с обычными проверками кода. Строка convention = "google" согласует правила с выбранным форматом: часть правил, относящихся к другим форматам, отключается, чтобы требования не противоречили друг другу. Последний раздел снимает требование докстрингов с папки тестов: имя тестовой функции там само описывает проверяемый случай.

$ ruff check app --output-format=concise

По коду правила его находят в документации Ruff, где описано, что оно проверяет и как исправить.

§10Правила, которые чаще срабатывают

Как это выглядит на коде проекта — четыре случая с настоящим выводом проверки:

def format_title(text: str, width: int = 40) -> str:
    return text.center(width, "=")

formatter.py:1:1: D100 Missing docstring in public module
formatter.py:1:5: D103 Missing docstring in public function

    """Центрирует заголовок отчёта
    Достраивает строку знаками «=» до нужной ширины.
    """

formatter.py:5:5: D205 1 blank line required between summary
line and description

    """Считает выручку по официантам.

    Args:
        orders: Заказы за смену.

    Returns:
        Выручка по именам.
    """

orders.py:4:5: D417 Missing argument description in the
docstring for `revenue_by_waiter`: `top`

    """
    Возвращает дату для шапки отчёта
    """

clock.py:5:5: D200 One-line docstring should fit on one line
clock.py:5:5: D212 Multi-line docstring summary should start
at the first line
clock.py:5:5: D415 First line should end with a period,
question mark, or exclamation point

Правило D417 отличается от остальных тем, что сравнивает докстринг с кодом: перечень параметров в разделе Args: с подписью функции. Добавленный аргумент, для которого забыли строку описания, находится сразу. Остальные правила проверяют наличие описания и его оформление.

У части замечаний есть готовое исправление. Пример: заготовка генератора оставляет краткую строку _summary_ без точки на конце, и правило D415 предлагает её поставить.

§11Проверка в редакторе и в запросе на слияние

Чтобы замечания появлялись во время набора кода, ставят расширение Ruff, его идентификатор — charliermarsh.ruff. После установки нарушения подчёркиваются в файле и перечисляются в панели Problems (CtrlCmd + Shift + M), а часть из них исправляется действием Quick Fix по сочетанию CtrlCmd + ..

Та же команда запускается в проверках запроса на слияние. Шаг Ruff стоит там следом за шагом mypy, который проверяет типы:

      - name: Проверка типов
        run: mypy app
      - name: Проверка кода и докстрингов
        run: ruff check app
      - name: Тесты
        run: python -m pytest -q

После этого отсутствие докстринга у публичной функции попадает в замечания к запросу на слияние так же, как функция без аннотаций или лишний импорт. Подробно устройство таких проверок разбирается в разделе про CI; здесь важен состав: один запуск ruff check покрывает и оформление кода, и наличие описаний, а типы проверяет mypy.

§12Мини-практика: десять минут

1. Установите расширение njpwerner.autodocstring через панель расширений.
2. Создайте в проекте файл .vscode/settings.json с параметрами из §4.
3. Откройте функцию без докстринга, поставьте курсор под подписью, наберите три кавычки и нажмите Enter. Заполните вставленные поля, переходя по Tab.
4. Добавьте в pyproject.toml разделы из §9 и выполните ruff check app. Разберите каждое замечание по таблице §10.
5. Исправьте замечания и добейтесь вывода All checks passed!.
6. Добавьте в функцию новый параметр, не дописывая раздел Args:, и запустите проверку снова: появится D417. Верните докстринг в соответствие с подписью.

§13Частые вопросы

§14Проверьте себя

§15Шпаргалка по главе

Итог главы

Редактор с расширением Python показывает докстринг в подсказке, но заготовку по подписи не создаёт: для этого ставят расширение njpwerner.autodocstring. Оно вставляет разметку выбранного формата, имена параметров, признак необязательности и раздел исключений; описания пишет человек. Формат задают в .vscode/settings.json внутри репозитория, потому что это договорённость команды. Свой шаблон подключают файлом mustache, а простую заготовку можно получить сниппетом редактора без установки расширений. Пропущенные и неверно оформленные докстринги находит проверка: правила pydocstyle включаются в pyproject.toml набором "D" с конвенцией google и запускаются командой ruff check в редакторе и в проверках запроса на слияние. Правило D417 сравнивает перечень параметров в докстринге с подписью функции. Верность описания по смыслу проверяет человек. В следующей главе всё это применяется к своему проекту: практика на паре и домашнее задание.