Рекомендуется придерживаться следующих правил разметки кода
Используйте 4 пробела для добавления отступа.
Последующие строки обернутых элементов в скобки должны быть выравнены либо по вертикали, либо с помощью висящего отступа.
При использовании висячего отступа, следует учитывать следующее: в первой строке не должно быть аргументов, и следует использовать дополнительный отступ, чтобы четко отличить себя как строку продолжения.
Правильно:
# Выравнивается с разделителем открытия. foo = long_function_name(var_one, var_two, var_three, var_four) # Добавьте 4 пробела (дополнительный уровень отступа), # чтобы отличить аргументы. 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)
Не правильно:
#Аргументы в первой строке запрещены, если не используется вертикальное выравнивание. 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)
Правило 4 пробелов не является обязательным для строк продолжения.
По желанию:
# Висячие отступы могут иметь отступы, отличные от 4 пробелов. foo = long_function_name ( var_one, var_two, var_three, var_four)
Когда условная часть if достаточно длинная (более 79 символов) и мы должны записать ее в несколько строк, стоит отметить, что сочетание двухсимвольного ключевого слова (например, if ), одного пробела и открывающей скобки, при переносе, создает естественный отступ в 4 символа для последующих строк. Это может привести к визуальному конфликту с дальнейшим набором кода, вложенным в конструкцию if, которое также будет иметь отступ в 4 пробела. Этот PEP не занимает явной позиции о том, как следует дополнительно визуально отличать такие строки от вложенного кода внутри конструкции if. Приемлемые варианты в этой ситуации можно посмотреть в примерах ниже, но не ограничиваться этим:
# Никаких дополнительных отступов, код в конструкции if # сливается с условием, что затрудняет чтение кода if (this_is_one_thing and that_is_another_thing): do_something()
# Добавить комментарий, который обеспечит некоторое различие # в редакторе при помощи подсветки синтаксиса. if (this_is_one_thing and that_is_another_thing): # Так как .... do_something()
# Добавьте дополнительный отступ в строке условного продолжения. if (this_is_one_thing and that_is_another_thing): do_something()
Закрывающая скобка в многострочных конструкциях может располагаться либо под первым символом последней строки списка:
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 с параметром -t выдает предупреждения о коде, который смешивает табуляции и пробелы. При использовании -tt эти предупреждения становятся ошибками. Эти варианты настоятельно рекомендуются!
Ограничьте все строки максимум 79 символами.
Для строк документации или комментариев длина строки должна быть ограничена 72 символами.
Ограничение ширины окна редактора позволяет одновременно открывать несколько файлов и хорошо работает при использовании инструментов обзора, которые представляют две версии кода в соседних окнах.
Перенос по умолчанию в большинстве редакторов нарушает визуальную структуру кода, что делает его более трудным для понимания. Данные ограничения приняты для того, чтобы избежать автоматического переноса строк в редакторах с шириной окна, установленной на 80 символов, даже если он помещает маркер курсора в последний столбец. Некоторые IDE могут вообще не иметь авто-переноса строк.
Некоторые команды разработчиков предпочитают более длинные строки при написании кода. Исключительно для поддержания такого кода внутри команды, разрешается увеличить ограничение длины строки до 99 символов, при условии, что комментарии и документация должна быть ограничена 72 символами
Стандартная библиотека Python консервативна и требует ограничения строки до 79 символов (и строки документации/комментариев до 72).
Предпочтительный способ переноса длинных строк - это использование показанного выше переноса кода внутри скобок. Длинные строки можно разбить на несколько строк, заключив выражения в скобки.
income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)
Если такое не возможно, например, длинные строковые параметры в аргументах функций, то допустимо использование обратного слеша \.
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 утверждениями.
Удостоверьтесь, что сделали отступ в 4 пробела для продолжения строки кода.
В течение десятилетий рекомендуется переносить строки после двоичного оператора. Но это может усложнить читабельность. При таком переносе, операторы, как правило, разбросаны по разным столбцам, при этом каждый оператор отошел от своей переменной и перешел на предыдущую строку. Здесь глаз должен сделать дополнительную работу, чтобы увидеть, какие элементы добавляются, а какие вычитаются:
# Неправильно: # операторы сидят далеко от своих операндов income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)
Чтобы решить проблему читаемости, математики следуют противоположному соглашению. Следуя традиции математики, обычно получается более читаемый код:
# Правильно: # легко сопоставлять операторы с операндами income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)
В коде Python допускается перенос до или после двоичного оператора, если есть такое соглашение. Для нового кода предлагается математический стиль.
Определения функций и классов верхнего уровня должны быть заключены в две пустые строки.
Определения методов внутри класса заключены в одну пустую строку.
Дополнительные пустые строки могут использоваться для разделения групп связанных функций. Пустые строки могут быть пропущены между связкой связанных строк (например, набором фиктивных реализаций).
Используйте пустые строки в функциях, чтобы указать логические разделы.
Python принимает символ перевода формы control-L (т.е. ^ L) в качестве пробела. Многие инструменты обрабатывают эти символы как разделители страниц, поэтому, вы можете использовать их для разделения страниц связанных разделов вашего файла. Обратите внимание, что некоторые редакторы и IDE могут не распознавать control-L.
Код в основном дистрибутиве Python всегда должен использовать UTF-8 (или ASCII в Python 2).
Файлы, использующие ASCII (в Python 2) или UTF-8 (в Python 3), не должны иметь декларации кодировки.
В стандартной библиотеке, кодировки, отличные от заданных по умолчанию, следует использовать только для целей тестирования или в тех случаях, когда в комментариях или строке документации необходимо упомянуть имя автора, содержащее символы, отличные от ASCII. В противном случае использование \x , \u , \U или \N escape-файлов является предпочтительным способом включения данных не-ASCII в строковые литералы.
Для Python 3.0 и выше, для стандартной библиотеки предписана следующая политика. Все идентификаторы в стандартной библиотеке Python ДОЛЖНЫ использовать идентификаторы только ASCII и ДОЛЖНЫ использовать английские слова везде, где это возможно (сокращения и технические термины, которые не являются английскими). Кроме того, все строковые литералы и комментарии также должны быть в ASCII.
Единственными исключениями являются:
Проектам с открытым исходным кодом с глобальной аудиторией рекомендуется придерживаться аналогичной политики.
Импорт обычно должен быть в отдельных строках:
# Правильно: import os import sys # Неправильно: import sys, os
Это нормально, хотя:
from subprocess import Popen, PIPE
Импорт всегда помещается вверху файла, сразу после любых комментариев и строк документации, а также перед глобальными переменными и константами модуля.
Импорт должен быть сгруппирован в следующем порядке:
Вы должны поставить пустую строку между каждой группой импорта.
Рекомендуется абсолютный импорт, так как он обычно более читабелен и, как правило, ведет себя лучше (или, по крайней мере, дает лучшие сообщения об ошибках), если система импорта настроена неправильно (например, когда каталог внутри пакета заканчивается в sys.path ):
import mypkg.sibling from mypkg import sibling from mypkg.sibling import example
Однако явный относительный импорт является приемлемой альтернативой абсолютному импорту, особенно когда речь идет о сложном макете в пакете, где использование абсолютного импорта было бы излишне многословным:
from . import sibling from .sibling import example
Код стандартной библиотеки должен избегать сложных макетов пакетов и всегда использовать абсолютный импорт.
Неявный относительный импорт никогда не должен использоваться и был удален в Python 3.
При импорте класса из модуля, обычно можно записать следующее:
from myclass import MyClass from foo.bar.yourclass import YourClass
Если это написание вызывает локальные конфликты имен, то запишите импорт через точку:
import myclass import foo.bar.yourclass
и используйте myclass.MyClass и foo.bar.yourclass.YourClass.
Следует избегать импорта подстановочных знаков ( from <module> import * ), так как из-за этого неясно, какие имена присутствуют в пространстве имен, запутывает как читателей, так и многие автоматизированные инструменты. Существует один оправданный вариант использования для импорта с использованием подстановочного знака, который заключается в повторной публикации внутреннего интерфейса как части общедоступного API.
При повторной публикации имен, все же применяются приведенные ниже рекомендации, касающиеся открытых и внутренних интерфейсов.
Имена "dunders" (имена с двумя начальными и двумя замыкающими подчеркиваниями), такие как __all__ , __author__ , __version__ и т. ., Должны быть помещены после строки документации модуля, но перед любыми операторами импорта, кроме __future__. Python предписывает, что в __future__ импорт должен стоять перед любым другим кодом, кроме строк документации:
"""This is the example module. This module does stuff. """ from __future__ import barry_as_FLUFL __all__ = ['a', 'b', 'c'] __version__ = '0.1' __author__ = 'Cardinal Biggles' import os import sys
В Python одинарные и двойные кавычки функционально одинаковы. PEP не дает рекомендации какие из них предпочтительнее. Выберите правило и придерживайтесь его. Если, например, строка содержит одинарные кавычки, чтобы избежать обратной косой черты в строке, используйте дополнительно двойные кавычки. Это улучшает читаемость.
Для строк с тройными кавычками всегда используйте символы двойной кавычки, чтобы соответствовать соглашению с документированной строкой в PEP 257.