pv-docstring (VS Code)

VS Code extension для проверки docstring в Python-файлах с помощью CLI-утилиты pv-docstring.

Показывает нарушения как подчёркивания в редакторе и записи в панели Problems.

Установка

Расширение включает собранный бинарник pv-docstring в директории bin/. Дополнительная установка CLI не требуется.

Собери расширение:

npm install
npm run compile

Запусти через Extension Development Host (F5 в VS Code) или упакуй:

npm run package
code --install-extension pv-docstring-0.1.0.vsix

Пересборка бинарника

Если нужно обновить бинарник (из корня pv-tools):

cargo build --release -p pv-docstring
cp target/release/pv-docstring vscode-pv-docstring/bin/pv-docstring

Настройки

Все настройки доступны через settings.json или UI настроек (поиск по pvDocstring).

Примеры .vscode/settings.json

Полное сканирование (по умолчанию) — проверяет каждый файл целиком при открытии и сохранении:

{
  "pvDocstring.mode": "full"
}

Только staged-изменения — проверяет только то, что добавлено через git add. Удобно перед коммитом, чтобы видеть проблемы только в новом коде:

{
  "pvDocstring.mode": "staged"
}

Только unstaged-изменения — проверяет изменения в tracked файлах, которые ещё не git add:

{
  "pvDocstring.mode": "unstaged"
}

Только untracked-файлы — проверяет новые .py файлы, которые ещё не добавлены в git:

{
  "pvDocstring.mode": "untracked"
}

Сравнение с веткой — показывает нарушения только в коде, который отличается от указанной ветки. Удобно для code review:

{
  "pvDocstring.mode": "base-branch",
  "pvDocstring.baseBranch": "master"
}

Сравнение с main:

{
  "pvDocstring.mode": "base-branch",
  "pvDocstring.baseBranch": "main"
}

Всё незакоммиченное — staged + unstaged + untracked. Самый полный режим для разработки — видит вообще всё, что отличается от последнего коммита:

{
  "pvDocstring.mode": "all-uncommitted"
}

Использование внешнего бинарника

Если pv-docstring установлен глобально или нужна конкретная версия:

{
  "pvDocstring.executablePath": "/usr/local/bin/pv-docstring"
}

Использование CLI напрямую

Расширение использует pv-docstring CLI. Те же команды можно запускать из терминала.

Полное сканирование

# Весь проект
pv-docstring full /path/to/project

# Один файл
pv-docstring full /path/to/file.py

# JSON-вывод
pv-docstring --format json full .

# GitHub Actions annotations
pv-docstring --format github full .

Diff-режимы

# Только staged-изменения (для pre-commit хуков)
pv-docstring diff --staged

# Только unstaged-изменения (во время разработки)
pv-docstring diff --unstaged

# Сравнение с веткой (для CI)
pv-docstring diff --base-branch main

# Сравнение с веткой + фильтр по пути
pv-docstring diff --base-branch main --path src/

# JSON-вывод для diff
pv-docstring --format json diff --staged

Дополнительные аргументы (args)

Через pvDocstring.args можно передавать любые флаги CLI. Аргументы вставляются между --format json и подкомандой:

pv-docstring --format json <args...> full <file>
pv-docstring --format json <args...> diff --staged

Коды ошибок

Наличие docstring (D1xx)

Формат summary (D2xx)

Секции Args / Returns / Raises (D3xx)

Структура docstring (D4xx)

Что пропускается по умолчанию

• Dunder-методы (__init__, __str__, ...)
• Тестовые методы (test_*, setUp, tearDown)

Управление триггерами

// По умолчанию — проверка при открытии и при сохранении:
{ "pvDocstring.lintTriggers": ["open", "save"] }

// Только при сохранении:
{ "pvDocstring.lintTriggers": ["save"] }

// Только при открытии (+ все уже открытые файлы при старте):
{ "pvDocstring.lintTriggers": ["open"] }

Как работает

• Триггеры настраиваются через pvDocstring.lintTriggers: open (открытие файла + уже открытые при старте) и save (сохранение).
• В режиме full — вызывается pv-docstring --format json full <file> на каждый файл.
• В diff-режимах (staged, unstaged, base-branch) — вызывается pv-docstring --format json diff ... на весь репозиторий, нарушения распределяются по файлам.
• В режиме untracked — находятся новые .py файлы через git ls-files --others и проверяются через full.
• all-uncommitted — параллельно запускает staged + unstaged + untracked и мёржит с дедупликацией.
• Если бинарник не найден, показывается предупреждение (один раз за сессию).