Введение

Этот документ описывает соглашение о том, как писать код для языка python, включая стандартную библиотеку, входящую в состав python. Пожалуйста, посмотрите также на сопутствующий PEP (python enhanced proposal — заявки на улучшение языка python), описывающий, какого стиля следует придерживаться при написании кода на C в реализации языка python¹.

Этот документ создан на основе рекомендаций Гуидо ван Россума с добавлениями от Барри. Если где-то возникал конфликт, мы выбирали стиль Гуидо. И, конечно, этот PEP может быть неполным (фактически, он, наверное, никогда не будет закончен).

A Foolish Consistency is the Hobgoblin of Little Minds²

Ключевая идея Гуидо такова: код читается намного больше раз, чем пишется. Собственно, рекоммендации о стиле написания кода направлены на то, чтобы улучшить читбельность кода и сделать его согласованным между большим числом проектов. В идеале, весь код будет написан в едином стиле, и любой сможет легко его прочесть. Как говорится в PEP 20³, «Читабельность имеет значение».

Это руководство о согласованности и единстве. Согласованность с этим руководством очень важна. Согласованность внутри одного проекта еще важнее. А согласованность внутри модуля или функции — самое важное. Но важно помнить, что иногда это руководство неприменимо, и понимать, когда можно отойти от рекоммендаций. Когда вы сомневаетесь, просто посмотрите на другие примеры и решите, какой выглядит лучше.

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

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

Отступы

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

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

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

Самый распространенный способ отступов — пробелы. На втором месте — отступы только с использованием табуляции. Код, в котором используются и те, и другие типы отступов, должен быть исправлен так, чтобы отступы в нем были расставлены только с помощью пробелов. Когда вы вызываете интерпретатор в командной строке с параметром -t, он выдает предупреждения (warnings) при использовании смешанного стиля в отступах, а запустив интерпретатор с параметром -tt, вы получите в этих местах ошибки (errors). Используйте этии опции!

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

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

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

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

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

Вот несколько примеров:

Copy Source | Copy HTML

1. class Rectangle(Blob):
2.       def __init__(self, width, height,
3.                    color='black', emphasis=None, highlight= 0):
4.           if width ==  0 and height ==  0 and \
5.              color == 'red' and emphasis == 'strong' or \
6.              highlight > 100:
7.               raise ValueError("sorry, you lose")
8.           if width ==  0 and height ==  0 and (color == 'red' or
9.                                              emphasis is None):
10.               raise ValueError("I don't think so -- values are %s, %s" %
11.                                (width, height))
12.           Blob.__init__(self, width, height,
13.                         color, emphasis, highlight)

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

Отделяйте функции (верхнего уровня, не функции внутри функций) и определения классов двумя пустыми строчками.

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

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

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

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

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

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

Files using ASCII (or UTF-8, for Python 3.0) should not have a coding cookie. Используйте Latin-1 (или UTF-8), только если это необходимо, чтобы указать в комментарии или строке документации имя автора, содержащее в себе символ из Latin-1. В противном случае предпочтительнее использовать escape-символы \x, \u или \U для не-ASCII символов в строках.

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

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

Import-секции

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

Copy Source | Copy HTML

1. import os
2. import sys

неправильно:

Copy Source | Copy HTML

1. import os, sys

В то же время, можно писать вот так:

Copy Source | Copy HTML

1. from subprocess import Popen, PIPE

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

Группируйте импорты в следующем порядке:
• импорты стандартной библиотеки
• импорты сторонних библиотек
• импорты модулей текущего проекта

Вставляйте пустую строку между каждой группой импортов.

Указывайте спецификации __all__ после импортов.

Относительные импорты крайне не рекомендуются — всегда указывайте абсолютный путь к модулю для всех импортирований. Даже сейчас, когда PEP 328⁴ реализован в версии python 2.5, использовать явные относительные импорты нежелательно, потому что абсолютные импорты лучше переносимы и читабельны.

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

Copy Source | Copy HTML

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

Если такое написание вызывает конфликт имен, тогда пишите:

Copy Source | Copy HTML

1. import myclass import foo.bar.yourclass

И используйте «myclass.MyClass» и «foo.bar.yourclass.Yourclass».

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

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

1. Сразу после или перед скобками (обычными, фигурными и квадратными)
можно:

Copy Source | Copy HTML

1. spam(ham[1], {eggs: 2})

нельзя:

Copy Source | Copy HTML

1. spam( ham[ 1 ], { eggs: 2 } )

2. Сразу перед запятой, точкой с запятой, двоеточием:
можно:

Copy Source | Copy HTML

1. if x == 4: print x, y; x, y = y, x

нельзя

Copy Source | Copy HTML

1. if x == 4 : print x , y ; x , y = y , x

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

Copy Source | Copy HTML

1. spam(1)

нельзя:

Copy Source | Copy HTML

1. spam (1)

4. Сразу перед открывающей скобкой, после которой следует индекс или срез:
можно:

Copy Source | Copy HTML

1. dict['key'] = list[index]

нельзя:

Copy Source | Copy HTML

1. dict ['key'] = list [index]

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

Copy Source | Copy HTML

1. x = 1
2. y = 2
3. long_variable = 3

нельзя:

Copy Source | Copy HTML

1. x = 1
2. y = 2
3. long_variable = 3

Прочие рекомендации:

1. Вседа окружайте эти бинарные операторы одним пробелом с каждой стороны: присваивание (=, +=, -= и прочие), сравнения (==, <, >, !=, <>, <=, >=, in, not in, is, is not), логические операторы (and, or, not).

2. Ставьте пробелы вокруг арифметических операций.
можно:

Copy Source | Copy HTML

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

нельзя:

Copy Source | Copy HTML

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

3. Не используйте пробелы для отделения знака =, когда он употребляется для обозначения аргумента-ключа (keyword argument) или значения параметра по умолчанию.
можно:

Copy Source | Copy HTML

1. def complex(real, imag= 0. 0):
2.     return magic(r=real, i=imag)

нельзя:

Copy Source | Copy HTML

1. def complex(real, imag =  0. 0):
2.     return magic(r = real, i = imag)

4. Не используйте составные инструкции (несколько команд в одной строке).
можно:

Copy Source | Copy HTML

1. if foo == 'blah':
2.     do_blah_thing()
3. do_one()
4. do_two()
5. do_three()

нельзя:

Copy Source | Copy HTML

1. if foo == 'blah': do_blah_thing()
2. do_one(); do_two(); do_three()

5. Иногда можно писать тело циклов while, for или ветку if в той же строке, если команда короткая, но если команд несколько, никогда так не пишите.
можно:

Copy Source | Copy HTML

1. if foo == 'blah': do_blah_thing()
2. for x in lst: total += x
3. while t < 10: t = delay()

нельзя:

Copy Source | Copy HTML

1. if foo == 'blah': do_blah_thing()
2. else: do_non_blah_thing()
3. try: something()
4. finally: cleanup()
5. do_one(); do_two(); do_three(long, argument,
6.                              list, like, this)
7. if foo == 'blah': one(); two(); three()

¹ PEP 7, Style Guide for C Code, van Rossum
² «A foolish consistency is the hobgoblin of little minds, adored by little statesman and philosophers and divines.  With consistency a great soul has simply nothing to do» — цитата Ральфа Валдо Эмерсона, известного американского писателя.
³ PEP 20, The Zen of Python
⁴ PEP 328, Imports: Multi-Line and Absolute/Relative

Материалы опубликованы с согласием переводчика.
Топик на Хабре