python基础入门：附录：PEP8编码规范与代码格式化（Black工具）

Python代码风格与格式化权威指南：从PEP8到自动化实践

一、PEP8核心规范精要

1. 命名规范矩阵

2. 布局与格式规范

# ✅ 正确示范
def complex_function(
    param1: int,
    param2: str,
    *,
    verbose: bool = False
) -> tuple:
    """函数文档字符串示例
  
    Args:
        param1: 整型参数描述
        param2: 字符串参数描述
        verbose: 控制详细输出
      
    Returns:
        包含处理结果的元组
    """
    if verbose:
        print(f"Processing {
     
     param2}")
      
    result = (param1 * 2, param2.upper())
    return result

# ❌ 常见错误
class badExample:
    def __init__(self,a,b):  # 缺少空格
        self.a =a  # 运算符间距错误
        self.b= b
    def Calculate(self):  # 方法命名不规范
        return self.a+self.b  # 运算符间距

3. 行长度与换行策略

# 优先使用括号隐式续行
result = (
    some_long_calculation()
    + another_function()
    - correction_factor
)

# 函数参数换行规范
def process_data(
    input_file: Path,
    output_dir: Optional[Path] = None,
    *,
    chunk_size: int = 1024,
    encoding: str = "utf-8"
) -> list[dict]:
    # 处理逻辑...

二、Black格式化工具实战

1. 基础配置与使用

# 安装最新版
$ pip install black

# 基础格式化命令
$ black .  # 格式化当前目录所有文件

# 常用参数组合
$ black --line-length 120 --skip-string-normalization src/

# 差异检查模式（不实际修改）
$ black --check --diff .

2. 配置文件示例（pyproject.toml）

[tool.black]
line-length = 100
target-version = ['py311']
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | \.venv
  | build
  | dist
)/
'''

3. 与预提交钩子集成

# .pre-commit-config.yaml
repos:
- repo: https://github.com/psf/black
  rev: 23.3.0
  hooks:
    - id: black
      args: [--config=./pyproject.toml]

4. 特殊处理技巧

# 使用# fmt: off临时禁用格式化
# fmt: off
matrix = [
    [1, 0, 0],
    [0, 1, 0],
    [0, 0, 1],
]  # 保持矩阵格式
# fmt: on

# 字符串规范化控制
$ black --skip-string-normalization .  # 保留原始引号风格

三、多工具集成方案