PEP8 Рекомендации Python

Этот документ содержит соглашения по кодированию для кода Python, входящего в стандартную библиотеку в основном дистрибутиве Python. Пожалуйста, ознакомьтесь с сопутствующим информационным PEP, описывающим стилевые рекомендации для кода C в C-реализации Python .

Введение

Этот документ содержит соглашения по кодированию для кода Python, входящего в стандартную библиотеку основной дистрибуции Python. Пожалуйста, ознакомьтесь с сопутствующим информационным PEP, описывающим стилевые руководящие принципы для кода C в C-реализации Python.

Этот документ и PEP 257 (Соглашения по Docstring) были адаптированы из оригинального эссе по стилю написания кода Python от Гвидо, с некоторыми дополнениями из стиля Барри .

Глупая последовательность — это домовой маленьких умов

Один из ключевых выводов Гвидо заключается в том, что код читается гораздо чаще, чем он пишется. Рекомендации, представленные здесь, предназначены для улучшения читаемости кода и обеспечения его согласованности в широком спектре кода на Python. Как говорится в PEP 20, «читаемость имеет значение».

Руководство по стилю касается согласованности. Согласованность с этим руководством по стилю важна. Согласованность в рамках проекта еще более важна. Согласованность в пределах одного модуля или функции является наиболее важной.

Но самое главное: знать, когда быть несогласованным — иногда руководство по стилю просто не применимо. Если есть сомнения, используйте свое лучшее суждение. Посмотрите на другие примеры и решите, что выглядит лучше. И не стесняйтесь спросить!

Два хороших основания для нарушения определенного правила:

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

Расположение кода

Отступы

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

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

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

Да:


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 — это использование только пробелов. Второй по популярности способ — это использование только табуляции. Код, отформатированный с использованием смеси табуляции и пробелов, должен быть преобразован в использование только пробелов. При вызове интерпретатора командной строки Python с опцией -t, он выдает предупреждения о коде, который незаконно смешивает табуляцию и пробелы. При использовании -tt эти предупреждения становятся ошибками. Эти опции настоятельно рекомендуются!

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

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

Ограничьте все строки максимальной длиной в 79 символов.

Во многих устройствах все еще используются строки длиной 80 символов; плюс, ограничение окон в 80 символов позволяет иметь несколько окон рядом. Автоматическое перенос строк на таких устройствах нарушает визуальную структуру кода, что делает его сложнее для понимания. Поэтому, пожалуйста, ограничьте все строки максимальной длиной в 79 символов. Для длинных блоков текста (документации или комментариев), рекомендуется ограничить длину до 72 символов.

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

Обратные слэши могут быть все еще полезны в некоторых случаях. Например, длинные, множественные операторы 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())

Другой такой случай — операторы assert.

Убедитесь, что правильно отформатировали продолженную строку. Предпочтительное место для переноса вокруг бинарного оператора — после оператора, а не перед ним. Некоторые примеры:

class Rectangle(Blob):

    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if (width <mark> 0 and height </mark> 0 and
            color <mark> 'red' and emphasis </mark> 'strong' or
            highlight > 100):
            raise ValueError("sorry, you lose")
        if width <mark> 0 and height </mark> 0 and (color == 'red' or
                                           emphasis is None):
            raise ValueError("I don't think so -- values are %s, %s" <

### Отступы


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


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


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


Да:

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 — это использование только пробелов. Второй по популярности способ — это использование только табов. Код, в котором смешаны табы и пробелы, должен быть преобразован в использование только пробелов. При вызове интерпретатора командной строки Python с опцией `-t`, он выдает предупреждения о коде, который незаконно смешивает табы и пробелы. При использовании `-tt` эти предупреждения становятся ошибками. Эти опции настоятельно рекомендуются!


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




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


Ограничьте длину всех строк максимум 79 символами.


Во многих устройствах все еще ограничена длина строк в 80 символов; кроме того, ограничение окон до 80 символов позволяет размещать несколько окон рядом. Стандартное перенос на таких устройствах нарушает визуальную структуру кода, что затрудняет его понимание. Поэтому, пожалуйста, ограничьте длину всех строк максимум 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())



Другой такой случай — это операторы `assert`.


Убедитесь, что продолженная строка правильно отступлена. Предпочтительное место для переноса вокруг бинарного оператора — *после* оператора, а не перед ним. Вот несколько примеров:

class Rectangle(Blob):

def __init__(self, width, height,
             color='black', emphasis=None, highlight=0):
    if (width <mark> 0 and height </mark> 0 and
        color <mark> 'red' and emphasis </mark> 'strong' or
        highlight > 100):
        raise ValueError("sorry, you lose")
    if width <mark> 0 and height </mark> 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 принимает символ подачи страницы в виде управляющего символа (т.е. ^L) как
пробел; Многие инструменты рассматривают эти символы как разделители страниц, поэтому
вы можете использовать их для разделения страниц связанных разделов вашего файла.
Обратите внимание, что некоторые редакторы и веб-основанные средства просмотра кода могут не распознавать
управляющий символ ^L как подачу страницы и могут отображать другой глиф на его месте.




### Кодировки (PEP 263)


Код в основном дистрибутиве Python должен всегда использовать кодировку ASCII или
Latin-1 (также известную как ISO-8859-1). Для Python 3.0 и далее,
UTF-8 предпочтительнее Latin-1, см. PEP 3120.


Файлы, использующие ASCII, не должны иметь куки кодировки. Latin-1 (или UTF-8)
должны использоваться только тогда, когда комментарий или строка документации нуждается в упоминании
имени автора, требующего Latin-1; в противном случае, использование `\x`, `\u` или
`\U` экранирования является предпочтительным способом включения не-ASCII данных в
строковые литералы.


Для Python 3.0 и далее, следующая политика предписывается для
стандартной библиотеки (см. PEP 3131): Все идентификаторы в стандартной библиотеке Python
ДОЛЖНЫ использовать только идентификаторы ASCII, и ДОЛЖНЫ использовать английские слова везде, где это возможно
(во многих случаях используются аббревиатуры и технические термины, которые не являются английскими). Кроме того,
строковые литералы и комментарии также должны быть в ASCII. Единственными исключениями являются
(a) тестовые случаи, тестирующие не-ASCII функции, и
(b) имена авторов. Авторы, чьи имена не основаны на латинском алфавите,
ДОЛЖНЫ предоставить латинскую транслитерацию своих имен.


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




### Импорты


* Импорты обычно должны быть на отдельных строках, например:

Да: import os import sys

Нет: import sys, os



Но можно и так:

from subprocess import Popen, PIPE

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


Импорты должны быть сгруппированы в следующем порядке:


	1. импорты стандартной библиотеки
	2. импорты связанных сторонних библиотек
	3. импорты локальных приложений/библиотекМежду каждой группой импортов должна быть пустая строка.


Разместите любую соответствующую спецификацию `__all__` после импортов.
* Относительные импорты для внутрипакетных импортов настоятельно не рекомендуются. Всегда используйте абсолютный путь к пакету для всех импортов. Даже после полного внедрения PEP 328 в Python 2.5, его стиль явных относительных импортов активно не рекомендуется; абсолютные импорты более переносимы и обычно более читаемы.
* При импорте класса из модуля, содержащего классы, обычно допустимо писать так:

from myclass import MyClass from foo.bar.yourclass import YourClass



Если это вызывает конфликты локальных имен, то пишите их так:

import myclass import foo.bar.yourclass



и используйте “myclass.MyClass” и “foo.bar.yourclass.YourClass”.




## Пробелы в выражениях и операторах



### Частые недочеты


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


* Непосредственно внутри круглых, квадратных или фигурных скобок.

Да: spam(ham[1], {eggs: 2}) Нет: spam( ham[ 1 ], { eggs: 2 } )

* Непосредственно перед запятой, точкой с запятой или двоеточием:

Да: if x == 4: print x, y; x, y = y, x Нет: if x == 4 : print x , y ; x , y = y , x

* Непосредственно перед открывающей скобкой, начинающей список аргументов вызова функции:

Да: spam(1) Нет: spam (1)

* Непосредственно перед открывающей скобкой, начинающей индексирование или срез:

Да: dict[‘key’] = list[index] Нет: dict [‘key’] = list [index]

* Более одного пробела вокруг оператора присваивания (или другого) для выравнивания с другим.


Да:

x = 1 y = 2 long_variable = 3



Нет:

x = 1 y = 2 long_variable = 3





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


* Всегда окружайте эти бинарные операторы одним пробелом с каждой стороны: присваивание (`=`), увеличивающее присваивание (`+=`, `-=` и т.д.), сравнения (`==`, `<`, `>`, `!=`, `<>`, `<=`, `>=`, `in`, `not in`, `is`, `is not`), логические (`and`, `or`, `not`).
* Если используются операторы с разным приоритетом, рассмотрите возможность добавления пробелов вокруг операторов с самым низким приоритетом. Используйте свое суждение; однако, никогда не используйте более одного пробела, и всегда оставляйте одинаковое количество пробелов с обеих сторон бинарного оператора.


Да:

i = i + 1 submitted += 1 x = x2 - 1 hypot2 = xx + y*y c = (a+b) * (a-b)



Нет:

i=i+1 submitted +=1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b)

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


Да:

def complex(real, imag=0.0): return magic(r=real, i=imag)



Нет:

def complex(real, imag = 0.0): return magic(r = real, i = imag)

* Составные операторы (несколько операторов на одной строке) вообще не рекомендуются.


Да:

if foo == ‘blah’: do_blah_thing() do_one() do_two() do_three()



Лучше не:

if foo == ‘blah’: do_blah_thing() do_one(); do_two(); do_three()

* Хотя иногда можно поместить if/for/while с небольшим телом на одной строке, никогда не делайте этого для многострочных операторов. Также избегайте сворачивания таких длинных строк!


Лучше не:

if foo == ‘blah’: do_blah_thing() for x in lst: total += x while t < 10: t = delay()



Точно не:

if foo == ‘blah’: do_blah_thing() else: do_non_blah_thing()

try: something() finally: cleanup()

do_one(); do_two(); do_three(long, argument, list, like, this)

if foo == ‘blah’: one(); two(); three()






### Придирки


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


* Непосредственно внутри скобок, квадратных скобок или фигурных скобок.

Да: spam(ham[1], {eggs: 2}) Нет: spam( ham[ 1 ], { eggs: 2 } )

* Непосредственно перед запятой, точкой с запятой или двоеточием:

Да: if x == 4: print x, y; x, y = y, x Нет: if x == 4 : print x , y ; x , y = y , x

* Непосредственно перед открывающей скобкой, начинающей список аргументов функции:

Да: spam(1) Нет: spam (1)

* Непосредственно перед открывающей скобкой, начинающей индексирование или срез:

Да: dict[‘key’] = list[index] Нет: dict [‘key’] = list [index]

* Более одного пробела вокруг оператора присваивания (или другого) для выравнивания с другим.


Да:

x = 1 y = 2 long_variable = 3



Нет:

x = 1 y = 2 long_variable = 3





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


* Всегда окружайте эти двоичные операторы одним пробелом с каждой стороны: присваивание (`=`), увеличивающее присваивание (`+=`, `-=` и т.д.), сравнения (`==`, `<`, `>`, `!=`, `<>`, `<=`,
`>=`, `in`, `not in`, `is`, `is not`), логические операторы (`and`,
`or`, `not`).
* Если используются операторы с разными приоритетами, рассмотрите возможность добавления пробелов вокруг операторов с наименьшим приоритетом. Используйте свое суждение; однако, никогда не используйте более одного пробела, и всегда оставляйте одинаковое количество пробелов с обеих сторон двоичного оператора.


Да:

i = i + 1 submitted += 1 x = x2 - 1 hypot2 = xx + y*y c = (a+b) * (a-b)



Нет:

i=i+1 submitted +=1 x = x * 2 - 1 hypot2 = x * x + y * y c = (a + b) * (a - b)

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


Да:

def complex(real, imag=0.0): return magic(r=real, i=imag)



Нет:

def complex(real, imag = 0.0): return magic(r = real, i = imag)

* Составные операторы (несколько операторов на одной строке) вообще не рекомендуются.


Да:

if foo == ‘blah’: do_blah_thing() do_one() do_two() do_three()



Лучше нет:

if foo == ‘blah’: do_blah_thing() do_one(); do_two(); do_three()

* Хотя иногда допустимо поместить if/for/while с небольшим телом на одной строке, никогда не делайте этого для многострочных операторов. Также избегайте сворачивания таких длинных строк!


Лучше нет:

if foo == ‘blah’: do_blah_thing() for x in lst: total += x while t < 10: t = delay()



Определенно нет:

if foo == ‘blah’: do_blah_thing() else: do_non_blah_thing()

try: something() finally: cleanup()

do_one(); do_two(); do_three(long, argument, list, like, this)

if foo == ‘blah’: one(); two(); three()





## Комментарии


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


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


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


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


При написании на английском языке применяются правила Странка и Уайта.


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



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


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


Абзацы внутри блочного комментария разделяются строкой, содержащей один `#`.




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


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


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


Встроенные комментарии излишни и отвлекают, если они указывают очевидное. Не делайте так:

x = x + 1 # Увеличить x



Но иногда это полезно:

x = x + 1 # Компенсировать границу





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


Соглашения о написании хороших строк документации (также известных как "docstrings") зафиксированы в PEP 257.


* Пишите строки документации для всех публичных модулей, функций, классов и методов. Строки документации не нужны для непубличных методов, но должен быть комментарий, описывающий, что делает метод. Этот комментарий должен появляться после строки `def`.
* PEP 257 описывает хорошие соглашения о строках документации. Важно отметить, что `"""`, завершающий многострочную строку документации, должен быть на отдельной строке, и, предпочтительно, перед ним должна быть пустая строка, например:

“““Return a foobang

Optional plotz says to frobnicate the bizbaz first.

"””

* Для однострочных строк документации допустимо оставить закрывающий `"""` на той же строке.





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


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


Абзацы внутри блочного комментария разделяются строкой, содержащей один `#`.




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


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


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


Встроенные комментарии излишни и отвлекающие, если они указывают очевидное. Не делайте этого:

x = x + 1 # Увеличить x



Но иногда это может быть полезно:

x = x + 1 # Компенсировать рамку





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


Соглашения по написанию хороших строк документации
(также известных как “docstrings”) закреплены в PEP 257.


* Пишите docstrings для всех публичных модулей, функций, классов и
методов. Docstrings не требуются для непубличных методов, но
вы должны иметь комментарий, описывающий, что делает метод. Этот
комментарий должен появляться после строки `def`.
* PEP 257 описывает хорошие соглашения по docstring. Обратите внимание, что
наиболее важно, закрывающие `"""` многострочного docstring должны быть
на отдельной строке и, предпочтительно, предшествовать пустой строке, например:

“““Return a foobang

Optional plotz says to frobnicate the bizbaz first.

"””

* Для однострочных docstrings допустимо оставить закрывающие `"""` на
той же строке.




## Ведение версионности


Если вам необходимо иметь в файле исходного кода данные Subversion, CVS или RCS, делайте это следующим образом.

version = “$Revision$”



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




## Соглашения об именах


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



### Описательные: Стили именования


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


Следующие стили именования обычно различаются:


* `b` (одна строчная буква)
* `B` (одна заглавная буква)
* `lowercase`
* `lower_case_with_underscores`
* `UPPERCASE`
* `UPPER_CASE_WITH_UNDERSCORES`
* `CapitalizedWords` (или CapWords, или CamelCase – так назван из-за неровной формы его букв ). Это также иногда называют StudlyCaps.


Примечание: При использовании аббревиатур в CapWords, заглавными должны быть все буквы аббревиатуры. Таким образом, HTTPServerError лучше, чем HttpServerError.
* `mixedCase` (отличается от CapitalizedWords начальным строчным символом!)
* `Capitalized_Words_With_Underscores` (уродливо!)


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


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


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


* `_single_leading_underscore`: слабый индикатор "внутреннего использования". Например, `from M import *` не импортирует объекты, имя которых начинается с подчеркивания.
* `single_trailing_underscore_`: используется по соглашению для избежания конфликтов с ключевыми словами Python, например:

Tkinter.Toplevel(master, class_=‘ClassName’)

* `__double_leading_underscore`: при именовании атрибута класса вызывает изменение имени (внутри класса FooBar, `__boo` становится `_FooBar__boo`; см. ниже).
* `__double_leading_and_trailing_underscore__`: "магические" объекты или атрибуты, которые существуют в пользовательских пространствах имен. Например, `__init__`, `__import__` или `__file__`. Никогда не придумывайте такие имена; используйте их только в соответствии с документацией.




### Предписывающие: Соглашения об именах



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


Никогда не используйте символы ‘l’ (строчная буква el), ‘O’ (заглавная буква oh) или ‘I’ (заглавная буква eye) в качестве односимвольных имен переменных.


В некоторых шрифтах эти символы неотличимы от цифр один и ноль. Когда возникает соблазн использовать ‘l’, используйте ‘L’ вместо этого.




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


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


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


Когда модуль на C или C++ имеет сопутствующий модуль Python, предоставляющий более высокий уровень (например, более объектно-ориентированный) интерфейс, C/C++ модуль имеет ведущее подчеркивание (например, `_socket`).




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


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




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


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




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


(Давайте надеяться, что эти переменные предназначены для использования только в одном модуле.) Соглашения аналогичны тем, что используются для функций.


Модули, предназначенные для использования через `from M import *`, должны использовать механизм `__all__` для предотвращения экспорта глобальных переменных, или использовать более старый подход, предваряя такие глобальные переменные подчеркиванием (который вы можете захотеть сделать, чтобы указать, что эти глобальные переменные "не являются публичными" для модуля).




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


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


mixedCase допускается только в контекстах, где это уже преобладающий стиль (например, threading.py), для сохранения обратной совместимости.




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


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


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


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




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


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


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


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


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


Примечание: существует некоторая дискуссия о использовании __names (см. ниже).
### Описательные: Стили Именования


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


Следующие стили именования обычно различают:


* `b` (одна строчная буква)
* `B` (одна заглавная буква)
* `lowercase`
* `lower_case_with_underscores`
* `UPPERCASE`
* `UPPER_CASE_WITH_UNDERSCORES`
* `CapitalizedWords` (или CapWords, или CamelCase – так названо из-за неровной формы его букв ). Это также иногда называют StudlyCaps.


Примечание: При использовании аббревиатур в CapWords, заглавными должны быть все буквы аббревиатуры. Таким образом, HTTPServerError лучше, чем HttpServerError.
* `mixedCase` (отличается от CapitalizedWords начальным строчным символом!)
* `Capitalized_Words_With_Underscores` (уродливо!)


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


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


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


* `_single_leading_underscore`: слабый индикатор "внутреннего использования". Например, `from M import *` не импортирует объекты, имя которых начинается с подчеркивания.
* `single_trailing_underscore_`: используется по соглашению для избежания конфликтов с ключевыми словами Python, например:

Tkinter.Toplevel(master, class_=‘ClassName’)

* `__double_leading_underscore`: при именовании атрибута класса вызывает изменение имени (внутри класса FooBar, `__boo` становится `_FooBar__boo`; см. ниже).
* `__double_leading_and_trailing_underscore__`: "магические" объекты или атрибуты, которые существуют в пользовательски контролируемых пространствах имен. Например, `__init__`, `__import__` или `__file__`. Никогда не придумывайте такие имена; используйте их только как указано в документации.






### Предписывающие: Соглашения об именах



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


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


В некоторых шрифтах эти символы неотличимы от цифр один и ноль. Когда возникает соблазн использовать ‘l’, используйте вместо этого ‘L’.




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


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


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


Когда модуль, написанный на C или C++, имеет сопутствующий Python-модуль, который предоставляет более высокий уровень (например, более объектно-ориентированный) интерфейс, C/C++-модуль имеет префикс с подчеркиванием (например, `_socket`).




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


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




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


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




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


(Давайте надеяться, что эти переменные предназначены для использования только внутри одного модуля.) Соглашения аналогичны тем, которые применяются к функциям.


Модули, предназначенные для использования через `from M import *`, должны использовать механизм `__all__` для предотвращения экспорта глобальных переменных, или использовать более старый конвенциональный способ – добавлять префикс с подчеркиванием к таким глобальным переменным (что вы можете захотеть сделать, чтобы указать, что эти глобальные переменные являются "непубличными" для модуля).




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


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


mixedCase допускается только в контекстах, где это уже преобладающий стиль (например, threading.py), для сохранения обратной совместимости.




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


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


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


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




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


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


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


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


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


Примечание: существует некоторая полемика относительно использования __names (см. ниже).




#### Константы


Константы обычно определяются на уровне модуля и записываются заглавными буквами с подчеркиваниями, разделяющими слова. Примеры включают `MAX_OVERFLOW` и `TOTAL`.




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


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


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


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


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


С этим в виду, вот Pythonic рекомендации:


* Публичные атрибуты не должны иметь подчеркиваний в начале.
* Если ваше публичное имя атрибута конфликтует с зарезервированным ключевым словом, добавьте к имени атрибута одно подчеркивание в конце. Это предпочтительнее, чем использование аббревиатуры или искаженного написания. (Однако, несмотря на это правило, ‘cls’ является предпочтительным написанием для любой переменной или аргумента, который известен как класс, особенно первый аргумент метода класса.)


Примечание 1: См. рекомендацию по имени аргумента для методов класса выше.
* Для простых публичных атрибутов данных лучше всего просто предоставить имя атрибута, без сложных методов доступа/мутации. Помните, что Python предоставляет легкий путь к будущему улучшению, если вы обнаружите, что простой атрибут данных нуждается в расширении функциональности. В этом случае используйте свойства для скрытия функциональной реализации за простым синтаксисом доступа к атрибутам данных.


Примечание 1: Свойства работают только с новыми классами.


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


Примечание 3: Избегайте использования свойств для дорогостоящих вычислений; нотация атрибутов заставляет вызывающего полагать, что доступ (относительно) дешев.
* Если ваш класс предназначен для наследования, и у вас есть атрибуты, которые вы не хотите, чтобы использовали подклассы, рассмотрите возможность именования их с двумя подчеркиваниями в начале и без подчеркиваний в конце. Это вызывает алгоритм изменения имен в Python, где имя класса смешивается с именем атрибута. Это помогает избежать конфликтов имен атрибутов, если подклассы случайно содержат атрибуты с тем же именем.


Примечание 1: Обратите внимание, что только простое имя класса используется в измененном имени, поэтому если подкласс выбирает как то же имя класса, так и имя атрибута, вы все равно можете получить конфликты имен.


Примечание 2: Изменение имен может сделать определенные использования, такие как отладка и `__getattr__()`, менее удобными. Однако алгоритм изменения имен хорошо документирован и легко выполняется вручную.


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





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


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


В некоторых шрифтах эти символы неотличимы от цифр один и ноль. Когда возникает желание использовать ‘l’, используйте вместо этого ‘L’.




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


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


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


Когда модуль на C или C++ имеет сопутствующий модуль Python, который предоставляет более высокий уровень (например, более объектно-ориентированный) интерфейс, модуль на C/C++ имеет ведущий подчеркивание (например, `_socket`).




#### Имена Классов


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




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


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




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


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


Модули, предназначенные для использования через `from M import *`, должны использовать
механизм `__all__` для предотвращения экспорта глобальных переменных, или использовать более старый
конвенции, добавляя подчеркивание в начале таких глобальных переменных (что вы можете захотеть сделать,
чтобы указать, что эти глобальные переменные являются "непубличными" для модуля).




#### Имена Функций


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


mixedCase допускается только в контекстах, где это уже является
преобладающим стилем (например, threading.py), чтобы сохранить обратную
совместимость.




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


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


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


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




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


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


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


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


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


Примечание: существует некоторая спорность относительно использования __names (см. ниже).




#### Константы


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




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


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


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


Мы не используем здесь термин “private”, так как в Python ни один атрибут
на самом деле не является приватным (без обычно ненужного количества
работы).


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


Учитывая это, вот питонические рекомендации:


* Публичные атрибуты не должны иметь ведущих подчеркиваний.
* Если имя вашего публичного атрибута конфликтует с зарезервированным
ключевым словом, добавьте к имени атрибута одно завершающее подчеркивание.
Это предпочтительнее, чем сокращение или искаженное написание. (Однако,
несмотря на это правило, ‘cls’ является предпочтительным написанием для
любой переменной или аргумента, который известен как класс, особенно для
первого аргумента метода класса.)


Примечание 1: См. рекомендацию по имени аргумента выше для методов класса.
* Для простых публичных атрибутов данных лучше всего просто
предоставить имя атрибута, без сложных методов доступа/мутатора. Имейте в
виду, что Python предоставляет легкий путь для будущего улучшения, если вы
обнаружите, что простой атрибут данных нуждается в функциональном
поведении. В этом случае используйте свойства, чтобы скрыть
функциональную реализацию за простым синтаксисом доступа к атрибутам
данных.


Примечание 1: Свойства работают только с новыми классами.


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


Примечание 3: Избегайте использования свойств для вычислительно
дорогостоящих операций; обозначение атрибута заставляет вызывающего
считать, что доступ (относительно) дешев.
* Если ваш класс предназначен для подклассификации, и у вас есть
атрибуты, которые вы не хотите, чтобы подклассы использовали,
рассмотрите возможность их именования с двойным ведущим подчеркиванием и
без завершающего подчеркивания. Это вызывает алгоритм изменения имени
Python, где имя класса изменяется в имени атрибута. Это помогает избежать
столкновений имен атрибутов, если подклассы случайно содержат атрибуты с
тем же именем.


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


Примечание 2: Изменение имени может сделать определенные применения,
такие как отладка и `__getattr__()`, менее удобными. Однако
алгоритм изменения имени хорошо документирован и легко выполняется
вручную.


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




## Ссылки




|  | PEP 7, Руководство по стилю для кода на C, ван Россум |
| --- | --- |




|  | Руководство по стилю Барри для GNU Mailman <http://barry.warsaw.us/software/STYLEGUIDE.txt> |
| --- | --- |




|  | <http://www.wikipedia.com/wiki/CamelCase> |
| --- | --- |




## Авторское право


Автор: Гвидо ван Россум <[guido@python.org](mailto:guido%40python.org)>, Барри Варшавский <[barry@python.org](mailto:barry%40python.org)>

Перейти к следующему уроку →

PEP8 Рекомендации Python

Table of Contents

Введение

Глупая последовательность — это домовой маленьких умов

Расположение кода

Отступы

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

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

Присоединяйтесь к обсуждению!

Расскажите друзьям: