Молниеносный инкрементальный линтинг Python-кода
Линтинг кода бывает очень долгим, а в ситуациях наличия большого legacy‑проекта, который решили «причесать», линтинг может причинять боль и страдания разработчикам. В этой статье мы найдем решение, которое позволит без проблем линтить код с любого этапа разработки и делать это супер быстро и инкрементально!
Часто на проектах встречается проблема автоматического форматирования исходного кода для соответствия определенным стандартам стиля. Кроме того, хочется проверять свою разработку на наличие потенциальных проблем с безопасностью и общим качеством. Чтобы не тратить время на ручное ревью и форматирование кода разработчиком, возможно подключить так называемые линтеры — специальные пакеты для автоматизации вышеописанных проверок. Процесс таких проверок идет без выполнения исходного кода, поэтому он называется статическим анализом.
Линтеры интегрируются в CI/CD‑процессы (Continuous Integration, Continuous Delivery — непрерывная интеграция и доставка) и выполняются в pipeline (поток автоматической интеграции и доставки). Шаг за шагом стартуют разные типы проверок: собирается образ, запускаются линтеры, далее идут автоматические тесты и деплой приложения в целевую среду доставки.
Сложности с legacy-проектами
Если проект начинается с нуля, то внедрить статический анализ кода проще: код будет отформатирован и проверен с самого начала, с первого коммита. При таком подходе весь код приложения всегда соответствует стандартам проекта и проверен линтерами. Однако встречаются и проекты, на которых линтеры решили внедрить уже после начала разработки. Например, это был MVP (Minimum Viable Product — минимально жизнеспособный продукт), поэтому решили не тратить время на дополнительную вспомогательную работу. Тогда, если над проектом работает множество разработчиков, возникает проблема синхронизации правил оформления кода и требуется некая стандартизация в правилах.
Правила могут быть зафиксированы в настройках линтеров. После осуществления предварительных настроек линтеры добавляются к проекту, но появляется другая сложность — как быть с уже существующим, еще не отформатированным кодом при изменении части модуля? Если «прогнать» линтер по модулю, то будет затронут код, который не относится к задаче разработчика. Это может усложнить и замедлить процессы код‑ревью и доставки кода. Логичным видится решение проблемы путем форматирования только сделанных изменений, то есть отслеживать код инкремента. Для этого каким‑то образом необходимо получить эту разницу в коде и передать её на вход линтеру.
Так как у разработчиков в распоряжении всегда есть важный инструмент для работы с исходным кодом, а именно система контроля версий, то можно воспользоваться ей. git предоставляет подобную функциональность с помощью команды git diff, которая, согласно документации, позволяет получить разницу кода между коммитом и целевой веткой. Например, стандартный сценарий доставки кода следующий. Существует ветка master (или main), которая всегда доставляется до продакшн сервера. В эту ветку отправляется весь код, над которым работают разработчики в своих feature‑ветках. Значит, можно сопоставить версии кода из текущей feature‑ветки и целевой master‑ветки с получением искомой разницы. Именно эта разница и будет передаваться линтеру для проверки, что позволит отслеживать только измененный код и форматировать его. Подобный подход применим не ко всем типам линтеров.
Типы линтеров и сценарии их использования
Существует множество линтеров, нацеленных на решение определенных задач. Линтеры можно условно разделить на две группы: для автоматического форматирования и статического анализа. Линтеры, относящиеся к первой группе, исправляют оформление исходного кода согласно указанным в конфигурации стандартам. Линтеры из второй группы проверяют соответствие типов, наличие неиспользуемых импортов и переменных, оценивают качество кода и так далее.
Для инкрементального линтинга хорошо подходят линтеры‑форматировщики, так как они только форматируют код, поступающий к ним. То есть им можно передавать осмысленную (синтаксически корректную) часть кода и они её правильно обработают. Линтеры из второй группы не всегда способны правильно воспринять и интерпретировать лишь фрагменты кода без контекста их применения, так как они анализируют общую структуру, например, обнаруживают наличие неиспользуемых импортов модулей. Поэтому для такой группы линтеров инкрементальная проверка не применима в полной мере или не возможна. Однако допустимо передавать им список обновленных файлов для анализа, а не части затронутого изменениями кода.
При таком подходе (с передачей целиком файлов) может проверяться и legacy‑код (код, который ранее существовал в проекте), что не всегда является целью, потому что ревьювить такой код сложнее и появляются изменения, не относящиеся к задачам разработки. Тогда необходимо настроить конфигурацию линтера таким образом, чтобы степень строгости проверки была достаточной и в то же время оптимальной для конкретной ситуации и проекта. Исходя из этого, можно реализовать инкрементальный линтинг с гарантированным форматированием только измененного кода и опционально со статической проверкой файлов (возможно и с исправлением плохого кода), в которых были изменения.
Примеры линтеров из первой группы: Black, autopep8, YAPF, isort.
Примеры линтеров из второй группы: Pylint, Mypy, Flake8, Pyflakes.
Инструмент для инкрементального форматирования кода
Для решения вышеизложенной проблемы (с ней сталкивается едва ли не каждый разработчик) были предприняты попытки создания open‑source продукта под названием darken, который впоследствии переродился в проект Darker. Darker — линтер для инкрементального форматирования кода. Он основан на Black и даже использует его в своем исходном коде. Для обеспечения совместимости авторы Darker постоянно отслеживают изменения в Black и вносят соответствующие доработки для корректной работы с новой версией Black. Darker под капотом реализует все необходимые действия с git‑ом (использует git diff), находит измененный код и передает его Black для форматирования. Результат работы линтера записывается в исходные файлы, тем самым форматируются только обновленные блоки кода.
У Darker есть хорошая документация, которая позволит понять, как его настроить именно под нужды на вашем проекте. Так как Darker задействует git для получения информации о разнице кода можно задавать целевую ветку для сравнения. По умолчанию Darker использует последний коммит (HEAD — указатель на последний коммит в текущей ветке) в качестве отправной точки. Кроме того, есть возможность задать конкретные файлы для форматирования или отформатировать целиком весь проект. Чтобы попробовать Darker в действии достаточно его установить и запустить команду в корне репозитория с исходным кодом:
darker --diff .В консоль будет выведена информация с демонстрацией инкремента изменения (diff) и предложением отформатировать конкретные строки кода. Исходный код при этом затронут не будет. Данная команда полезна для предварительного анализа перед запуском фактического форматирования.
Чтобы действительно отформатировать код достаточно запустить команду:
darker .В консоль будет выведена информация о том какие файлы были затронуты обновлением.
Darker помимо своей основной функциональности интегрирован и с другими линтерами: flynt для обновления устаревшего стиля оформления строк на f‑строки, isort для сортировки импортов. Кроме того, Darker может работать с подключаемыми внешними линтерами. Список подходящих на момент написания статьи: Mypy, Pylint, Flake8, cov_to_lint.py (разработанный автором Darker).
Статический анализ кода
Для статического анализа кода в затронутых изменениями файлах рекомендую присмотреться к линтеру Ruff. Он разработан на языке Rust, включает в себя большое количество правил для анализа (более 700) и работает от 10 до 100 раз быстрее других линтеров, согласно заявлению его авторов. Он один способен заменить целый ряд линтеров: Flake8, isort, pydocstyle, yesqa, eradicate, pyupgrade, autoflake. Но специализированные инструменты для проверки типов (например, Mypy) Ruff в полной мере заменить не сможет.
Если вы хотите автоматизировать процесс линтинга еще больше, то это возможно. Ruff умеет исправлять fixable‑ошибки (исправляемые ошибки) в коде. Например, удалить неиспользуемые импорты или переменные. Полный список замечаний, которые можно исправить с помощью Ruff, доступен в документации. Все нужные правила возможно описать в едином файле pyproject.toml.
Пример конфигурации из документации
[tool.ruff]
# Enable the pycodestyle (`E`) and Pyflakes (`F`) rules by default.
# Unlike Flake8, Ruff doesn't enable pycodestyle warnings (`W`) or
# McCabe complexity (`C901`) by default.
select = ["E", "F"]
ignore = []
# Allow fix for all enabled rules (when `--fix`) is provided.
fixable = ["ALL"]
unfixable = []
# Exclude a variety of commonly ignored directories.
exclude = [
".bzr",
".direnv",
".eggs",
".git",
".git-rewrite",
".hg",
".mypy_cache",
".nox",
".pants.d",
".pytype",
".ruff_cache",
".svn",
".tox",
".venv",
"__pypackages__",
"_build",
"buck-out",
"build",
"dist",
"node_modules",
"venv",
]
per-file-ignores = {}
# Same as Black.
line-length = 88
# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
# Assume Python 3.8
target-version = "py38"Благодаря тонкой настройке линтера можно добиться необходимого вам результата, что позволит снизить количество рутинных действий и упростить жизнь разработчика.
Универсальное решение
Хотелось бы иметь некое универсальное решение, обладающее преимуществами Darker и Ruff для инкрементального линтинга — быструю работу и простоту использования с гибкостью конфигурации. Darker предоставляет возможность передачи консольной команды для запуска линтера в качестве аргумента. Это позволяет попробовать запустить Ruff вместе с Darker:
darker --revision origin/main --diff --check --lint "ruff check --exit-zero" .Ruff действительно работает только для измененных файлов и выводит предупреждения в соответствии с его настройками, но действует он не так быстро, как ожидалось согласно представлению о заявленной «молниеносной» работе. Такая команда при проведении эксперимента выполнялась 12 секунд в проекте с 42 тысячами строк кода. Причем сам Darker отработал и вывел результат за 2 секунды. Остальное время ушло на выполнение команды, которая указана в качестве значения аргумента ‑-lint. Если запустить данную команду отдельно, то получим результат за 70 миллисекунд (0.070 сек.), что в 142 раза быстрее!
Конкретные значения сильно зависят от контекста (объема исходного кода, количества изменений в нем и настроек линтера), но порядок величин понятен. Это значит, что если мы хотим по настоящему быстрого результата без раздражающего ожидания процесса линтинга, то Ruff необходимо запускать вне Darker. Да, в документации к Darker не заявлена поддержка Ruff, но попробовать стоило. Всё‑таки команда с запуском стороннего линтера удобна и доступна «из коробки».
Осталось решить вопрос запуска Ruff только для измененных файлов. Возможно разработать решение самостоятельно на базе команды git diff или попробовать найти что‑то готовое и подходящее. После недолгих поисков оказалось, что решение есть — git‑diff‑lint! Скрипт давно не обновлялся, но он минималистичен и работоспособен. Идея та же — скрипт получает относительные пути ко всем затронутым изменениями файлам и выводит их в консоль:
git diff --name-only --diff-filter=d $(git merge-base HEAD "origin/main") | grep -E "\.py$"git diff --name-only --diff-filter=d — получение путей ко всем измененным файлам (кроме удаленных).
git merge‑base HEAD «origin/main» — получение общего предка между двумя коммитами (подробнее в документации git).
grep -E »\.py$» — фильтрация по расширению .py.
Вывод этой команды вполне можно передать на вход Ruff для последующего анализа:
ruff check $(git diff --name-only --diff-filter=d $(git merge-base HEAD "origin/main") | grep -E "\.py$")Действительно, это работает. Линтер с ожидаемой скоростью обработал все измененные файлы и вывел результат в консоль.
Собираем всё вместе
Теперь осталось объединить все наработки вместе: взять Darker с его возможностью форматирования измененных строк кода и Ruff с его талантом быстро проводить статический анализ. Можно использовать следующую конструкцию для проверки кода (без внесения командой изменений в исходный код):
ruff check --exit-zero $(git diff --name-only --diff-filter=d $(git merge-base HEAD "origin/main") | grep -E "\.py$") && darker --revision origin/main --diff --check .Данная команда выведет в консоль все ошибки статического анализа, включая предложения линтера отформатировать код. Опция ‑-exit‑zero позволит выполниться следующей команде в случае наличия ошибок, обнаруженных Ruff.
Как уже известно Ruff достаточно способен, чтобы попытаться улучшить плохой код. Для того, чтобы исправить найденные ошибки, можно запустить команду:
ruff --fix .Но нужно быть осторожным и не переоценить его возможностей. Иногда изменения могут привести к критическим ошибкам в коде. Для того, чтобы этого избежать, необходимо тщательно настроить линтер и отключить те проверки, которые не требуются или потенциально могут привести к проблемам. Для конфигурации можно задать список исправляемых ошибок (fixable) и список неисправляемых ошибок (unfixable). Также в комплексном автоматизированном решении автоматические тесты способы решить эту задачу и выявить проблемы с кодом на раннем этапе. Вы же их пишете, правда?
Для автоматизации команд и удобства внедрения в повседневные процессы разработки и в CI/CD можно подготовить необходимые sh‑скрипты и использовать Makefile. В нем нужно описать требуемые таргеты с вызовами скриптов. Это позволит в одной команде запустить комплексный процесс анализа кода. Команды можно настроить нужным вам образом. В примере ниже идея в том, чтобы проверять форматирование кода и вызывать ошибку при наличии расхождений с правилами и в то же время статический анализ линтером Ruff не будет приводить к ошибкам даже при обнаруженных замечаниях.
Пример оформления таргетов в Makefile:
TARGET = origin/main
.PHONY: lint
lint: ## Статический анализ измененных файлов
# проверка качества кода
./git-diff-lint -x "ruff check --exit-zero" -b $(TARGET)
# проверка стиля оформления кода
darker --revision $(TARGET) --diff --check
.PHONY: fix
fix: ## Автоматическое исправление измененных файлов
# форматирование кода
darker --revision $(TARGET)
# попытка исправить обнаруженные недостатки кода
./git-diff-lint -x "ruff --fix --silent --exit-zero" -b $(TARGET)Тогда всё, что нужно будет сделать разработчику до оформления очередного коммита, вызвать команду make fix, которая приведет к форматированию измененного кода с автоматическим исправлением некачественного кода в затронутых файлах. Причем команда выполнится довольно быстро.
Для запуска проверок в CI/CD‑процессах команду make lint или исходные команды под этим таргетом можно добавить в один из шагов pipeline до слияния веток. Тогда наличие ошибок будет препятствовать слиянию и сигнализировать разработчику, ответственному за ветку, разобраться в проблеме и устранить найденные недостатки. Впоследствии такой подход обеспечит инкрементальное улучшение качества кода с каждым очередным коммитом.
Примеры скриптов можно найти на моем GitHub. Вы можете их адаптировать под свой проект и цели. Всем спасибо за внимание и молниеносного линтинга!
