PEP 8: оформление
кода на Python

§1Что такое PEP и зачем PEP 8

PEP (Python Enhancement Proposal) — документ с предложением по развитию языка Python. У каждого PEP есть номер, автор и статус. PEP 8 написали Гвидо ван Россум, Барри Уорсо и Ник Коглан.

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

Интерпретатор PEP 8 не проверяет: программа с нарушениями запустится. Обязательным его делает проект — правилом в README, настройкой линтера и проверкой в CI, которая не пропускает изменение с нарушениями.

Сам PEP 8 разрешает отступать от правил, если правило ухудшает читаемость или ломает единообразие с уже написанным кодом. Раздел об этом называется «A Foolish Consistency is the Hobgoblin of Little Minds».

§2Отступы

Один уровень отступа — 4 пробела. Табуляцию не используют; смешивать табуляцию и пробелы в одном файле Python 3 запрещает.

def total(prices):
  result = 0
  for p in prices:
        result += p
  return result

def total(prices):
    result = 0
    for price in prices:
        result += price
    return result

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

result = send_report(user_id, period_start,
    period_end, include_archived)

# выравнивание по открывающей скобке
result = send_report(user_id, period_start,
                     period_end, include_archived)

# висячий отступ
result = send_report(
    user_id, period_start,
    period_end, include_archived,
)

def create_ticket(
    title, description,
    priority, author):
    validate(title)
    return save(title)

def create_ticket(
        title, description,
        priority, author):
    validate(title)
    return save(title)

§3Длина строки и перенос

Строка кода — не длиннее 79 символов, строка комментария или документации — не длиннее 72. Стандарт разрешает команде договориться о пределе до 99 символов для кода. Форматировщик black по умолчанию использует 88.

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

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

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)

if user.is_active and user.email_confirmed and not user.is_blocked and user.role in ('teacher', 'admin'):
    grant_access(user)

if (user.is_active
        and user.email_confirmed
        and not user.is_blocked
        and user.role in ('teacher', 'admin')):
    grant_access(user)

§4Пустые строки и кодировка

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

import os
def load(path):
    return open(path).read()
class Report:
    def __init__(self, title):
        self.title = title
    def render(self):
        return self.title.upper()

import os


def load(path):
    return open(path).read()


class Report:
    def __init__(self, title):
        self.title = title

    def render(self):
        return self.title.upper()

Файлы сохраняют в UTF-8; строку с указанием кодировки в начале файла для UTF-8 не пишут. Имена в коде — латиницей, даже если комментарии на русском.

§5Импорты

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

from .models import Ticket
import os, sys
import requests
from datetime import date
from fastapi import FastAPI
from .db import *

import os
import sys
from datetime import date

import requests
from fastapi import FastAPI

from .db import get_session
from .models import Ticket

Импорт со звёздочкой from module import * не используют: непонятно, какие имена появились в модуле, и одно из них может незаметно заменить другое. Абсолютные импорты предпочтительнее относительных. Порядок импортов расставляет isort или ruff с правилом I.

§6Пробелы в выражениях

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

spam( ham[ 1 ], { eggs: 2 } )
print (x , y)
dct ['key'] = lst [index]
if x == 4 : print(x , y)

spam(ham[1], {eggs: 2})
print(x, y)
dct['key'] = lst[index]
if x == 4:
    print(x, y)

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

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

def connect(host, port = 5432, timeout = 30):
    ...

connect(host = 'db', port = 6432)

def munge(sep:str='-', limit: int=10):
    ...

def connect(host, port=5432, timeout=30):
    ...

connect(host='db', port=6432)

def munge(sep: str = '-', limit: int = 10):
    ...

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

§7Висячая запятая

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

FILES = [
    'setup.cfg',
    'tox.ini'
    ]

FILES = [
    'setup.cfg',
    'tox.ini',
]

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

§8Комментарии

Комментарий объясняет, почему код написан так. Пересказывать, что делает код, не нужно: это видно из самого кода. Комментарий начинается с # и пробела. Комментарий в конце строки отделяют от кода минимум двумя пробелами. PEP 8 считает комментарий, который расходится с кодом, хуже отсутствия комментария, поэтому при изменении кода комментарий исправляют тоже.

x = x + 1 # прибавить единицу
retries=3#число попыток

x = x + 1  # компенсация рамки: ширина считается без неё
retries = 3  # провайдер разрывает соединение после 3 ошибок

#проверяем дубли
#потому что форма не проверяет
if exists(email):
    raise DuplicateEmail(email)

# Форма регистрации не проверяет, занята ли почта (задача #198),
# поэтому повтор отсекается здесь, до записи в базу.
if exists(email):
    raise DuplicateEmail(email)

§9Имена

class ticket_repo:
    def LoadAll(self):
        l = []
        for O in self.Items:
            l.append(O)
        return l

MaxRetries = 3

class TicketRepository:
    def load_all(self):
        tickets = []
        for ticket in self.items:
            tickets.append(ticket)
        return tickets

MAX_RETRIES = 3

def count(list, id, type):
    return len([x for x in list if x.type == type])

def count(items, item_id, kind):
    return len([x for x in items if x.kind == kind])

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

Последний раздел PEP 8 посвящён приёмам, при которых код ведёт себя предсказуемо.

if result == None:
    ...
if is_active == True:
    ...
if len(tickets) == 0:
    ...

if result is None:
    ...
if is_active:
    ...
if not tickets:
    ...

if type(price) == int:
    ...

if isinstance(price, int):
    ...

if filename[-4:] == '.csv':
    ...
if url[:8] == 'https://':
    ...

if filename.endswith('.csv'):
    ...
if url.startswith('https://'):
    ...

try:
    rows = load(path)
except:
    rows = []

try:
    rows = load(path)
except FileNotFoundError:
    rows = []

try:
    value = collection[key]
    result = handle(value)
except KeyError:
    result = key_not_found(key)

try:
    value = collection[key]
except KeyError:
    result = key_not_found(key)
else:
    result = handle(value)

def discount(user):
    if user.is_student:
        return 0.2
    if user.is_teacher:
        return 0.1

def discount(user):
    if user.is_student:
        return 0.2
    if user.is_teacher:
        return 0.1
    return 0.0

square = lambda x: x * x

def square(x):
    return x * x

f = open('report.csv')
data = f.read()
f.close()

with open('report.csv', encoding='utf-8') as f:
    data = f.read()

§11Разбор файла целиком

Ниже — файл, собранный «на скорую руку», и тот же файл после приведения к PEP 8. Поведение программы не изменилось.

import os,sys
from datetime import *
import requests
def MakeReport( Users,Date ):
    l=[]
    for u in Users :
        if u['active']==True and u['email']!=None:
            l.append( u['name']+' '+u['email'] ) # добавить
    try:
        r=requests.post('https://api.example/report',json={'rows':l,'date':str(Date)})
    except:
        return None
    return r.status_code

import requests

REPORT_URL = 'https://api.example/report'


def make_report(users, report_date):
    """Отправить список активных пользователей с почтой; вернуть код ответа."""
    rows = [
        f"{user['name']} {user['email']}"
        for user in users
        if user['active'] and user['email'] is not None
    ]
    payload = {'rows': rows, 'date': report_date.isoformat()}
    try:
        response = requests.post(REPORT_URL, json=payload, timeout=10)
    except requests.RequestException:
        return None
    return response.status_code

§12Как проверяют соответствие

Вручную PEP 8 не проверяют: это делают программы. Линтер находит нарушения и называет их кодом. Форматировщик сам переписывает оформление.

Проверку включают в CI: изменение, которое не проходит линтер, не сливают в основную ветку. Настройки хранят в pyproject.toml, чтобы у всех участников они были одинаковыми.

[tool.ruff]
line-length = 88

[tool.ruff.lint]
select = ["E", "W", "F", "I", "N"]   # оформление, ошибки, импорты, имена