PEP 8 - руководство по написанию кода на Python

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

Руководствуясь советами Гвидо ван Россума и дополнениями от Барри, был создан PEP 8. В случае возникновения разногласий, предпочтение отдавалось стилю Гвидо. Следует отметить, что данное руководство может быть неполным и, вероятно, никогда не будет завершено.

Основная мысль Гвидо заключается в том, что код должен быть прочитан гораздо чаще, чем записан. Поэтому рекомендации по стилю кодирования направлены на улучшение его читаемости и обеспечение согласованности между различными проектами. Идеально, если весь код будет написан в одном стиле, что позволит любому легко его понять.

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

Есть две основные причины, по которым можно нарушить эти правила:

Внешний вид кода

Отступы

Для создания отступов на каждом уровне используйте 4 пробела.

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

Верно:

# Выровнено по открывающему разделителю foo = long_function_name(var_one, var_two, var_three, var_four)
# Больше отступов включено для отличения его от остальных def long_function_name( var_one, var_two, var_three, var_four): print(var_one)

Не верно:

# Аргументы на первой линии запрещены, если не используется вертикальное выравнивание foo = long_function_name(var_one, var_two, var_three, var_four)
# Больше отступов требуется, для отличения его от остальных def long_function_name( var_one, var_two, var_three, var_four): print(var_one)

По желанию:

# Нет необходимости в большем количестве отступов. foo = long_function_name( var_one, var_two, var_three, var_four)

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

my_list = [ 1, 2, 3, 4, 5, 6, ]

result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )

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

my_list = [ 1, 2, 3, 4, 5, 6, ]

result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f', )

Табуляция или пробелы?

Использование пробелов является наиболее предпочтительным способом создания отступов.

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

В Python 3 запрещено комбинировать табуляцию и пробелы в отступах.

Python 2 пытается заменить табуляцию на пробелы.

При запуске интерпретатора Python 2 в командной строке с опцией -t, будут выводиться предупреждения о смешанном стиле отступов, а если использовать опцию -tt, то в этих местах будут возникать ошибки. Рекомендуется использовать эти параметры для более чистого кода!

Максимальная длина строки

Сократите количество символов в строке до 79 символов.

Для текстовых блоков большей длины с менее строгими ограничениями по структуре (например, документация или комментарии), рекомендуется ограничивать длину строки до 72 символов.

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

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

Python стандартная библиотека считается консервативной и предпочитает ограничивать длину строки до 79 символов (а для строк документации/комментариев - до 72).

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

Иногда обратная косая черта все еще может быть полезна. Например, длинная конструкция с оператором "with" не допускает неявных продолжений, поэтому использование обратной косой черты в этом случае является допустимым:

with open('/path/to/some/file/you/want/to/read') as file_1, \
open('/path/to/some/file/being/written', 'w') as file_2: file_2.write(file_1.read())

Еще один пример - утверждение.

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

class Rectangle(Blob):
def __init__(self, width, height, color='black', emphasis=None, highlight=0):

if (width == 0 and height == 0 and color == 'red' and emphasis == 'strong' or highlight > 100): raise ValueError("sorry, you lose")

if width == 0 and height == 0 and (color == 'red' or emphasis is None):

raise ValueError("I don't think so -- values are %s, %s" % (width, height)) Blob.__init__(self, width, height, color, emphasis, highlight)

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

Рекомендуется разделять функции верхнего уровня и определения классов двумя пустыми строками.

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

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

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

Python интерпретирует символ control+L как пробельный символ (whitespace), поэтому его можно использовать, поскольку многие текстовые редакторы воспринимают его как разрыв страницы, что позволяет логически разделять части файла на разные страницы. Однако не все редакторы корректно обрабатывают control+L и могут отображать другой символ вместо него.

Кодировка исходного файла

Для Python необходимо использовать кодировку UTF-8 (для Python 2 - ASCII).

Необходимо избегать указания кодировки в файлах в ASCII (Python 2) или UTF-8 (Python 3).

В обычной библиотеке, нестандартные кодировки следует применять только для тестирования или в случае, если необходимо упомянуть автора, имя которого содержит не ASCII символы, в комментариях или документации; в остальных ситуациях наиболее предпочтительным способом является использование \x, \u, \U или \N для включения не ASCII символов в строковые литералы.

С начала версии python 3.0 в стандартной библиотеке действует следующее правило: все идентификаторы должны содержать только ASCII символы и представлять английские слова везде, где это возможно (во многих случаях используются сокращения или неанглийские технические термины). Кроме того, строки и комментарии также должны содержать только ASCII символы. Исключения составляют: (а) тестовый случай, проверяющий не-ASCII особенности программы, и (б) имена авторов. Авторы, у которых имена основаны не на латинском алфавите, должны транслитерировать свои имена на латиницу.

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

Импорты

Пробелы в выражениях и инструкциях

Избегайте использования пробелов в следующих ситуациях:

Другие рекомендации

Комментарии

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

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

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

После точки в конце предложения рекомендуется ставить два пробела.

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

Блоки комментариев

Обычно блок комментариев используется для пояснения кода (целиком или только его части), который идет после блока. Важно, чтобы комментарии имели такой же отступ, как и сам код. Каждая строка в блоке комментариев должна начинаться с символа # и иметь один пробел после него (если только текст комментария не имеет своего отступа).

Для разделения абзацев внутри блока комментариев используется строка, содержащая символ #.

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

Постарайтесь минимизировать использование таких высказываний.

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

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

x = x + 1 # Increment x

Однако, иногда бывает полезно услышать подобные отзывы:

x = x + 1 # Компенсация границы

Строки документации

Контроль версий

Если вам требуется внедрить Subversion, CVS или RCS в ваш проект, следуйте этим инструкциям:

__version__ = "$Revision: 1a40d4eaa00b $" # $Source$

Размещайте данные строки после описания модуля перед любым другим кодом и разделяйте их пустыми строками по одной до и после.

Соглашения по именованию

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

Главный принцип

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

Описание: Стили имен

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

Обычно выделяют следующие виды стилей:

Существует также стиль, при котором имена, относящиеся к одной группе, имеют общий короткий префикс. В Python этот стиль используется редко, но мы упоминаем его для полноты. Например, функция os.stat() возвращает кортеж, где имена обычно выглядят как st_mode, st_size, st_mtime и так далее. Это сделано для подчеркивания соответствия этих полей структуре системных вызовов POSIX, что помогает программистам, знакомым с этой структурой.

В библиотеке X11 принято использовать префикс Х для всех открытых функций. В языке программирования Python такой подход считается излишним, так как перед полями и методами уже указано имя объекта, а перед функциями - имя модуля.

Кроме этого, применяются следующие специфические способы записи имен с использованием символа подчеркивания в начале или конце имени:

Предписания: соглашения по именованию

Имена, которых следует избегать

Избегайте использования символов l (маленькая латинская буква «эль»), O (заглавная латинская буква «о») или I (заглавная латинская буква «ай») в качестве однобуквенных идентификаторов.

В некоторых шрифтах эти символы могут быть спутаны с цифрами один и ноль. Если необходимо использовать символ "l", рекомендуется писать заглавную букву "L" вместо нее.

Имена модулей и пакетов

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

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

Если модуль расширения написан на языках программирования С или C++, и имеет сопутствующий модуль на python (с интерфейсом высокого уровня), то название С/С++ модуля начинается с символа подчеркивания, например, _socket.

Имена классов

Обычно имена классов должны соответствовать соглашению CapWords.

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

Важно отметить, что существуют отдельные правила по именованию встроенных объектов: большинство встроенных объектов имеют одно слово (или два слова, написанных слитно), в то время как правило CapWords применяется только к именам исключений и встроенных констант.

Имена исключений

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

Имена глобальных переменных

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

Для того чтобы избежать экспортирования глобальных переменных в модулях, которые предназначены для использования с помощью from M import *, можно использовать механизм __all__. Также возможно придерживаться старого соглашения и добавлять перед именами глобальных переменных один символ подчеркивания. Этот символ можно использовать для обозначения тех глобальных переменных, которые используются только внутри модуля.

Имена функций

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

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

Аргументы функций и методов

Всегда рекомендуется использовать self в качестве первого аргумента метода экземпляра объекта.

Всегда следует использовать cls в качестве первого параметра при определении метода класса.

Если название параметра пересекается с ключевым словом Python, то рекомендуется добавить символ подчеркивания в конце имени, вместо искажения написания слова или использования аббревиатуры. Таким образом, class_ предпочтительнее, чем clss. (Возможно, стоит подумать о выборе синонима).

Имена методов и переменных экземпляров классов

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

Для обозначения непубличных методов и атрибутов используйте один символ подчёркивания перед именем.

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

Python изменяет эти имена: если у класса Foo есть атрибут с именем __a, то он не будет доступен как Foo.__a. (Однако опытный пользователь все равно сможет получить доступ, обратившись к Foo._Foo__a.) В общем, двойное подчеркивание следует использовать лишь для предотвращения конфликтов имен с атрибутами классов, предназначенными для наследования.

Отметим, что возникают некоторые разногласия относительно использования __ имена (см. ниже).

Константы

Обычно константы объявляются на уровне модуля и записываются только заглавными буквами, при этом слова разделяются символами подчеркивания. Например: MAX_OVERFLOW, TOTAL.

Проектирование наследования

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

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

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

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

Давайте теперь составим список рекомендаций:

Общие рекомендации