Форматируем код при помощи black
В сообществе Python ещё лет 20 назад осознали ценность форматирования кода, когда на свет появился PEP8 — документ, который призван сделать весь код, написанный на Python, оформленным одинаково и поставить точку в бесконечных спорах о стиле оформления кода. PEP8 и правда глубоко вошёл в идеологию Python. Писать код, который нарушает PEP8 — это считается очень плохой практикой. Это одна из первых заповедей, про которые говорят начинающим питонистам.
Почему же консистентный стиль оформления кода так важен, что этому посвящен целый PEP? Самая главная мысль — читаемость важна. Вот какие ещё мысли у меня возникают по поводу стиля оформления кода.
Следование PEP8 можно автоматически контролировать при помощи таких инструментов, как flake8 или pylint, но тогда форматировать код придётся вручную. Как мы уже выяснили, время разработчика стоит дорого. Можно ли как-то автоматизировать этот процесс?
Кроме того, PEP8 описывает лишь основные правила оформления кода, но оставляет свободу интерпретации во множестве краевых случаев, из-за чего может появиться неконсистентность оформления. Есть ли какие-нибудь более строгие конвенции, чем PEP8?
black — бескомпромиссный форматтер кода
Попробуйте в команде хотя бы из нескольких человек прийти к согласию по поводу того, как код выглядит лучше всего и читается проще всего.
Например, оба варианта абсолютно валидны с точки зрения PEP8, но у каждого стиля есть свои поклонники и противники.
У меня был опыт попытки выработать в команде конвенцию, и это не так просто. Не потому что люди плохие или упрямые, просто у каждого своё понимание красоты и удобства. Наверняка, начнётся борьба вкусов и мнений. black избавляет от всех этих обсуждений — есть готовый стиль оформления кода, где все решения уже приняты за вас.
Да, иногда black выдаёт не самый красивый код, но, если подумать, красота кода не так важна, как консистентность, последовательность, одинаковость. black осознанно приносит красоту в жертву консистентности.
Скажу по собственному опыту, что к отформатированному black коду привыкаешь очень быстро, и буквально через несколько дней просто перестаешь замечать форматирование вообще. Просто читаешь код.
Установка
К сожалению, на момент написания этого поста, black не имеет стабильных релизов, пока что есть только бета-версии. Смею вас заверить, что black даже в бета-версии уже достаточно стабилен и используется в куче серьезных проектов. Правда, отсутствие стабильных релизов немного усложняет установку.
black устанавливается из PyPI. Давайте выясним, какая на данный момент последняя доступная версия при помощи следующего трюка (или можно просто её посмотреть на странице проекта на PyPI):
Команда завершится ошибкой, но выведет список доступных версий. Найдем последнюю доступную версию и запомним её.
Внутри виртуального окружения нужно выполнить, заменив версию на последнюю:
Использование
black имеет очень интуитивный интерфейс командной строки.
Вот так можно отформатировать все файлы в текущей директории (и рекурсивно в поддиректориях):
И это практически единственная команда, которую вам нужно запомнить.
А вот так можно отформатировать один конкретный файл:
Интеграция с редактором/IDE
Очень удобно, когда форматтер запускается прямо из редактора кода автоматически, например, при сохранении файла. black так или иначе можно интегрировать со всеми известными науке редакторами. Процесс подробно описан здесь. Обязательно это сделайте, иначе не ощутите всей прелести автоматического форматирования.
Использование в CI
А ещё нужно настроить запуск black в сервисе для непрерывной интеграции (CI), например, GitHub Actions, GitLab CI или Travis CI. Так black сможет блокировать пулл-реквесты (или мердж-реквесты), в которых содержится неотформатированный код.
В режиме “проверки” black не будет форматировать файлы, а просто напечатает список неотформатированных файлов и завершится кодом ошибки, что должно “уронить” всю проверку целиком.
Конфигурация
Кое-какую минимальную возможность настройки black все-таки предоставляет. Стоит отметить, что в большинстве случаев этого делать не придётся, потому что у black достаточно разумные настройки по умолчанию.
Вот так можно настроить максимальную длину строки и файлы, которые форматировать не нужно. В pyproject.toml в корне проекта добавьте:
Что меня бесит в стиле black
Есть некоторые моменты, с которыми я категорически несогласен. Думаю, рассказать про них тоже нужно.
Рассмотрим пример исходного кода:
Тернарный оператор затерялся среди других аргументов функции, его теперь очень трудно заметить. Чтобы исправить, давайте возьмём тернарный оператор в скобки и ещё раз отформатируем:
Теперь намного понятнее, не правда ли? Такое может произойти не только с тернарными операторами, но и с длинными арифметическими выражениями, и с длинными строками, которые разбиты на несколько частей:
Эта функция имеет два аргумента — булевый и строковый. Отформатируем:
black опять не помог сделать код читаемее. Выглядит так, будто функция имеет три аргумента, хотя на самом деле их только два. Нужно хорошо присмотреться, чтобы заметить отсутствие запятой. Поставим скобки вручную и отформатируем ещё раз:
Стало в сто раз лучше. Теперь всё очевидно.
Надеюсь, что когда-нибудь эту шероховатость починят, а до тех пор я просто вручную ставлю скобки вокруг вот такого некрасивого кода. Такое случается не так уж часто. В целом, даже почти не больно.
Заключение
Консистентное форматирование кода — это невероятно важно, потому что упрощает восприятие кода другими людьми (или самим же автором кода, но через полгода). Автоматическое форматирование кода (почти) не требует вообще никаких усилий со стороны автора.
Хоть black и имеет свои недостатки, он всё равно явно окупает усилия, затраченные на ручную расстановку скобок, потому что случается это довольно редко. Как и любой инструмент, black дорабатывается, и будем верить, что все проблемы рано или поздно исправят.
Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!
The uncompromising code formatter¶
By using Black, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.
Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.
Try it out now using the Black Playground.
Black is already successfully used by many projects, small and big. Black has a comprehensive test suite, with efficient parallel tests, our own auto formatting and parallel Continuous Integration runner. However, Black is still beta. Things will probably be wonky for a while. This is made explicit by the “Beta” trove classifier, as well as by the “b” in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.
Testimonials¶
Mike Bayer, author of SQLAlchemy:
I can’t think of any single tool in my entire programming career that has given me a bigger productivity increase by its introduction. I can now do refactorings in about 1% of the keystrokes that it would have taken me previously when we had no way for code to format itself.
Dusty Phillips, writer:
Black is opinionated so you don’t have to be.
Hynek Schlawack, creator of attrs, core developer of Twisted and CPython:
An auto-formatter that doesn’t suck is all I want for Xmas!
Carl Meyer, Django core developer:
At least the name is good.
Kenneth Reitz, creator of requests and pipenv:
This vastly improves the formatting of our code. Thanks a ton!
Держите свой код в чистоте с помощью Black & Pylint, Git Hooks и Pre-commit
Кодирование может быть очень сложной задачей, особенно при работе над проектом с разными разработчиками. Каждый член команды использует свой собственный способ кодирования, что приводит к очень разнородным сценариям.
Вот почему важно иметь аналогичный формататор кода и линтер кода, чтобы сделать ваши коммиты git более чистыми. Это может быть выполнено либо между этапами постановки и фиксации, либо во время цепочки CI / CD.
В этой статье мы увидим, как это сделать на этапе перед фиксацией с помощью хуков git.
Оглавление
Резюме выглядит следующим образом:
Black
Его можно установить с помощью следующей командной строки:
Вы можете запустить black в любом файле Python, набрав:
Black можно слегка настроить с помощью файла pyproject.toml, который следует поместить в корень вашего проекта. Ниже пример этого файла:
Например, мы можем выбрать длину строк кодов, а также установить расширения, файлы которых не должны форматироваться.
Pylint
Pylint можно установить с помощью следующей командной строки:
Чтобы оценить качество написания кода для данного скрипта, вы можете запустить:
Вы можете проверить эту страницу для получения более подробной информации о конфигурации.
Предварительные коммиты в виде хуков Git
В этой статье мы сосредоточимся на клиентских, рабочий процесс которых можно описать следующим графиком:
Настройка предварительных коммитов
Чтобы добавить действие перед фиксацией в ваш репозиторий:
2. Добавьте в файл команды bash. В нашем случае:
Первая строка применяет форматировщик black, а вторая строка применяет linting к каждому файлу python вашего проекта. Вы можете скачать файл lint.py по этой ссылке:
NB: по умолчанию установлено пороговое значение 7. Если оценка pylint ниже этого числа, фиксация завершится ошибкой, и вам придется очистить свой скрипт перед повторной фиксацией.
3. Сделайте его исполняемым, выполнив следующую команду bash:
После этого каждой фиксации вашего проекта будет предшествовать форматирование Black и linting pylint.
В качестве иллюстрации рассмотрим следующее приложение:
При фиксации нового изменения мы получаем следующие результаты:
Совместное использование linter и formatter
Теперь, когда вы настроили black в качестве средства форматирования и pylint в качестве linter, вы определенно хотите, чтобы ваша команда имела такую же конфигурацию.
Для этого вы можете использовать следующий файл bash, который будет помещен в корень вашего проекта и запущен каждым членом вашей команды после клонирования репозитория:
Заключение
10 шагов к успешному Python-проекту
Материал, перевод которого мы сегодня публикуем, посвящён инструментам, которые позволяют оснащать Python-проекты средствами форматирования кода, тестирования, непрерывной интеграции и анализа зависимостей. Это помогает ускорить процесс разработки, способствует повышению качества, единообразия и безопасности кода. Предполагается, что у читателя этого материала уже есть некоторый опыт Python-разработки и проект на Python, с которым он, в ходе чтения, будет экспериментировать. Если такого проекта у вас нет — здесь можно узнать о том, как подготовить среду разработки и создать Python-пакет. Примеры, которые будут здесь приводиться, подготовлены с использованием macOS и Python 3.7.
Шаг 1. Установка Black
Код проекта должен следовать соглашениям о стиле кода. Black — это Python-пакет, который автоматически форматирует код, приводя его внешний вид к стандарту PEP 8. Black — это сравнительно новый проект, но у него уже набралось больше миллиона загрузок. Его использование быстро стало признаком хорошего тона в Python-разработке. Вот руководство по Black.
Пока мы говорим о Black — давайте оснастим этим средством среду разработки тех, кто вместе с нами трудится над проектом. В итоге все, кто работает над проектом, будут использовать одни и те же правила форматирования кода, а в противном случае их пулл-запросы не будут приниматься.
Black, по умолчанию, устанавливает длину строки кода равной 88 символов. В некоторых руководствах по стилю, например — в Sphinx, требуется использовать длину строки, равную 79 символов. В настройках пакета Black-Atom можно задать желаемую длину строки.
Теперь, когда мы обзавелись инструментом, который поможет экономить время на форматировании кода, подумаем о том, как ускорить и упростить отправку кода в PyPI.
Когда для отправки сборок приложения в TestPyPI и PyPI используется twine, сведения для входа в систему требуется вводить вручную. Если вы не знакомы с twine — взгляните на этот материал. Сейчас мы будем автоматизировать этот процесс.
Добавим в него следующий текст:
Понятно, что сюда надо вписать ваши реальные имя пользователя и пароль. Кроме того, проверьте, чтобы этот файл был бы сохранён в домашней директории, а не в текущей рабочей директории. Если вы хотите защитить этот файл от других пользователей, вы можете, пользуясь средствами командной строки, настроить его разрешения:
Теперь ваш пакет можно загружать в TestPyPI пользуясь следующей командой:
В обычный PyPI можно загружать пакеты так:
Теперь давайте добавим в нашу среду разработки инструменты тестирования, которые позволят проверить правильность работы пакета, созданием которого мы занимаемся.
Шаг 3. Установка и настройка pytest
Pytest — это самая популярная, лёгкая в использовании библиотека для тестирования кода, написанного на Python. В этом примере мы добавим в проект простые тесты. Вот, если вас интересуют подробности о pytest, хорошее вводное руководство по этому инструменту.
Добавим сведения о pytest в файл requirements_dev.txt :
Выполним установку пакета:
Теперь выполним следующую команду, которая позволит pytest обнаружить наш пакет:
Шаг 4. Создание тестов
В файл test_notebookc.py я добавил следующий тест, который направлен на проверку того, правильное ли имя выводит функция. Модифицируйте этот код так, чтобы используемые в нём имена файлов и функций соответствовали бы вашим, опишите в нём собственные тесты.
Что здесь происходит?
В ходе теста выявлена ошибка
Рекомендовано проверять тесты на правильность, описывая их так, чтобы, в определённых условиях, они завершались бы с ошибкой. Не стоит писать тесты, которые выдают лишь сообщения зелёного цвета, так как в противном случае может оказаться так, что тесты проверяют совсем не то, для проверки чего их пишут.
После того, как мы убедились в том, что тест дал сбой — поменяем в утверждении Jall на Jill и снова запустим тестирование. Теперь оно должно завершиться успешно.
Успешное завершение теста
Теперь всё хорошо. Тест позволяет убедиться в том, что если кто-то передаёт нашей функции строку, эта строка попадёт в тот текст, который выводит эта функция.
Когда мы создавали предыдущий тест, мы писали код, который приводит к успешному завершению теста. Это называется разработкой через тестировании (Test-Driven Development, TDD). TDD — это доказавший свою ценность подход к программированию, помогающий писать код, в котором оказывается меньше ошибок, чем в нём было бы без использования TDD. Вот полезный материал по TDD.
Теперь, в качестве упражнения, попробуйте написать тест, проверяющий функцию convert() на то, чтобы при передаче в неё чего-то, отличающегося от строки, она выдавала бы ошибку, и реализуйте соответствующие механизмы этой функции. Обратите внимание на то, что целые числа, списки и словари преобразуются в строки.
После того, как пакет успешно прошёл тесты — мы готовы к тому, чтобы воспользоваться системой непрерывной интеграции.
Шаг 5. Регистрация в сервисе Travis CI и его настройка
Travis CI — это «распределённый веб-сервис для сборки и тестирования программного обеспечения». Его недавно купила компания Idera. Существуют и другие системы непрерывной интеграции, но Travis CI — это популярный, бесплатный для опенсорсного применения и хорошо документированный инструмент, поэтому мы будем пользоваться именно им.
Travis CI позволяет обеспечить интеграцию в ваш проект только того кода, который проходит тесты и соответствует стандартам. Здесь можно почитать подробности о Travis CI, а здесь — о непрерывной интеграции.
Настройка учётной записи Travis CI
Настройка сборки проекта
Сейчас пришло время настроить проект, над которым мы работаем, что даст возможность Travis выполнять сборку проекта для каждого пулл-запроса.
Строка dist: xenial нужна для того чтобы указать Travis на необходимость использования для организации виртуального окружения Ubuntu Xenial 16.04. Для тестирования кода Python 3.7 нужна именно Ubuntu Xenial, подробности об этом можно почитать здесь.
Шаг 7. Тестирование в Travis CI
Выполните коммит изменений, отправьте их на GitHub, выполните PR. Travis должен, в течение нескольких секунд, начать работу.
Вот чем занимается Travis, обрабатывая проект.
Действия, выполняемые Travis при обработке проекта
Если PR оказался неудачным — Travis об этом сообщит. Обратите внимание на то, что если пулл-запрос оказался неудачным, то можно отправить изменения в ту же ветку и Travis автоматически примется за работу.
Перейдите к странице своего репозитория на сайте Travis и осмотритесь там. Тут вы можете найти много интересного о сборках. Вероятно, в будущем вы станете частым гостем этой страницы, когда будете пытаться понять что стало причиной неудавшейся сборки.
Если же предположить, что всё прошло хорошо, если на странице находятся надписи зелёного цвета, значит проверка и сборка проекта выполнены успешно.
Сборка проекта выполнена успешно
Travis отправляет пользователям электронные письма в тех случаях, когда сборка проекта оказывается неудачной, и в тех случаях, когда это удаётся исправить.
Помните о том, что в открытый PR можно отправлять коммиты и Travis будет автоматически перезапускать процесс сборки проекта.
Теперь проанализируем наш проект на предмет покрытия кода тестами.
Шаг 8. Оценка покрытия кода тестами
Отчёт о покрытии кода тестами позволяет узнать о том, какая часть кода проекта, пусть и небольшая, протестирована. Для создания подобных отчётов мы будем пользоваться пакетом pytest-cov.
В файл requirements_dev.txt добавим следующую строку:
Выполним такую команду:
Отчёт о покрытии кода тестами
Как оказалось, весь код проекта обеспечен тестами. Таких показателей очень легко достичь в том случае, если весь проект состоит из нескольких строк кода.
Теперь поговорим о средстве, которое позволяет вести общедоступную историю состояния проекта в плане покрытия его кода тестами.
Шаг 9. Использование Coveralls
Проект Coveralls позволяет поддерживать исторические сведения о покрытии кода тестами.
Для того, чтобы воспользоваться возможностями этого проекта, нужно зарегистрироваться на сайте https://coveralls.io/, используя данные учётной записи GitHub. Потом нужно подключить репозиторий.
Теперь, когда Travis будет собирать проект, он установит необходимые пакеты, запустит тесты и создаст отчёт о покрытии кода тестами. Затем этот отчёт будет отправлен на сервис Coveralls.
Выполните коммит, отправьте код в GitHub и понаблюдайте за тем, что происходит. На то, чтобы отчёт о покрытии кода тестами попал бы в Coveralls, может потребоваться несколько минут.
Обработка проекта, отчёт о покрытии кода тестами
Теперь среди проверок PR присутствует и проверка, выполняемая средствами Coveralls.
На странице Coveralls можно убедиться в том, что проект покрыт тестами на 100%.
Сведения о покрытии кода тестами
Теперь давайте оснастим наш проект ещё одним полезным инструментом.
Шаг 10. Работа с PyUp
Вот как выглядят сведения о пакетах, некоторые из которых устарели, на сайте PyUp.io.
Сведения о пакетах
Пользуясь этим сервисом, вы всегда будете знать о том, когда выходят свежие версии используемых вами пакетов. Знание, как говорится, есть половина победы. А вторая половина — это, очевидно, автоматические пулл-запросы на обновление зависимостей.
Итоги
Из этого материала вы узнали о том, как пользоваться при разработке Python-проектов такими средствами, как Black, pytest, Travis CI, Coveralls и PyUp. Они помогают контролировать зависимости проектов, форматировать и тестировать код, проверять и собирать проекты. Надеемся, вам эти инструменты пригодятся.
Уважаемые читатели! Какими инструментами вы пользуетесь при разработке Python-проектов?
Black python что это
The Uncompromising Code Formatter
Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.
Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.
Black makes code review faster by producing the smallest diffs possible.
Try it out now using the Black Playground. Watch the PyCon 2019 talk to learn more.
Installation and usage
If you can’t wait for the latest hotness and want to install from GitHub, use:
pip install git+git://github.com/psf/black
To get started right away with sensible defaults:
You can run Black as a package if running it as a script doesn’t work:
Further information can be found in our docs:
NOTE: This is a beta product
Black is already successfully used by many projects, small and big. Black has a comprehensive test suite, with efficient parallel tests, and our own auto formatting and parallel Continuous Integration runner. However, Black is still beta. Things will probably be wonky for a while. This is made explicit by the «Beta» trove classifier, as well as by the «b» in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.
The Black code style
Black is a PEP 8 compliant opinionated formatter. Black reformats entire files in place. Style configuration options are deliberately limited and rarely added. It doesn’t take previous formatting into account (see Pragmatism for exceptions).
Our documentation covers the current Black code style, but planned changes to it are also documented. They’re both worth taking a look:
Please refer to this document before submitting an issue. What seems like a bug might be intended behaviour.
Early versions of Black used to be absolutist in some respects. They took after its initial author. This was fine at the time as it made the implementation simpler and there were not many users anyway. Not many edge cases were reported. As a mature tool, Black does make some exceptions to rules it otherwise holds.
Please refer to this document before submitting an issue just like with the document above. What seems like a bug might be intended behaviour.
You can find more details in our documentation:
And if you’re looking for more general configuration documentation:
Pro-tip: If you’re asking yourself «Do I need to configure anything?» the answer is «No». Black is all about sensible defaults. Applying those defaults will have your code in compliance with many other Black formatted projects.
The following notable open-source projects trust Black with enforcing a consistent code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, Kedro, and many more.
The following organizations use Black: Facebook, Dropbox, KeepTruckin, Mozilla, Quora, Duolingo, QuantumBlack, Tesla.
Are we missing anyone? Let us know.
I can’t think of any single tool in my entire programming career that has given me a bigger productivity increase by its introduction. I can now do refactorings in about 1% of the keystrokes that it would have taken me previously when we had no way for code to format itself.
Dusty Phillips, writer:
Black is opinionated so you don’t have to be.
An auto-formatter that doesn’t suck is all I want for Xmas!
Carl Meyer, Django core developer:
Kenneth Reitz, creator of requests and pipenv :
This vastly improves the formatting of our code. Thanks a ton!
Use the badge in your project’s README.md:
Using the badge in README.rst:
