Python pep8 на русском: стиль кода в языке Python

Правила оформления кода по PEP8 на Python. Руководство для программиста — Python 3 | Data Science | Нейронные сети | AI

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

Вы также можете использовать это для замены переменных:

В Python 3 новый метод расширенной распаковки был представлен PEP3132 :

Если вам нужно что-то назначить (например, в распаковке ), но вам не понадобится эта переменная, используйте __:

Поскольку списки являются изменяемыми, *оператор (как указано выше) создаст список из N ссылок на один и тот же список, что вряд ли вам нужно. Вместо этого используйте понимание списка:

Примечание: используйте range () вместо xrange () в Python 3.

Распространенная идиома для создания строк — использовать str.join()пустую строку.

Это установит значение переменной word в «spam». Эта идиома может применяться к спискам и кортежам.

Поиск предмета в коллекции 

Иногда нам нужно искать в коллекции вещей. Давайте рассмотрим два варианта: списки и наборы.

Возьмите следующий код для примера:

s = set(['s', 'p', 'a', 'm'])
l = ['s', 'p', 'a', 'm']

def lookup_set(s):
    return 's' in s

def lookup_list(l):
    return 's' in l

Хотя обе функции выглядят одинаково, поскольку lookup_set использует тот факт, что наборы в Python являются хеш-таблицами, производительность поиска между ними очень различна. Чтобы определить, есть ли элемент в списке, Python должен будет просмотреть каждый элемент, пока не найдет соответствующий элемент. Это отнимает много времени, особенно для длинных списков. В наборе, с другой стороны, хеш элемента сообщит Python, где в наборе искать соответствующий элемент. В результате поиск может быть выполнен быстро, даже если набор большой. Поиск в словарях работает так же. Для получения дополнительной информации см. Эту страницу StackOverflow . Для получения подробной информации о времени, которое различные общие операции выполняют для каждой из этих структур данных, см. Эту страницу .

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

• Коллекция будет содержать большое количество предметов
• Вы будете неоднократно искать предметы в коллекции
• У вас нет дубликатов.

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

Дзен питона 

Также известен как PEP 20 , руководящие принципы для дизайна Python.

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Некоторые примеры хорошего стиля Python см. На этих слайдах из группы пользователей Python .

Соглашения PEP8

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

Проверьте, равна ли переменная постоянной 

Вам не нужно явно сравнивать значение с True, None или 0 — вы можете просто добавить его в оператор if. См. Проверка истинности значения для получения списка того, что считается ложным.

Плохо :

if attr == True:
    print 'True!'

if attr == None:
    print 'attr is None!'

Хорошо :

# Just check the value
if attr:
    print 'attr is truthy!'

# or check for the opposite
if not attr:
    print 'attr is falsey!'

# or, since None is considered false, explicitly check for it
if attr is None:
    print 'attr is None!

Доступ к элементу словаря 

Не используйте dict.has_key()метод. Вместо этого используйте синтаксис или передайте аргумент по умолчанию для .x in ddict.get()

Плохо :

d = {'hello': 'world'}
if d.has_key('hello'):
    print d['hello']    # prints 'world'
else:
    print 'default_value'

Хорошо :

d = {'hello': 'world'}

print d.get('hello', 'default_value') # prints 'world'
print d.get('thingy', 'default_value') # prints 'default_value'

# Or:
if 'hello' in d:
    print d['hello']

Короткие способы манипулирования списками 

Постижения списков предоставляют мощный и лаконичный способ работы со списками.

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

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

Плохо :

# needlessly allocates a list of all (gpa, name) entires in memory
valedictorian = max([(student.gpa, student.name) for student in graduates])

Хорошо :

valedictorian = max((student.gpa, student.name) for student in graduates)

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

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

Хорошо :

def make_batches(items, batch_size):
    """
    >>> list(make_batches([1, 2, 3, 4, 5], batch_size=3))
    [[1, 2, 3], [4, 5]]
    """
    current_batch = []
    for item in items:
        current_batch.append(item)
        if len(current_batch) == batch_size:
            yield current_batch
            current_batch = []
    yield current_batch

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

Плохо :

[print(x) for x in sequence]

Хорошо :

for x in sequence:
    print(x)

Фильтрация списка 

Плохо :

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

# Filter elements greater than 4
a = [3, 4, 5]
for i in a:
    if i > 4:
        a.remove(i)

Не делайте несколько проходов по списку.

while i in a:
    a.remove(i)

Хорошо :

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

# comprehensions create a new list object
filtered_values = [value for value in sequence if value != x]

# generators don't create another list
filtered_values = (value for value in sequence if value != x)

Возможные побочные эффекты изменения исходного списка 

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

# replace the contents of the original list
sequence[::] = [value for value in sequence if value != x]

Изменение значений в списке 

Плохо :

Помните, что назначение никогда не создает новый объект. Если две или более переменных ссылаются на один и тот же список, изменение одной из них изменит их все.

# Add three to all list members.
a = [3, 4, 5]
b = a                     # a and b refer to the same list object

for i in range(len(a)):
    a[i] += 3             # b[i] also changes

Хорошо :

Безопаснее создать новый объект списка и оставить оригинал в покое.

a = [3, 4, 5]
b = a

# assign the variable "a" to a new list without changing "b"
a = [i + 3 for i in a]

Используйте enumerate()счетчик вашего места в списке.

a = [3, 4, 5]
for i, item in enumerate(a):
    print i, item
# prints
# 0 3
# 1 4
# 2 5

enumerate()Функция имеет лучшую читаемость , чем обработка счетчика вручную. Более того, он лучше оптимизирован для итераторов.

Читать из файла 

Используйте синтаксис для чтения из файлов. Это автоматически закроет файлы для вас.with open

Плохо :

f = open('file.txt')
a = f.read()
print a
f.close()

Хорошо :

with open('file.txt') as f:
    for line in f:
        print line

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

Продолжение строки 

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

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

Плохо :

my_very_big_string = """For a long time I used to go to bed early. Sometimes, \
    when I had put out my candle, my eyes would close so quickly that I had not even \
    time to say “I’m going to sleep.”"""

from some.deep.module.inside.a.module import a_nice_function, another_nice_function, \
    yet_another_nice_function

Хорошо :

my_very_big_string = (
    "For a long time I used to go to bed early. Sometimes, "
    "when I had put out my candle, my eyes would close so quickly "
    "that I had not even time to say “I’m going to sleep.”"
)

from some.deep.module.inside.a.module import (
    a_nice_function, another_nice_function, yet_another_nice_function)

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

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

Python имеет определенные стандарты кода, которым стараются следовать все программисты. Эти стандарты описаны в документации PEP8.

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

Почему важно стандартизировать код?

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

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

Рекомендации по созданию красивого кода на Python не определяют стиль кода полностью. Поэтому программист может делать некоторые вещи на своё усмотрение, однако он всё ещё должен следовать тем указаниям, которые определены в стандарте.

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

Разметка кода на Python

Этот раздел содержит указания, определяющие, как оформлять код на Python 3 (пробелы, отступы, строки).

Отступы

Для обозначения нового уровня вложенности используется четыре пробела.

При разделении аргументов функции на несколько строк размер отступа может быть разным.

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

f1 = func(first_arg, second_arg,
          third_arg, fourth_arg)

либо использовать четыре пробела, но с обязательным переносом первой строки:

f1 = func(
    first_arg, second_arg,
    third_arg, fourth_arg)

Использовать для продолжения именно 4 пробела – это не обязательное правило для строк продолжения перечисления. Можно использовать и другое количество пробелов, например, 2.

Если после списка аргументов следует еще какой-либо код (например, если это объявляется функция), то к отступу аргументов добавляется еще 4 пробела:

def func(
        first_arg, second_arg, 
        third_arg, fourth_arg):
    print(fourth_arg)

Это делается для того, чтобы отделить аргументы от тела функции.

В случае с оператором if, программист может как использовать, так и не использовать экстра отступы:

if(temp > 5 and
        temp < 25):
    some_func(some_args[])

if(temp > 5
    and temp < 25):
    some_func(some_args[])

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

Закрывающая конструкция в функции или структуре может располагаться под первым символом нижней строки:

names = [
    "John", "Alex",
    "Olivia", "Jacob",
    ]

Также её можно поместить в самое начало строки:

f = some_f(
    "str1", "str2",
    "str3", "str4",
)

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

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

Программист не должен использовать более 79 символов в одной строке. Строки длинного многострочного текста (комментарии, документация) ограничены 72-я символами.

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

Круглые скобки — лучший способ реализовать разделение кода на несколько строк. Однако программисты также могут использовать знак обратной косой черты “\“.

Бинарные операторы и пробелы

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

Правильно:

math_rez = a * b – x + y

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

math_rez=a*b–x+y

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

max_sum = (first_sum
           + second_sum
           + third_sum)

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

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

Методы внутри класса отделяются одной пустой строкой.

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

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

Кодировка

Файлы с исходным кодом на Python 3 всегда должны иметь кодировку UTF-8. Раньше в Python 2 использовалась ASCII.

Если нужно использовать символы других кодировок, следует пользоваться экранирующими последовательностями: \x, \u, \U, \N.

Импорт

Импорт каждого нового модуля должен происходить в новой строке:

import sys
import time

При импорте нескольких частей модуля можно писать их в одной строке через запятую:

from time import sleep, ctime

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

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

1. Стандартные библиотеки.
2. Сторонние библиотеки.
3. Другие модули проекта.

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

Кавычки в строках

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

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

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

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

• Внутри фигурных, круглых или квадратных скобок.
  • Правильно:

    mix_arr = ("John", [176, 70], {"age" : 14})

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

    mix_arr = ( "John", [ 176, 70 ], { "age" : 14 } )

• Между запятой и закрывающей скобкой.
• Перед запятой, точкой или двоеточием. Однако в операции среза двоеточие должно иметь одинаковое количество пробелов с обеих сторон.
  • Правильно: mix_arr[0:2] или mix_arr[0 : 2]
  • Неправильно: mix_arr[0 :2] или mix_arr[0: 2]
• Между именем функции и скобкой с передаваемыми в неё аргументами.
  • Правильно:

    custom_function(args)

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

    custom_function (args)

• Нельзя использовать более одного пробела, чтобы выравнивать операторы присваивания разных выражений.
  • Правильно:

    weight = 70
    height = 1,76
    body_mass_index = 22,5

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

    weight          = 70
    height          = 1,76
    body_mass_index = 22,5

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

    y = 2*x – 1/x

• Если знак присваивания используется для задания параметра по умолчанию или именного аргумента, то он не отделяется пробелами.
  • Пример:

    def graph(x=0.0, y=0.0)

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

Использование запятых

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

• Правильно:

  names = ("John",)

• Допускается, но не рекомендуется:

  names = "John",

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

• Правильно:

  names = [
      "John",
      "Olivia",
      ]

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

  names = ["John", "Olivia",]

Комментарии

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

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

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

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

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

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

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

# Этот код делает что-то очень интересное
a = 5
b = 10
a = b - a + a

Комментарии “в строке”

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

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

a = a / 2 # Деление числа на два

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

a = a / 2 # Получение середины экрана

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

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

Более подробно про соглашение о документации рассказано в PEP 257. Кавычки, показывающие окончания строк документации, должны переносится на новую строку.

"""Speed determination.

Keyword arguments:
distance -- distance traveled in meters
time -- time in seconds (default 1)
"""

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

"""Some info about something."""

Правила по выбору имён

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

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

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

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

Стили имен

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

Обычно используются следующие стили:

• b (одиночная строчная буква)
• B (одиночная заглавная буква)
• lowercase (нижний регистр)
• lower_case_with_underscores (нижний регистр с нижней чертой-разделителем)
• UPPERCASE (верхний регистр)
• UPPER_CASE_WITH_UNDERSCORES (верхний регистр с нижней чертой-разделителем)
• CapitalizedWords (CamelCase) – каждое новое слово начинается с заглавной буквы
• mixedCase (отличается от предыдущего тем, что первая буква в нижнем регистре)

Имена, которые лучше не использовать

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

Если всё же возникла необходимость использовать l (“эл”), замените её на заглавную “L”.

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

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

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

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

Классам дают имена в соответствии со стилем наименования CapitalizedWords.

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

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

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

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

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

Если модуль предполагается импортировать командой from module import *, следует описать все разрешенные к импорту объекты в __all__. Это предотвращает импорт глобальных переменных, а также импорт тех объектов, которые в соответствии со своей реализацией не должны быть доступны извне.

__all__ – это список доступных для импорта объектов, то есть публичных.

Имена функций и переменных

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

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

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

Имена аргументов функций и методов

Для методов экземпляра в качестве первого аргумента всегда используется self, а для методов класса — cls.

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

• Правильно:
  tuple_
• Неправильно:
  tpl
tupl

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

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

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

Чтобы не допустить конфликта имён с подклассами, следует использовать два символа нижнего подчеркивания в начале имён. Если класс Animal имеет атрибут __a, обращение вида Animal.__a не будет работать (в этом случае можно использовать Animal._Animal__a), так как интерпретатор изменит имя. Двойное подчеркивание следует использовать только для того, чтобы избежать конфликта имён в классах и подклассах.

Константы

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

Примеры:

Рекомендации по программированию

• Код должен быть совместимым с другими реализациями Python, такими как PyPy, IronPython и другие.
• Если необходимо сравнить что-либо с такими объектами языка, как None, обязательно используйте операторы is или is not, а не знак равно.
  Кроме того, никогда не делайте проверку if x is not None (если x не является None). Так как это может привести к ошибке, если x – контейнер.
• Выражения “is not” и “not … is” ничем не отличаются друг от друга по функционалу. Однако для лучшей читаемости кода лучше использовать первое выражение.
• Не присваивайте переменной лямбда-выражение, потому что преимущество лямбда-выражения в том, что оно может быть встроено в длинный код. Вместо этого объявите функцию с помощью def.
• Если нужно перехватить исключение, указывайте конкретную ошибку. Если просто написать except, то компилятор будет перехватывать все исключения, что обязательно приведет к проблемам.
  • Правильно:

    try:
        import some_module
    except ImportError:
        print("Импорт невозможен")

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

    try:
        import some_module
    except:
        print("Я не задал тип ошибки, "
              "вы не сможете использовать ctrl+c")

• Внутри конструкции для отлавливания исключений должно быть минимум кода. Если это правило не соблюдено, то может быть не очевидно, что стало причиной ошибки.
• Чтобы сравнить тип двух объектов, используйте специальную функцию isinstance(), а не оператор is.
  • Правильно: isinstance(object, int)
  • Неправильно: type(object) is type(99)
• Нельзя сравнивать переменную с логическим типом с помощью равенства или is.
  • Правильно:

    if isAlive:

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

    if isAlive == True:

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

    if isAlive is True:

pep8. Коротко о главном ➤ DefPython

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

PEP 8: Руководство по стилю кодирования в Python

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

Для Python PEP 8 стал руководством по стилю, которого придерживается большинство проектов; это продвигает очень читаемый и приятный для глаз стиль кодирования. Каждый разработчик Python должен прочитать его в какой-то момент; Вот самые важные моменты, извлеченные для вас:

1. Используйте 4 пробела без вкладок.
Примеры:

# Aligned with opening delimiter.
grow = function_name(variable_one, variable_two,
                     variable_three, variable_four)

# First line contains no argument. Second line onwards
# more indentation included to distinguish this from 
# the rest.
def function_name(
        variable_one, variable_two, variable_three,
        variable_four):
    print(variable_one)

Правило 4 пробелов не всегда является обязательным и может быть отменено для строки продолжения.

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

def exam():
    """This is single line docstring"""

    """This is
    a
    multiline comment"""

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

with open('/path/from/where/you/want/to/read/file') as file_one, \
     open('/path/where/you/want/the/file/to/be/written', 'w') as file_two:
    file_two.write(file_one.read())

4. Использование регулярных и обновленных комментариев является ценным как для программистов, так и для пользователей . Существуют также различные типы и условия, которые при соблюдении могут оказать большую помощь с точки зрения программ и пользователей. Комментарии должны формировать полные предложения. Если комментарий является полным предложением, его первое слово должно начинаться с заглавной буквы, если только это не идентификатор, который начинается со строчной буквы. В коротких комментариях период в конце может быть опущен. В блочных комментариях есть более одного абзаца, и каждое предложение должно заканчиваться точкой. Блочные комментарии и встроенные комментарии могут быть написаны с последующим одиночным «#».
Пример встроенных комментариев:

geek = geek + 1                 # Increment

5. Использование запятых: это не обязательно, за исключением создания кортежа.
Пример:

tup = ("geek",)

5. Используйте стандартные кодировки Python UTF-8 или ASCII, а не какие-либо причудливые кодировки , если они предназначены для международной среды.

6. Используйте пробелы вокруг операторов и после запятых, но не внутри скобочных конструкций:

a = f(1, 2) + g(3, 4)

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

b (single lowercase letter)

B (single upper case letter)

lowercase

lower_case_with_underscores

UPPERCASE

UPPER_CASE_WITH_UNDERSCORES

CapitalizedWords (or CamelCase). This is also sometimes known as StudlyCaps.
Note: While using abbreviations in CapWords, capitalize all the letters 
of the abbreviation. Thus HTTPServerError is better than HttpServerError.

mixedCase (differs from CapitalizedWords by initial lowercase character!)

Capitalized_Words_With_Underscores

В дополнение к этим несколько ведущих или конечных подчеркиваний также рассматриваются.
Примеры:
single_leading_underscore: слабый индикатор «внутреннего использования». Например, из 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__ . Используйте их только как документально.

8. Символы, которые не должны использоваться для идентификаторов: «l» (строчная буква el), «O» (заглавная буква oh) или «I» (заглавная буква eye) в качестве имен переменных одного символа, так как они похожи на цифры один и ноль.

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

10. Называйте свои классы и функции единообразно . Соглашение состоит в том, чтобы использовать CamelCase для классов и lower_case_with_underscores для функций и методов. Всегда используйте self в качестве имени для первого аргумента метода.

11. В то время как именование функции методов всегда использует self для первого аргумента для методов экземпляра и cls для первого аргумента для методов класса. Если имя аргумента функции совпадает с зарезервированными словами, то оно может быть записано с запятой. Например, class_

Вы можете обратиться к этой простой программе, чтобы узнать, как написать понятный код:

Выход:

The factorial of 7 is 5040

Эта статья предоставлена Чинмой Ленкой . Если вы как GeeksforGeeks и хотели бы внести свой вклад, вы также можете написать статью с помощью contribute.geeksforgeeks.org или по почте статьи [email protected]. Смотрите свою статью, появляющуюся на главной странице GeeksforGeeks, и помогите другим вундеркиндам.

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

Рекомендуемые посты:

PEP 8: Руководство по стилю кодирования в Python

0.00 (0%) 0 votes

Python: русский PEP8 (сокращенная версия)

Краткое изложение стандартов оформления кода на Python, известное, как PEP8. Стандарт служит для удобства чтения вашего кода другими разработчиками. Начинающим разработчикам на Python рекомендуется распечатать и повесить на стену.

• используйте 4 пробела для отступа и не используйте табы, не смешивайте их
• максимальная длина строки 79 символов; для разрыва строки используйте отступы или бэкслеш
• функции верхнего уровня и определения классов отделяйте двумя пустыми строками
• определения методов внутри класса отделяйте одной пустой строкой
• дополнительные пустые строки используйте для логической группировки методов
• кодировка файлов должна быть Latin-1, а в Питоне 3 и выше — utf-8
• каждый импортируемый модуль с новой строки
• порядок импортов: стандартные модули, third-party модули, локальные модули приложения
• пустая строка между каждой группой импортов
• избегайте лишних пробелов внутри скобок; перед запятыми, точкой с запятой и двоеточиями
• избегайте лишних пробелов перед скобками с аргументами функций и скобками с индексами
• избегайте больше чем одного пробела между операторами (= — + итд)
• используйте одиночный пробел для выделения операторов
• избегайте пробелов вокруг ‘=’, который используется для параметров по-умолчанию и keyword аргументов
• обновляйте комментарии вместе с кодом
• пишите комментарии по-английски
• избегайте имён из одиночных l, O, I
• для модулей и пакетов используйте короткие всестрочные имена
• для классов используйте СловаНачинаютсяЗаглавными имена
• для функций используйте слова_с_подчёркиваниями (или смешанныйРегистр если так получилось исторически)
• для методов используйте слова_с_подчёркиваниями имена
• для внутренних методов и переменных _подчёркивание_перед_словом
• для проверки на None используйте is или is not, не используйте операторы сравнения
• используйте исключения основанные на классах — наследованные от Exception
• используйте методы класса string вместо строковых функций
• используйте ».startswith() и ».endswith() вместо вырезки из строк для проверки префиксов и суффиксов
• используйте isinstance() для проверки типа
• не сравнивайте булевы переменные с True и False

Поделиться «Python: русский PEP8 (сокращенная версия)»

Интересное по теме:

Стиль программирования Python и основные правила PEP8

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

Форматирование

•  Используйте четыре пробела для отступов. Не делайте отступов в два пробела.

•  Пишите import  каждого модуля в отдельной строке

• Располагайте все import‘ы в верхней части кода перед любыми глобальными объявлениями.

• Отделяйте блок import‘ов от кода пустой строкой.

• Не используйте конструкцию from … import *

• Скобки не отделяются пробелами с внутренней стороны. Между функцией и ее аргументами пробел не ставится.

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     # Неверно

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

  • присваивания (=, +=, -= и т. д.),

  • сравнения (==, <, >, !=, <>, <=, >=, in, not in, is, is not),

  • логические (and, or, not),

  • арифметические (+, -, *, /, //, \%, **).

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

x = 3            # Правильно
func(10)
x = 3; func(10)  # Неверно  Не располагайте блок из нескольких инструкций на той же строке сразу после двоеточия (после if, while и т. д.)

Комментарии

• Комментарии, противоречащие коду, хуже, чем их отсутствие.

• Располагайте однострочные комментарии после кода в той же строке и отделяйте их от кода не менее чем двумя пробелами. Комментарии должны начинаться с # и одного пробела.

Имена 

• Не используйте символы `l’, `O’, и `I’ как имена переменных. В некоторых шрифтах они могут быть очень похожи на цифры.

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

 name, name_with_several_words_in_it

 NAME, NAME_WITH_SEVERAL_WORDS_IN_IT

num_letters = int(input())         # Правильно

kolvo_bukv = int(input())          # Неверно 

Функции 

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

• Разделяйте тело функции на логические части одной пустой строкой.

Форматирование Python-кода / Хабр

Введение

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

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

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

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

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

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

Он включает:

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

В целом, покрывает множество правил форматирования кода. Однако, стоит заметить, что не все python-программисты соблюдают данные правила.
Большие компании, такие как Google, имеют свои рекомендации к написанию python-кода, их можно почитать здесь и здесь.
Весьма интересное чтиво, рекомендую.

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

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

pep8

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

$ pep8 --first optparse.py
optparse.py:69:11: E401 multiple imports on one line
optparse.py:77:1: E302 expected 2 blank lines, found 1
optparse.py:88:5: E301 expected 1 blank line, found 0
optparse.py:222:34: W602 deprecated form of raising exception
optparse.py:347:31: E211 whitespace before '('
optparse.py:357:17: E201 whitespace after '{'
optparse.py:472:29: E221 multiple spaces before operator
optparse.py:544:21: W601 .has_key() is deprecated, use 'in'

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

autopep8

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

$ autopep8 ./ --recursive --in-place -a

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

autoflake

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

$ autoflake --in-place --remove-all-unused-imports --remove-unused-variables -r ./

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

unify

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

$ unify --in-place -r ./src/

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

docformatter

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

$ docformatter --in-place example.py

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

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

Выводы

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

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

python — Почему в PEP-8 указана максимальная длина строки 79 символов?

Переполнение стека

1. Около

2. Продукты

3. Для команд

1. Переполнение стека
   Общественные вопросы и ответы

2. Переполнение стека для команд
   Где разработчики и технологи делятся частными знаниями с коллегами

3. Вакансии
   Программирование и связанные с ним технические возможности карьерного роста

4. Талант
   Нанимайте технических специалистов и создавайте свой бренд работодателя

5. Реклама
   Обратитесь к разработчикам и технологам со всего мира

.

PEP 8 — Руководство по стилю для кода Python

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

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

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

Многие проекты имеют свои собственные рекомендации по стилю кодирования. В случае каких-либо
конфликты, такие руководства для конкретного проекта имеют приоритет для этого проекта.

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

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

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

В частности: не нарушайте обратную совместимость только для соблюдения
это PEP!

Некоторые другие веские причины игнорировать конкретное правило:

1. При применении директивы код будет менее читабельным, даже
   для тех, кто привык читать код, следующий за этим PEP.
2. Чтобы соответствовать окружающему коду, который также его нарушает (возможно,
   по историческим причинам) — хотя это тоже возможность
   убирать чужой беспорядок (в истинном стиле XP).
3. Поскольку рассматриваемый код появился еще до введения
   рекомендации, и нет никаких других причин для изменения этого кода.
4. Когда код должен оставаться совместимым со старыми версиями
   Python, который не поддерживает функцию, рекомендованную руководством по стилю.

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

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

# Верный:

# Выровнено по открывающему разделителю.
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):
    печать (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):
    печать (var_one)
 

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

Дополнительно:

# Висячие отступы * могут * иметь отступ, отличный от 4 пробелов.
foo = long_function_name (
  var_one, var_two,
  var_three, var_four)
 

Когда условная часть оператора if достаточно длинна, чтобы требовать
чтобы он был написан в несколько строк, стоит отметить, что
комбинация двухсимвольного ключевого слова (например, если) плюс один пробел,
плюс открывающая скобка создает естественный 4-пробельный отступ для
последующие строки многострочного условного.Это может создать визуальное
конфликт с набором кода с отступом, вложенным в оператор if,
который также естественно будет иметь отступ до 4 пробелов. Этот PEP не требует
четкая позиция о том, как (и нужно ли) дополнительно визуально различать такие
условные строки из вложенного набора внутри оператора if.
Приемлемые варианты в этой ситуации включают, но не ограничиваются:

# Без дополнительных отступов.
если (this_is_one_thing и
    that_is_another_thing):
    сделай что-нибудь()

# Добавить комментарий, который выделит редакторы
# поддержка подсветки синтаксиса.если (this_is_one_thing и
    that_is_another_thing):
    # Поскольку оба условия верны, мы можем заморозить.
    сделай что-нибудь()

# Добавить дополнительный отступ в условную строку продолжения.
если (this_is_one_thing
        and that_is_another_thing):
    сделай что-нибудь()
 

(Также см. Обсуждение того, следует ли разбивать до или после двоичного
операторов ниже.)

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

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
результат = some_function_that_takes_arguments (
    'а', 'б', 'в',
    'd', 'e', ​​'f',
    )
 

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

my_list = [
    1, 2, 3,
    4, 5, 6,
]
результат = some_function_that_takes_arguments (
    'а', 'б', 'в',
    'd', 'e', ​​'f',
)
 

Пробелы — предпочтительный метод отступа.

Вкладки

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

Python 3 запрещает смешивать использование табуляции и пробелов для отступа.

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

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

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

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

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

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

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

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

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

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

с open ('/ path / to / some / file / you / want / to / read') как file_1, \
     open ('/ путь / к / некоторому / файлу / будет / записан', 'w') как файл_2:
    file_2.write (file_1.read ())
 

(см. Предыдущее обсуждение многострочных операторов if для дальнейшего
мысли об отступах таких многострочных операторов-операторов.)

Другой такой случай — с утверждениями.

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

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

# Неправильно:
# оператор находится далеко от своих операндов
доход = (валовая_ зарплата +
          taxable_interest +
          (дивиденды - qual_dividends) -
          ira_deduction -
          student_loan_interest)
 

Чтобы решить эту проблему удобочитаемости, математики и их издатели
следуйте противоположному соглашению.Дональд Кнут объясняет традиционные
правило в своей серии «Компьютеры и набор текста »: «Хотя формулы
внутри абзаца всегда разрыв после бинарных операций и отношений,
отображаемые формулы всегда прерываются перед бинарными операциями ».

Следуя традиции математики, обычно дает больше
читаемый код:

# Верный:
# легко сопоставить операторы с операндами
доход = (валовая_ зарплата
          + taxable_interest
          + (дивиденды - qual_dividends)
          - ira_deduction
          - student_loan_interest)
 

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

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

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

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

Осторожно используйте пустые строки в функциях для обозначения логических разделов.L) символ подачи формы как
пробел; Многие инструменты рассматривают эти символы как разделители страниц, поэтому
вы можете использовать их для разделения страниц связанных разделов вашего файла.
Обратите внимание: некоторые редакторы и веб-программы просмотра кода могут не распознавать
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 и более поздних версий предписана следующая политика для
стандартная библиотека (см. PEP 3131): все идентификаторы в Python
стандартная библиотека ДОЛЖНА использовать идентификаторы только ASCII и ДОЛЖНА использовать
Английские слова везде, где это возможно (во многих случаях сокращения и
используются не английские технические термины).Кроме того, строка
литералы и комментарии также должны быть в формате ASCII. Единственные исключения:
(a) тестовые примеры для тестирования функций, отличных от ASCII, и
(б) имена авторов. Авторы, чьи имена не основаны на
Латинский алфавит (latin-1, набор символов ISO / IEC 8859-1) ДОЛЖЕН обеспечивать
транслитерация их имен в этом наборе символов.

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

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

  # Верный:
  импорт ОС
  import sys
   

  # Неправильно:
  import sys, os
   

  Можно сказать так:

  # Верный:
  из подпроцесса импорта Popen, PIPE
   

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

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

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

  Между каждой группой импорта следует поместить пустую строку.

• Рекомендуется абсолютный импорт, так как они обычно более читабельны
  и, как правило, ведут себя лучше (или, по крайней мере, лучше ошибаются
  сообщения), если система импорта настроена неправильно (например,
  когда каталог внутри пакета попадает в sys.путь):

  import mypkg.sibling
  из mypkg import sibling
  из примера импорта mypkg.sibling
   

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

  от . импортный брат
  из примера импорта .sibling
   

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

  Неявный относительный импорт никогда не должен использоваться и был удален
  в Python 3.

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

  из myclass import MyClass
  из foo.bar.yourclass импортировать YourClass
   

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

  импортировать мой класс
  import foo.bar.yourclass
   

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

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

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

Модуль уровня «dunders» (т.е. имена с двумя ведущими и двумя конечными
подчеркивания), например __all__, __author__, __version__,
и т. д. следует размещать после строки документации модуля, но до любого импорта
выписки , кроме из импорта __future__. Python требует, чтобы
future-import должен появиться в модуле перед любым другим кодом, кроме
строки документации:

"" "Это пример модуля.

Этот модуль делает разные вещи.
"" "

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0,1'
__author__ = 'Кардинал Бигглс'

импорт ОС
import sys
 

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

# Верный:
ФАЙЛЫ = ('setup.cfg',)
 

# Неправильно:
FILES = 'setup.cfg',
 

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

# Верный:
ФАЙЛЫ = [
    'setup.cfg',
    'tox.ini',
    ]
инициализировать (ФАЙЛЫ,
           error = True,
           )
 

# Неправильно:
FILES = ['setup.cfg', 'tox.ini',]
инициализировать (ФАЙЛЫ, ошибка = True,)
 

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

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

Есть много разных стилей именования. Это помогает уметь
узнавать, какой стиль именования используется, независимо от того, какой
они используются для.

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

• b (одна строчная буква)

• B (одна заглавная буква)

• строчная

• lower_case_with_underscores

• ВЕРХНИЙ

• UPPER_CASE_WITH_UNDERSCORES

• CapitalizedWords (или CapWords, или CamelCase — так названо потому, что
  неровности букв).Это тоже иногда известно
  как StudlyCaps.

  Примечание. При использовании аббревиатур в CapWords все буквы
  буквы акронима. Таким образом, HTTPServerError лучше, чем
  HttpServerError.

• смешанный регистр (отличается от 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 (мастер, класс _ = 'ClassName')
   

• __double_leading_underscore: при именовании атрибута класса
  вызывает изменение имени (внутри класса FooBar __boo становится
  _FooBar__boo; Смотри ниже).

• __double_leading_and_trailing_underscore__: «магические» объекты или
  атрибуты, которые живут в пространствах имен, контролируемых пользователем.
  Например. __init__, __import__ или __file__. Никогда не изобретайте
  такие имена; используйте их только в соответствии с документацией.

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

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

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

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

Модули

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

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

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

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

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

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

Имена переменных типа

Имена переменных типа, представленные в PEP 484, обычно должны использовать CapWords
предпочитая короткие имена: T, AnyStr, Num.Рекомендуется добавить
суффиксы _co или _contra к переменным, используемым для объявления ковариантных
или контравариантное поведение соответственно:

от ввода import TypeVar

VT_co = TypeVar ('VT_co', ковариантный = Истина)
KT_contra = TypeVar ('KT_contra', контравариант = Истина)
 

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

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

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

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

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

Имена функций и переменных

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

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

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

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

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

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

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

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

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

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

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

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

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

Константы

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

Дизайн для наследования

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

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

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

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

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

• Открытые атрибуты не должны иметь начальных подчеркиваний.

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

  Примечание 1. См. Рекомендации по именам аргументов выше для методов класса.

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

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

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

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

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

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

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

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

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

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

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

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

Интерфейс также считается внутренним, если он содержит пространство имен
(пакет, модуль или класс) считается внутренним.

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

.