Python PEP 8 编码规范实战指南

行长度：79 字符的智慧

PEP 8 建议每行不超过 79 个字符，注释和文档字符串不超过 72 个字符。

虽然现代显示器很宽，但这个限制仍有价值：并排查看代码时更方便，避免过度嵌套，提高专注度。

# ✅ 合理拆分长行
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())

# ✅ 使用括号隐式续行
result = (
    very_long_variable_name + another_long_variable_name - yet_another_long_name
)

空行：代码的段落

空行就像文章的段落分隔，让代码结构清晰：

# ✅ 正确的空行使用
import os
import sys
from typing import List, Dict


class DataProcessor:
    """数据处理器类"""

    def __init__(self, data: List[Dict]):
        self.data = data
        self.processed = False

    def process(self):
        """处理数据"""
        for item in self.data:
            self._validate(item)
            self._transform(item)
        self.processed = True

    def _validate(self, item: Dict):
        """验证数据项"""
        if not item.get('id'):
            raise ValueError("Missing id")

    def _transform(self, item: Dict):
        """转换数据项"""
        item['processed'] = True


def main():
    """主函数"""
    processor = DataProcessor([])
    processor.process()


if __name__ == '__main__':
    main()

空行规则：

• 顶层函数和类定义之间：2 个空行
• 类内方法之间：1 个空行
• 函数内逻辑块之间：1 个空行（谨慎使用）

导入语句：井然有序

导入语句应该放在文件开头，按以下顺序分组：

# ✅ 正确的导入顺序
# 1. 标准库
import os
import sys
from datetime import datetime

# 2. 第三方库
import numpy as np
import pandas as pd
from flask import Flask, request

# 3. 本地应用/库
from myapp.models import User
from myapp.utils import helper

# ❌ 错误：多个导入在一行
import os, sys

# ❌ 错误：使用通配符导入
from module import *

为什么避免通配符导入？

# ❌ 问题代码
from math import *
from numpy import *
# 现在 sqrt 来自哪里？math 还是 numpy？
result = sqrt(16)

# ✅ 明确的导入
from math import sqrt as math_sqrt
from numpy import sqrt as np_sqrt
result = math_sqrt(16)
# 清晰明了

命名规范：见名知意

命名是编程中最难的事情之一，PEP 8 提供了清晰的指导：

不同类型的命名风格

# ✅ 变量和函数：snake_case
user_name = "Alice"

def calculate_total_price():
    pass

# ✅ 类名：PascalCase
class UserProfile:
    pass

class HTTPConnection:
    pass

# ✅ 常量：UPPER_CASE
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30

# ✅ 私有变量/方法：前导下划线
class BankAccount:
    def __init__(self):
        self._balance = 0  # 受保护的
        self.__secret_key = "xxx"  # 私有的

    def _internal_method(self):
        pass

# ❌ 错误：混用风格
userName = "Alice"  # 这是 JavaScript 风格

def CalculateTotal():  # 函数不应该用 PascalCase
    pass

命名的艺术

好的命名应该描述性强，避免单字母变量（除了循环计数器），布尔值用 is/has 前缀。

# ✅ 描述性强
def get_user_by_email(email: str) -> User:
    pass

# ❌ 过于简短
def get(e):
    pass

# ✅ 布尔值用 is/has 前缀
is_active = True
has_permission = False

# ✅ 避免单字母变量（除了循环计数器）
for i in range(10):
    pass

# ❌ 不要用 l, O 作为变量名（容易混淆）
l = 1  # 看起来像 1
O = 0  # 看起来像 0

表达式和语句中的空格

空格的使用直接影响代码的可读性：

# ✅ 正确的空格使用
spam(ham[1], {eggs: 2})
x = 1
y = 2
long_variable = 3
if x == 4:
    print(x, y)
dict_value = {'key': 'value'}
list_slice = my_list[1:3]

# ❌ 错误的空格使用
spam( ham[1], { eggs:2})  # 括号内多余空格
x=1  # 赋值号两边缺少空格
y = 2
if x==4:  # 比较运算符两边缺少空格
    print(x , y)  # 函数名和括号之间不应有空格
dict_value = {'key':'value'}  # 冒号前不应有空格
list_slice = my_list[1:3]  # 切片冒号两边不应有空格

运算符优先级与空格

# ✅ 用空格突出优先级
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)

注释：代码的说明书

注释的黄金法则

注释应该解释'为什么'，而不是'是什么'

# ❌ 无用的注释
x = x + 1  # 给 x 加 1

# ✅ 有价值的注释
x = x + 1  # 补偿边界条件的偏移

# ❌ 显而易见的注释
# 创建用户对象
user = User(name="Alice")

# ✅ 解释业务逻辑
# 新用户默认获得 100 积分作为欢迎奖励
user = User(name="Alice", points=100)

块注释与行内注释

# ✅ 块注释：解释下面的代码块
# 使用二分查找算法提高搜索效率
# 前提条件：列表必须已排序
def binary_search(arr, target):
    left, right = 0, len(arr) - 1
    while left <= right:
        mid = (left + right) // 2
        if arr[mid] == target:
            return mid
        elif arr[mid] < target:
            left = mid + 1
        else:
            right = mid - 1
    return -1

# ✅ 行内注释：谨慎使用，至少两个空格分隔
x = x + 1  # 边界补偿

# ❌ 行内注释过长
x = x + 1  # 这里加 1 是因为我们需要补偿某些边界条件下的偏移量，这个问题在之前的版本中导致了 bug

文档字符串（Docstring）

文档字符串是 Python 的特色，用三引号包裹：

# ✅ 单行文档字符串
def square(n):
    """返回 n 的平方。"""
    return n * n

# ✅ 多行文档字符串
def complex_function(param1, param2, param3=None):
    """执行复杂的数据处理操作。
    这个函数会对输入数据进行多步处理，包括验证、转换和聚合。
    适用于需要批量处理用户数据的场景。
    Args:
        param1 (str): 用户标识符，必须是有效的 UUID
        param2 (list): 待处理的数据列表
        param3 (dict, optional): 额外的配置选项。默认为 None
    Returns:
        dict: 包含处理结果的字典，格式为：
         {'success': bool, 'data': list, 'errors': list}
    Raises:
        ValueError: 当 param1 不是有效的 UUID 时
        TypeError: 当 param2 不是列表时
    Examples:
        >>> result = complex_function('uuid-123', [1, 2, 3])
        >>> result['success']
        True
    """
    pass

编程建议：写出 Pythonic 的代码

比较操作

# ✅ 使用 is 比较单例对象
if value is None:
    pass
if value is not None:
    pass

# ❌ 不要用 == 比较 None
if value == None:
    pass

# ✅ 检查空序列
if not my_list:
    print("列表为空")

# ❌ 不要用 len() 检查空序列
if len(my_list) == 0:
    print("列表为空")

# ✅ 布尔值比较
if is_valid:
    pass

# ❌ 不要显式比较 True/False
if is_valid == True:
    pass

使用上下文管理器

# ✅ 使用 with 语句
with open('file.txt', 'r') as f:
    content = f.read()

# ❌ 手动管理资源
f = open('file.txt', 'r')
content = f.read()
f.close()
# 容易忘记，或者在异常时不执行

异常处理

# ✅ 捕获具体的异常
try:
    value = int(user_input)
except ValueError:
    print("请输入有效的数字")

# ❌ 捕获所有异常
try:
    value = int(user_input)
except:
    print("出错了")

# ✅ 使用 else 和 finally
try:
    file = open('data.txt')
except FileNotFoundError:
    print("文件不存在")
else:
    # 只在没有异常时执行
    data = file.read()
    file.close()
finally:
    # 无论如何都会执行
    print("操作完成")

字符串操作

# ✅ 使用 startswith/endswith
if filename.endswith('.py'):
    pass

# ❌ 使用切片
if filename[-3:] == '.py':
    pass

# ✅ 使用 join 连接字符串
result = ', '.join(items)

# ❌ 使用 + 连接多个字符串
result = items[0] + ', ' + items[1] + ', ' + items[2]

# ✅ 使用 f-string（Python 3.6+）
message = f"Hello, {name}! You have {count} messages."

# ✅ 或使用 format
message = "Hello, {}! You have {} messages.".format(name, count)

# ❌ 使用 % 格式化（旧式）
message = "Hello, %s! You have %d messages." % (name, count)

类型注解：现代 Python 的标配

虽然 PEP 8 诞生时还没有类型注解，但现代 Python 开发强烈推荐使用：

from typing import List, Dict, Optional, Union

# ✅ 清晰的类型注解
def process_users(
    users: List[Dict[str, str]],
    max_count: int = 100,
    filter_active: bool = True
) -> List[str]:
    """处理用户列表并返回用户名。
    Args:
        users: 用户字典列表
        max_count: 最大处理数量
        filter_active: 是否只处理活跃用户
    Returns:
        用户名列表
    """
    result: List[str] = []
    for user in users[:max_count]:
        if filter_active and not user.get('active'):
            continue
        result.append(user['name'])
    return result

# ✅ Optional 表示可能为 None
def find_user(user_id: int) -> Optional[Dict[str, str]]:
    # 可能返回 None
    return None

# ✅ Union 表示多种类型
def parse_value(value: Union[int, str, float]) -> float:
    return float(value)

工具链：自动化代码规范

手动检查代码风格效率低下，使用工具可以事半功倍：

1. Black - 代码格式化工具

# 安装
pip install black

# 格式化单个文件
black script.py

# 格式化整个项目
black .

# 检查但不修改
black --check .

Black 的哲学是'零配置'，自动将代码格式化为符合 PEP 8 的风格。

2. Flake8 - 代码检查工具

# 安装
pip install flake8

# 检查代码
flake8 script.py

# 检查整个项目
flake8 .

# 配置文件 .flake8
[flake8]
max-line-length = 88
exclude = .git,__pycache__,venv
ignore = E203, W503

3. isort - 导入排序工具

# 安装
pip install isort

# 排序导入
isort script.py

# 检查但不修改
isort --check-only .

4. pylint - 全面的代码分析工具

# 安装
pip install pylint

# 分析代码
pylint script.py

# 生成配置文件
pylint --generate-rcfile > .pylintrc

集成到开发流程

在 pyproject.toml 中配置：

[tool.black]
line-length = 88
target-version = ['py38', 'py39', 'py310']

[tool.isort]
profile = "black"
line_length = 88

[tool.pylint.messages_control]
disable = "C0330, C0326"

[tool.pylint.format]
max-line-length = 88

在 Git 提交前自动检查（使用 pre-commit）：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/psf/black
    rev: 23.3.0
    hooks:
      - id: black
  - repo: https://github.com/pycqa/isort
    rev: 5.12.0
    hooks:
      - id: isort
  - repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

何时打破规则？

PEP 8 开篇就说明：

'A Foolish Consistency is the Hobgoblin of Little Minds'

愚蠢的一致性是头脑狭隘的表现

以下情况可以不遵循 PEP 8：

特定领域的约定

# 科学计算中常用单字母变量
import numpy as np

# 这在数学上下文中是可以接受的
def distance(x1, y1, x2, y2):
    return np.sqrt((x2 - x1)**2 + (y2 - y1)**2)

向后兼容性

修改旧代码可能引入风险，此时保持一致性更重要。

与周围代码保持一致

如果现有代码库使用不同的风格，保持一致比强行统一更好。

遵循规则会降低可读性

有时超过 79 字符更清晰：

raise ValueError("This is a very long error message that explains exactly what went wrong")

总结

PEP 8 的目标是让代码更易读、更易维护、更专业。

记住以下核心要点：

• 使用 4 个空格缩进
• 每行不超过 79 个字符
• 函数和类之间用空行分隔
• 导入语句要有序
• 命名要有意义且一致
• 注释解释'为什么'而不是'是什么'
• 使用工具自动化检查

官方参考：https://peps.python.org/pep-0008/