Какую команду нужно запустить чтобы отформатировать этот файл в соответствии с рекомендациями pep8

Обновлено: 04.07.2024

В сообществе Python ещё лет 20 назад осознали ценность форматирования кода, когда на свет появился PEP8 — документ, который призван сделать весь код, написанный на Python, оформленным одинаково и поставить точку в бесконечных спорах о стиле оформления кода. PEP8 и правда глубоко вошёл в идеологию Python. Писать код, который нарушает PEP8 — это считается очень плохой практикой. Это одна из первых заповедей, про которые говорят начинающим питонистам.

Почему же консистентный стиль оформления кода так важен, что этому посвящен целый PEP? Самая главная мысль — читаемость важна. Вот какие ещё мысли у меня возникают по поводу стиля оформления кода.

Следование PEP8 можно автоматически контролировать при помощи таких инструментов, как flake8 или pylint, но тогда форматировать код придётся вручную. Как мы уже выяснили, время разработчика стоит дорого. Можно ли как-то автоматизировать этот процесс?

Кроме того, PEP8 описывает лишь основные правила оформления кода, но оставляет свободу интерпретации во множестве краевых случаев, из-за чего может появиться неконсистентность оформления. Есть ли какие-нибудь более строгие конвенции, чем PEP8?

Почему бескомпромиссный? Потому что black навязывает свой стиль кода, и его практически нельзя конфигурировать. Возможно, вам пока что так не кажется, но это огромный плюс black .

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

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

У меня был опыт попытки выработать в команде конвенцию, и это не так просто. Не потому что люди плохие или упрямые, просто у каждого своё понимание красоты и удобства. Наверняка, начнётся борьба вкусов и мнений. black избавляет от всех этих обсуждений — есть готовый стиль оформления кода, где все решения уже приняты за вас.

Да, иногда black выдаёт не самый красивый код, но, если подумать, красота кода не так важна, как консистентность, последовательность, одинаковость. black осознанно приносит красоту в жертву консистентности.

Скажу по собственному опыту, что к отформатированному black коду привыкаешь очень быстро, и буквально через несколько дней просто перестаешь замечать форматирование вообще. Просто читаешь код.

Установка

К сожалению, на момент написания этого поста, black не имеет стабильных релизов, пока что есть только бета-версии. Смею вас заверить, что black даже в бета-версии уже достаточно стабилен и используется в куче серьезных проектов. Правда, отсутствие стабильных релизов немного усложняет установку.

black устанавливается из PyPI. Давайте выясним, какая на данный момент последняя доступная версия при помощи следующего трюка (или можно просто её посмотреть на странице проекта на PyPI):

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

Внутри виртуального окружения нужно выполнить, заменив версию на последнюю:

А если вы используете pipenv или poetry , то вот так:

Обратите внимание, что при установке black через pipenv обязательно нужно указывать конкретную версию. Я описал, что произойдёт, если этого не сделать, а взамен разрешить pipenv устанавливать пре-релизные версии в посте про pipenv .

Использование

black имеет очень интуитивный интерфейс командной строки.

Вот так можно отформатировать все файлы в текущей директории (и рекурсивно в поддиректориях):

И это практически единственная команда, которую вам нужно запомнить.

А вот так можно отформатировать один конкретный файл:

Интеграция с редактором/IDE

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

Использование в CI

А ещё нужно настроить запуск black в сервисе для непрерывной интеграции (CI), например, GitHub Actions, GitLab CI или Travis CI. Так black сможет блокировать пулл-реквесты (или мердж-реквесты), в которых содержится неотформатированный код.

В режиме “проверки” black не будет форматировать файлы, а просто напечатает список неотформатированных файлов и завершится кодом ошибки, что должно “уронить” всю проверку целиком.

Конфигурация

Кое-какую минимальную возможность настройки black все-таки предоставляет. Стоит отметить, что в большинстве случаев этого делать не придётся, потому что у black достаточно разумные настройки по умолчанию.

Вот так можно настроить максимальную длину строки и файлы, которые форматировать не нужно. В pyproject.toml в корне проекта добавьте:

Настройка flake8 , чтобы он не противоречил black

У flake8 своё мнение по поводу того, как должен быть отформатирован код, которое не всегда совпадает с мнением black . Чтобы не возникало конфликтов, рекомендуется выключить некоторые проверки flake8 , по примеру того, как это сделано в репозитории black .

Что меня бесит в стиле black

Есть некоторые моменты, с которыми я категорически несогласен. Думаю, рассказать про них тоже нужно.

Рассмотрим пример исходного кода:

Я специально сделал побольше аргументов в функцию print() , чтобы вызов функции стал достаточно длинным, чтобы black разнёс его на несколько строк. Обратите внимание на тернарный оператор. Теперь отформатируем и посмотрим на результат:

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

Эта функция имеет два аргумента — булевый и строковый. Отформатируем:

black опять не помог сделать код читаемее. Выглядит так, будто функция имеет три аргумента, хотя на самом деле их только два. Нужно хорошо присмотреться, чтобы заметить отсутствие запятой. Поставим скобки вручную и отформатируем ещё раз:

Стало в сто раз лучше. Теперь всё очевидно.

Надеюсь, что когда-нибудь эту шероховатость починят, а до тех пор я просто вручную ставлю скобки вокруг вот такого некрасивого кода. Такое случается не так уж часто. В целом, даже почти не больно.

Консистентное форматирование кода — это невероятно важно, потому что упрощает восприятие кода другими людьми (или самим же автором кода, но через полгода). Автоматическое форматирование кода (почти) не требует вообще никаких усилий со стороны автора.

Хоть black и имеет свои недостатки, он всё равно явно окупает усилия, затраченные на ручную расстановку скобок, потому что случается это довольно редко. Как и любой инструмент, black дорабатывается, и будем верить, что все проблемы рано или поздно исправят.

black , наряду с flake8 и pytest , попал в мой набор незаменимых инструментов, которые я пытаюсь использовать во всех своих проектах. И вам рекомендую.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

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

О читаемости и пойдет речь, а точнее как ее увеличить.

Проблемы форматирования

Идеального форматирования кода не существует. Для каждого языка стоит подстраиваться под общепринятые правила оформления кода. Да что говорить, если среди новичков С++ еще до сих пор войны по поводу ставить скобки на следующей строке или нет.
Для python'а основными проблемами форматирования является «C стиль». Не редко в рассматриваемый язык приходят из С-подобных языков, а для них свойственно писать с символами ")(;".
Символы не единственная проблема, есть еще и проблема избыточности написания конструкций. Питон, в отличие от Java, менее многословен и чтобы к этому привыкнуть у новичков уходит большое количество времени.
Это две основные проблемы, которые встречаются чаще всего.

Стандарты и рекомендации к оформлению

Если для повышения скорости исполнения кода можно использовать разные подходы, хотя эти подходы очень индивидуальны, то для форматирования текста существует прям slyle guide — это pep8. Далее его буду называть «стандарт».
Почитать про стандарт можно здесь, на русском языке можно здесь
Pep8 весьма обширный и позволяет программисту писать РЕАЛЬНО читаемый код.

максимальную длину строк кода и документации
кодировки файлов с исходным кодом
рекомендации как правильно оформлять комментарии
соглашения именования функций/классов, аргументов
и многое другое

Автоматизируем форматирование

Если посмотреть сколько всяких правил в pep8, то можно сесть за рефакторинг надолго. Вот только это лениво, да и при написании нового кода сиравно будут какие-то ошибки правил. Для этого рассмотрим как же себе можно упростить жизнь.

Дабы иметь представление сколько ошибок оформления в коде, стоит использовать утилиту pep8.
У нее достаточный список параметров, который позволяет рекурсивно просмотреть все файлы в папках на предмет соответствия стандарту pep8.
Вывод утилиты примерно такой:

По нему можно однозначно понять: где ошибка и что случилось.

autopep8

Ошибки стандарта часто повторяются от файла в файлу. И возникает сильное желание исправление автоматизировать. В этом случае на арену выходит autopep8.
Как и pep8, он умеет самостоятельно определять ошибки, а также исправлять их. Список исправляемых ошибок форматирования можно найти здесь
Само использование autopep8 крайне простое и может выглядеть так:

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

autoflake

Можно пойти дальше и в качестве оружия взять autoflake. Эта утилита помогает удалить не используемые импорты и переменные.
Используется примерно так:

Тем самым будут рекурсивно почищены файлы в директории.

unify

Крайний, заключительный момент в редактировании кода — это строки. Кто-то любит их писать в одиночных апострофах, кто-то в двойных. Вот только и для этого существует рекомендации, а также и утилита, которая позволяет автоматически приводить в соответствие — unify
Использование:

Как и везде, утилита выполнит свое грязное дело рекурсивно для файлов в папке.

docformatter

Все время говорим о самом коде, а о комментариях еще ни разу не шло речи. Настало время — docformatter. Эта утилита помогает привести ваши docstring по соглашению PEP 257. Соглашение предписывает как следует оформлять документацию.
Использование утилиты ничуть не сложнее предыдущих:

А все вместе можно?

Выше описаны утилиты, их запуск можно добавить какой-нибудь bash скрипт под магическим названием clean.bash и запускать. А можно пойти и по другому пути и использовать wrapper над этими утилитами — pyformat

Выводы

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

Что такое PEP в Python?

Адаптивный красивый стиль кодирования делает код более читабельным. Код становится простым для конечного пользователя.

Почему важен PEP 8?

PEP 8 улучшает читаемость кода Python, но почему читаемость так важна? Давайте разберемся с этой концепцией.

Создатель Python Гвидо ван Россум сказал, что код может быть написан за несколько минут, несколько часов или целый день, но как только мы напишем код, мы больше никогда его не переписываем. Но иногда нам нужно читать код снова и снова.

На этом этапе мы должны иметь представление о том, почему мы написали конкретную строку в коде. Код должен отражать значение каждой строки. Вот почему так важна удобочитаемость.

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

Условные обозначения

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

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

Одна строчная буква

Одна заглавная буква

Строчные буквы с подчеркиванием

ВЕРХНИЙ РЕГИСТР С ПОДЧЕРКИВАНИЕМ

Заглавные слова(или CamelCase)

Стили имен

Ниже приведена таблица, в которой указаны некоторые из распространенных стилей именования в Python. Рассмотрим следующую таблицу.

Тип	Соглашение об именовании	Примеры
Функция	Мы должны использовать слова в нижнем регистре или разделять слова подчеркиванием.	myfunction, my_function
Переменная	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость.	a, var, variable_name
Класс	Первая буква названия класса должна быть заглавной; используйте camel case. Не разделяйте слова подчеркиванием.	MyClass, Form, Model
Метод	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость.	class_method, method
Константа	Использование заглавных букв, слов или отдельных слов для повышения удобочитаемости.	MYCONSTANT, CONSTANT, MY_CONSTANT
Модуль	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость.	Module_name.py, module.py
Пакет	Мы должны использовать строчные буквы, слова или отдельные слова, чтобы улучшить читаемость. Не разделяйте слова подчеркиванием.	package, mypackage

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

Макет кода

Макет кода определяет, насколько код читается. В этом разделе мы узнаем, как использовать пробелы для улучшения читаемости кода.

Отступ

В приведенном выше примере оператор печати с отступом будет выполнен, если условие оператора if истинно. Этот отступ определяет блок кода и сообщает нам, какие операторы выполняются при вызове функции или триггере условия.

Вкладки против пробела

Мы также можем использовать вкладки, чтобы предоставить последовательные пробелы, чтобы указать отступ, но пробелы являются наиболее предпочтительными. Python 2 позволяет смешивать табуляции и пробелы, но мы получим ошибку в Python 3.

Отступ после разрыва строки

Для продолжения строки важно использовать отступ, чтобы длина строки не превышала 79 символов. Это обеспечивает гибкость определения между двумя строками кода и одной строкой кода, которая расширяет две строки.

Мы можем использовать следующую структуру.

Использование документационной строки

Должна ли линия разрываться до или после бинарного оператора?

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

Python позволяет нам разбивать строку до или после бинарного оператора, если соглашение согласовано локально.

Модуль импорта

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

Мы также можем использовать следующий подход.

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

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

Пустые строки

Пустые строки могут улучшить читаемость кода Python. Если много строк кода сгруппированы вместе, код станет труднее читать. Мы можем удалить это, используя множество пустых вертикальных линий, и читателю может потребоваться прокрутить больше, чем необходимо. Следуйте приведенным ниже инструкциям, чтобы добавить вертикальный пробел.

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

Закрывающие скобки

Мы можем разбивать строки внутри круглых скобок, используя продолжения строки. PEP 8 позволяет нам использовать закрывающие фигурные скобки в подразумеваемых продолжениях строк. Давайте разберемся в следующем примере.

Совместите закрывающую скобку с первым непробельным символом.

Совместите закрывающие фигурные скобки с первым символом строки.

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

Комментарии являются неотъемлемой частью любого языка программирования. Это лучший способ объяснить код. Когда мы задокументировали наш код с соответствующими комментариями, каждый сможет понять код. Но следует помнить о следующих моментах.

Начните с заглавной буквы и напишите полное предложение.
Обновите комментарий в случае изменения кода.
Ограничьте длину строки комментариев и строк документации 72 символами.

Блочный комментарий

PEP 8 предоставляет следующие правила для записи блока комментариев.

Посмотрим на следующий код.

Мы можем использовать больше абзаца для технического кода.

Встроенные комментарии

Встроенные комментарии используются для объяснения одного оператора в фрагменте кода. Мы можем быстро понять, почему мы написали именно эту строку кода. PEP 8 определяет следующие правила для встроенных комментариев.

Ниже приведен пример встроенных комментариев.

Иногда мы можем использовать соглашение об именах, чтобы заменить встроенный комментарий.

Мы можем использовать следующее соглашение об именах.

Встроенные комментарии необходимы, но блочные комментарии делают код более читабельным.

Излишнее добавление пробелов

В некоторых случаях использование пробелов может затруднить чтение кода. Слишком много пробелов может сделать код слишком разреженным и трудным для понимания. Не следует добавлять пробелы в конце строки. Это известно как завершающие пробелы.

Посмотрим на следующий пример.

Заключение

PEP 8, иногда обозначаемый PEP8 или PEP-8, представляет собой документ, содержащий рекомендации по написанию кода на Python. Он был составлен в 2001 году Гвидо ван Россумом, Барри Варшавой и Ником Когланом. Основная цель PEP 8 – улучшить читабельность и логичность кода на Python.

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

Из данной серии статей вы узнаете:

как писать Python-код, соответствующий PEP8;
какие доводы лежат в основе рекомендаций, изложенных в PEP8;
как настроить среду разработки так, чтобы вы могли начать писать код на Python по PEP8.

Зачем нужен PEP 8

“Читаемость имеет значение”, — Дзен Python

PEP 8 существует для улучшения читаемости кода Python. Но почему так важна удобочитаемость? Почему написание читаемого кода является одним из руководящих принципов языка Python?

Как сказал Гвидо ван Россум: «Код читают гораздо чаще, чем пишут». Вы можете потратить несколько минут или целый день на написание фрагмента кода для аутентификации пользователя. В дальнейшем вам не придётся его писать. Но перечитывать его вы точно будете. Этот фрагмент кода может остаться частью проекта, над которым вы работаете. Каждый раз, возвращаясь к этому файлу, вам нужно будет вспомнить, что делает этот код и зачем вы его написали. Поэтому удобочитаемость имеет большое значение.

Если вы новичок в Python, возможно, вам уже через несколько дней или недель будет трудно вспомнить, что делает фрагмент кода. Но если вы следуете PEP 8, вы можете быть уверены, что правильно назвали свои переменные . Вы будете знать, что добавили достаточно пробелов, чтобы обособить логические шаги. Вы также снабдили свой код отличными комментариями. Все это сделает ваш код будет более читабельным, а значит, к нему будет легче вернуться. Следование правилам PEP 8 для новичка может сделать изучение Python гораздо более приятной задачей.

Следование PEP 8 особенно важно, если вы претендуете на должность разработчика. Написание понятного, читаемого кода свидетельствует о профессионализме. Это скажет работодателю, что вы понимаете, как правильно структурировать свой код.

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

Марк Лутц «Изучаем Python»

Скачивайте книгу у нас в телеграм

Когда стоит игнорировать PEP 8

Краткий ответ на этот вопрос – никогда. Если вы строго следуете PEP 8, то можете гарантировать, что у вас будет чистый, профессиональный и читабельный код. Это принесет пользу вам, а также сотрудникам и потенциальным работодателям.

Однако некоторые рекомендации в PEP 8 неудобны в следующих случаях:

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

Как проверить соответствие кода PEP 8

Чтобы убедиться, что ваш код соответствует PEP 8, необходимо многое проверить. Помнить все эти правила при разработке кода может быть непросто. Особенно много времени уходит на приведение прошлых проектов к стандарту PEP 8. К счастью, есть инструменты, которые помогут ускорить этот процесс.

Существует два класса инструментов, которые можно использовать для обеспечения соответствия PEP 8: линтеры и автоформаттеры.

Линтеры

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

Вот пара лучших линтеров для кода на Python:

pycodestyle

Это инструмент для проверки вашего кода на соответствие некоторым стилевым соглашениям в PEP8.

Установите pycodestyle с помощью pip:

Вы можете запустить pycodestyle из терминала, используя следующую команду:

flake8

Это инструмент, который сочетает в себе отладчик, pyflakes и pycodestyle.

Установите flake8 с помощью pip:

Запустите flake8 из терминала, используя следующую команду:

Замечание: Дополнительная строка в выводе указывает на синтаксическую ошибку.

Автоформаттеры

Установите black с помощью pip. Для запуска требуется Python 3.6+:

Его можно запустить из командной строки, как и в случае с линтерами. Допустим, вы начали со следующего кода, который не соответствует PEP 8, в файле с именем code.py:

Затем вы можете запустить следующую команду через командную строку:

code.py будет автоматически приведён к следующему виду:

Если вы хотите изменить ограничение длины строки, можно использовать флаг --line-length :

Работа двух других автоформаттеров – autopep8 и yapf – аналогична работе black .

О том, как использовать эти инструменты, хорошо написано в статье Python Code Quality: Tools & Best Practices Александра ван Тол.

AutopepEP8 является инструментом, который использует Python кода автоматической версии стиля PEP8. Вы можете использовать AutoPEP8 непосредственно в PyCharm.

1. Введение в Autopep8

Мы должны понимать, прежде чем использовать AutoPep8PEP 8 – Style Guide for Python Code

Во-вторых, установить и использовать AutoPEP8

AutoPEP8 является открытым исходным кодом команды средство командной строки, которая автоматически форматирует код Python в стиле PEP8. AutoPEP8 использует инструмент Pycodestyle, чтобы определить, какую часть потребностей коды для форматирования, который фиксирует типографские проблемы, сообщенные в большинстве инструментов Pycodestyle. Сам AutoPep8 также инструмент, написанный на языке Python, поэтому мы можем использовать PIP для установки непосредственно:

Давайте возьмем полный пример, код, используемый в данном примере выглядит следующим образом:

Есть три проблемы в этом коде:

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

Далее, мы проверим этот код, используя PycodesTyple, а затем форматировать код в код типа PEP 8, используя AutoPep8.

Используйте код проверки Pycodestyle обнаружить, что есть три места в коде, которые не соответствуют спецификациям PEP 8, как показано ниже:

Используйте формат autopep8 для преобразования кода Python. В этом примере, AutoPep8 успешно помогла нам решить все вопросы следующим образом:

Если вы посмотрите на исходный файл в это время, он будет найден такой же, как и она не фиксирована к коду, который соответствует спецификации PEP 8. Как упоминалось ранее, не указать опцию в-месте, только выводит результат в командной строке. Если мы используем опцию в-место, то не будет никакого вывода, и AutoPep8 будет напрямую модифицировать исходный файл.

В-третьих, PyCharm Установить AutoPEP8

PyCharm Установка AutoPEP8

PIP Установка autopephot 8: Пип Установить Autopep8

PyCharm -> Настройки -> Инструменты -> ПРОДЛЕВАЕТ TOOLS -> Нажмите + Plus

Name: autopep8
Tools settings:

Programs: autopep8
Parameters: --in-place --aggressive --aggressive $FilePath$
Working directory: $ProjectFileDir$
Advanced Options -> Output Filters: $FILE_PATH$\:$LINE$\:$COLUMN$\:.*

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