pep 8 是协作接口而非审美选择，其缩进、命名（snake_case）、行宽（88）、多行参数格式、类型提示（含optional/union规范）、常量抽取（upper_snake_case）、pathlib路径拼接等规则，共同保障工具链兼容、代码可维护与团队高效协作。
PEP 8 不是审美选择，是协作接口
Python 的缩进、空格、换行、命名规则不是为了“好看”，而是让不同人写的代码在合并、审查、调试时能快速对齐语义。比如 def calculate_total_price(items: list) -> float: 和 def calculateTotalPrice(items:list)->float: 看似都能跑，但前者让 IDE 能准确跳转类型提示，后者会让 pylint 报 C0103（无效函数名），CI 流水线卡住——这不是风格问题，是工具链契约。
-
snake_case 是所有标准库、主流包（requests、pytest）的默认约定，硬改会增加阅读负担
-
max_line_length=88（而非 79）是 black 默认值，它直接决定自动格式化是否和团队已有代码兼容
- 多行参数必须每项独占一行 + 尾随逗号，否则 git diff 会污染整行，掩盖真实修改
类型提示写不全，等于没写def process(data) 这种签名在半年后连你自己都得看三遍实现才能猜出 data 是 dict 还是 pd.DataFrame。而 def process(data: dict[str, float]) -> list[Path]: 让 mypy 在编辑器里实时报错，也避免传入 None 导致运行时崩溃。
- 必须标注
Optional，Union 要用 |（Python 3.10+）或 typing.Union（旧版本），混用会导致 mypy 静默失败
- 类型别名要提前定义：
UserId = NewType("UserId", int)，而不是到处写 int，否则改 ID 类型时得 grep 全局
- 第三方类型（如
pd.DataFrame）必须用 from <strong>future</strong> import annotations 延迟求值，否则导入失败
魔法字符串和硬编码路径是维护黑洞"config.yaml"、"user_data_v2"、42 这类字面量一旦散落在 5 个文件里，改配置名就得手动搜替换，漏一个就出生产事故。
- 所有常量提成模块级
UPPER_SNAKE_CASE 变量，放在 constants.py 或 settings.py
- 路径拼接必须用
pathlib.Path：DATA_DIR / "raw" / f"{date}.csv"，不用 os.path.join 或字符串 +
- 配置文件名、环境变量前缀、API 超时时间等，全部集中管理，哪怕只有两处用到也要抽离
snake_case 是所有标准库、主流包（requests、pytest）的默认约定，硬改会增加阅读负担 max_line_length=88（而非 79）是 black 默认值，它直接决定自动格式化是否和团队已有代码兼容 def process(data) 这种签名在半年后连你自己都得看三遍实现才能猜出 data 是 dict 还是 pd.DataFrame。而 def process(data: dict[str, float]) -> list[Path]: 让 mypy 在编辑器里实时报错，也避免传入 None 导致运行时崩溃。
- 必须标注
Optional，Union要用|（Python 3.10+）或typing.Union（旧版本），混用会导致mypy静默失败 - 类型别名要提前定义：
UserId = NewType("UserId", int)，而不是到处写int，否则改 ID 类型时得 grep 全局 - 第三方类型（如
pd.DataFrame）必须用from <strong>future</strong> import annotations延迟求值，否则导入失败
魔法字符串和硬编码路径是维护黑洞"config.yaml"、"user_data_v2"、42 这类字面量一旦散落在 5 个文件里，改配置名就得手动搜替换，漏一个就出生产事故。
- 所有常量提成模块级
UPPER_SNAKE_CASE 变量，放在 constants.py 或 settings.py
- 路径拼接必须用
pathlib.Path：DATA_DIR / "raw" / f"{date}.csv"，不用 os.path.join 或字符串 +
- 配置文件名、环境变量前缀、API 超时时间等，全部集中管理，哪怕只有两处用到也要抽离
UPPER_SNAKE_CASE 变量，放在 constants.py 或 settings.py pathlib.Path：DATA_DIR / "raw" / f"{date}.csv"，不用 os.path.join 或字符串 + 复杂点在于：类型提示和常量抽取看似增加初期编码量，但真正拖慢迭代的从来不是多敲几行，而是每次改逻辑前，得花 20 分钟确认“这个 status 字段到底可能取哪些值”。
