Обзор инструментов для автоформатирования кода Python

Благодаря легко читаемому и понятному синтаксису Python вполне обоснованно стал самым востребованным языком программирования на сегодняшний день. Области его применения настолько разнообразны, что программная инженерия, машинное обучение и наука о данных используют его для решения самых разных сложных задач. 

Один из немаловажных, но оставленных без должного внимания аспектов в написании чистого кода Python заключается в необходимости его качественного форматирования и проверок. 

Достаточно сказать, что автоматизация коснулась всех сторон современной жизни, и нам не составит особого труда привнести ее и в процесс ревью кода.

В нашем распоряжении есть несколько инструментов, позволяющих сэкономить драгоценное время и умственную энергию, чтобы вложить их в более важные дела, чем форматирование кода перед каждым git commit.

Перечислим некоторые из них:

• хуки pre-commit;
• black;
• isort.

Рассмотрим поочередно каждый инструмент и научимся настраивать их для проекта Python. 

Установка и применение хуков pre-commit 

Хуки pre-commit делают ровно то, что указано в названии: запускают определенные скрипты, которые проверяют код на наличие ошибок и конечных пробелов, активируют инструменты форматирования и проводят другие полезные проверки в процессе ревью. 

Мы исключим из сферы нашего внимания обычные хуки, а сосредоточимся только на двух важных из них.

Начнем с установки библиотеки (учитывая, что вы уже работаете в виртуальной среде): 

pip install pre-commit

После установки проверяем версию с помощью данной команды. Если все работает должным образом, на выводе получаем номер версии. 

$ pre-commit --version

pre-commit 2.17.0

Примечание. Для простой настройки инструментов автоформатирования необходимо наличие конфигурационного файла git в корневом каталоге проекта. 

Именно этим мы сейчас и займемся. 

Настройка конфигурационного файла 

Согласно документации в проекте должен быть конфигурационный файл pre-commit с именем .pre-commit-config.yaml. 

Теперь воспользуемся фрагментом кода с информацией о хуках, с которыми мы хотим работать. Прямо сейчас мы намерены запустить 2 из них: black и isort в файлах Python перед каждым коммитом.

А вот и их настройки: 

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
    -   id: check-yaml
    -   id: end-of-file-fixer
    -   id: trailing-whitespace
-   repo: https://github.com/psf/black
    rev: 21.12b0
    hooks:
    -   id: black
-   repo: https://github.com/pycqa/isort
    rev: 5.10.1
    hooks:
    -   id: isort
        name: isort (python)

Проведем построчный анализ:

• Строки 5–7: Первая строка id пытается загрузить все файлы yaml для проверки синтаксиса; вторая  —  следит за тем, чтобы файлы заканчивались переводом строки и только одним; третья  —  проверяет наличие конечных пробелов.  
• Строки 8–10: Настройка хука для black, который автоматически форматирует код Python и широко применяется во всей индустрии. 
• Строки 12–16: Настройка для библиотеки isort, которая автоматически сортирует импорты в коде, избавляя программистов от необходимости делать это вручную. 

С помощью следующей команды присоединяем их к конфигурации git, чтобы обеспечить их запуск перед каждым коммитом:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

Без особых усилий мы успешно настроили хуки pre-commit для проекта! 

Переходим к настройке black и isort. К счастью, для этого потребуется всего один конфигурационный файл. 

Установка и настройка black и isort

Легко и просто устанавливаем эти две библиотеки: 

pip install black isort

Из отлично написанной документации мы узнаем о назначении Black: 

Black ускоряет процесс ревью кода, производя минимальные возможные различия. Код, отформатированный в Black, выглядит одинаково независимо от проекта, который вы читаете. Со временем принципы форматирования становятся понятными, что позволяет сосредоточиться на содержании. 

isort также просто определяет области своего применения: 

isort —  это утилита/библиотека Python для сортировки импорта по алфавиту с автоматическим разделением на разделы и по типам. 

Для настройки потребуется всего один файл pyproject.toml.

Размещаем в нем следующий контент: 

[tool.black]
line-length = 109
target-version = ['py37']

[tool.isort]
profile = "black"

Вы можете менять не только длину строки в соответствии с личными или рабочими предпочтениями, но и другие настраиваемые переменные, предлагаемые Black. 

Теперь поясним, почему мы непосредственно задействуем этот конкретный файл: 

PEP 518 определяет pyproject.toml как конфигурационный файл, содержащий требования к системе сборки для проектов Python. 

На практике данный файл в корневом каталоге проекта позволяет использовать “глобальную” конфигурацию проверки/ревизии кода для всего проекта. 

Приступаем к их тестированию! 

Тестирование хуков pre-commit

Написав или отредактировав код в нескольких файлах, выполняем дальнейшую последовательность простых действий, чтобы протестировать работоспособность прикрепленных хуков. 

Сначала добавляем файлы или их комбинацию с помощью команды git add . в терминале. 

Я провожу тестирование в одном из моих текущих проектов Django. 

Выполняем git commit -m “a message here” и видим следующий результат: 

Это значит, что файлы были изменены путем форматирования, выполненного хуком pre-commit. 

При выполнении команды git status получаем следующее сообщение: 

Файл views.py содержит несколько строк, измененных в результате выполнения хуков. Их следует просмотреть. 

Так мы убедимся, что измененные файлы не будут автоматически зафиксированы. Это позволит просмотреть их еще раз и проверить корректность всех изменений. 

В качестве преднамеренного шага pre-commit никогда не изменит область staging (подготовки к коммиту) версионного кода. Поскольку любой запускаемый хук может содержать ошибки, исправление которых после совершенного коммита обернется головной болью, нам предоставляется дополнительная возможность еще раз проверить и убедиться, что все в порядке. 

Снова добавляем и фиксируем изменения в файлах: 

git add .
git commit -m "your message here"

Полученный результат:

Итак, мы успешно зафиксировали внесенные в код изменения!

Заключение 

Надеюсь, это краткое руководство дало вам представление о том, как использовать хуки pre-commit для автоформатирования без усилий и ручного вмешательства. 

Полезные ресурсы 

• Black docs
• isort docs
• Pre-commit hooks docs
• A GitHub issue that explains why that additional commit step is so necessary.

Благодарю за внимание! 🙂

Читайте также:

• Работа с панелью индикаторов. Руководство программиста Python. Часть 3
• Внимание: работает пакет Python Tweepy!
• Осваиваем веб-скрэпинг на Python

Читайте нас в Telegram, VK и Яндекс.Дзен

---

Перевод статьи Yash Prakash: The Easy Python Auto-code Formatting Guide