PEP 8 官方风格指南全文精读:Python 代码规范、命名约定与 LlamaIndex 实践

原创2026-10-15 12:42:491,817 阅读
文章标签:示例工程

PEP 8 官方风格指南全文精读:Python 代码规范、命名约定与 LlamaIndex 实践

本文以开源仓库 materials 中 python-llamaindex/data/pep8.rst 所收录的 PEP 8 官方全文为骨架,系统梳理 Python 官方代码风格指南的核心规则:代码布局、缩进与空行、导入规范、空白符用法、注释与文档字符串、命名约定以及编程建议;同时结合该仓库中 python-llamaindex 的 LlamaIndex RAG 示例,说明如何以这份规范文档作为知识库语料,构建可检索、可问答的风格指南问答系统。读完本文,你既能完整掌握 PEP 8 的可执行规范细节,也能在本地复现一套针对"Python 编码规范"的检索问答流水线。

背景:这份 PEP 8 文档在仓库中的角色

PEP 8(Style Guide for Python Code)由 Guido van Rossum、Barry Warsaw 与 Alyssa Coghlan 共同撰写,2001-07-05 创建,2013-08-01 更新,当前状态为 Active,类型为 Process,主要面向 Python 标准库代码,同时被整个 Python 社区广泛采用(详见 python-llamaindex/data/pep8.rst 头部元信息)。

在 materials 仓库中,这份文档被作为 LlamaIndex 教程的知识库语料存放于 python-llamaindex/data/pep8.rst。仓库的多个脚本都通过 SimpleDirectoryReader(input_files=["./data/pep8.rst"]) 读取它并构建索引,例如:

  • documents.py —— 最简读取:加载文档并打印第一段文本;
  • demo.py —— 构建 VectorStoreIndex 并执行 "What is this document about?" 查询;
  • single_query.py —— 带磁盘持久化的索引复用版本(storage 目录);
  • indices.py —— 同时构建 VectorStoreIndex、SummaryIndex、TreeIndex 三种索引并对比回答;
  • async_query.py —— 用 asyncio.gather 并发执行多个查询;
  • demo_ollama.py、demo_google.py、demo_gpt5.py —— 分别演示 Ollama、Google GenAI、GPT-5.1 等不同 LLM/Embedding 组合。

因此,理解这份文档内容的同时,也可以把它当作"如何用 RAG 检索一份大型规范文档"的实践样本:风格指南规则细节繁多、难以凭记忆全量覆盖,正适合做成可问答的知识库。

总纲:一致性的价值与何时可以打破规则

PEP 8 开篇提出了贯穿全文的核心理念:代码被阅读的次数远多于被编写的次数(呼应 PEP 20 的 "Readability counts")。风格指南的本质是追求一致性,其优先级排序为:

  1. 与本风格指南一致;
  2. 与所在项目一致(更重要);
  3. 与单个模块或函数内部保持一致(最重要)。

PEP 8 同时明确给出允许打破规则的场景(不要为了合规而破坏向后兼容):

  1. 遵守规则反而让代码更难读时;
  2. 为与周边已打破该规则的代码保持一致时(顺带说明这也是清理历史代码的机会);
  3. 代码早于该规则出现、且没有理由去改动它时;
  4. 需要兼容不支持该特性推荐的旧版 Python 时。

文中反复强调:"A Foolish Consistency is the Hobgoblin of Little Minds"(愚蠢的一致性是小心灵的妖怪)——规则服务于可读性,拿不准时多看示例、多请教。

代码布局(Code Lay-out)

缩进:4 空格与对齐方式

  • 每个缩进层级使用 4 个空格;
  • 续行优先利用括号、方括号、花括号内的隐式续行来对齐包裹元素,或使用悬挂缩进(hanging indent,即除首行外全部缩进的一种排版方式,定义见原文脚注)。

推荐写法(垂直对齐 / 增加一级缩进 / 悬挂缩进):

# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
                         var_three, var_four)

# Add 4 spaces (an extra level of indentation) to distinguish arguments from the rest.
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)

# Hanging indents should add a level.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

不推荐写法:

# Arguments on first line forbidden when not using vertical alignment.
foo = long_function_name(var_one, var_two,
    var_three, var_four)

# Further indentation required as indentation is not distinguishable.
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

其中"4 空格规则"对续行是可选的——悬挂缩进也可以缩进到 4 空格以外的其他深度。

多行 if 语句的缩进冲突:当 if 条件跨行时,if 关键字 + 空格 + 左括号天然形成 4 空格缩进,与 if 内部代码块的自然 4 空格缩进产生视觉冲突。PEP 8 明确不强制立场,给出的可选方案包括:不加额外缩进、加注释区分、或给条件续行增加额外缩进:

# No extra indentation.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()

# Add a comment, which will provide some distinction in editors
# supporting syntax highlighting.
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()

# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

多行结构的闭合符位置有两种都可接受:对齐到列表最后一行第一个非空白字符,或对齐到多行结构起始行的第一个字符:

my_list = [
    1, 2, 3,
    4, 5, 6,
    ]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
    )
my_list = [
    1, 2, 3,
    4, 5, 6,
]
result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

制表符还是空格?

  • 空格是首选的缩进方式;
  • 制表符只应在与既有制表符缩进代码保持一致时使用;
  • Python 禁止混用制表符和空格进行缩进。

最大行长:79/72/99

  • 所有行限制为 79 字符以内;
  • 对结构约束较少的文本块(docstring 或注释),行宽限制为 72 字符;
  • 若团队内部达成一致,可放宽到 99 字符,但注释和 docstring 仍应限制在 72 字符;
  • Python 标准库保持保守:代码 79、文档字符串/注释 72。

设置这些上限的原因:限制编辑器窗口宽度便于并排打开多个文件,也便于代码评审工具并排展示两个版本;大多数工具在 80 列窗口下换行会破坏代码视觉结构。

换行首选隐式续行:长行应通过把表达式包进括号来跨行,优先于使用反斜杠 \ 续行。反斜杠在特定场景仍适用,例如 Python 3.10 之前多个 with 语句无法使用隐式续行:

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())

assert 语句的反斜杠续行同理;续行务必正确缩进。

二元运算符:断行应在运算符前还是后?

过去几十年推荐在二元运算符之后换行,但这样做有两个坏处:运算符散落在不同列上,且每个运算符远离其操作数,眼睛需要额外工作才能判断哪些项在相加、哪些在相减:

# Wrong: operators sit far away from their operands
income = (gross_wages +
          taxable_interest +
          (dividends - qualified_dividends) -
          ira_deduction -
          student_loan_interest)

数学排版传统相反——Donald Knuth 在 Computers and Typesetting 系列中指出:段落内公式在二元操作之后断行,而展示式公式总在二元操作之前断行。遵循数学传统通常更易读:

# Correct: easy to match operators with operands
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction
          - student_loan_interest)

PEP 8 的结论:运算符前后断行都允许,只要在局部保持一致;新代码建议采用 Knuth 风格(断在运算符前)。

空行

  • 顶层函数与类定义之间用 两行空行 分隔;
  • 类内部的方法定义之间用 一行空行 分隔;
  • 可以用(少量)额外空行把相关函数分组;成串的相关一行函数(如一组 dummy 实现)之间可省略空行;
  • 函数内部可少量使用空行表示逻辑分段;
  • Python 接受 ^L(control-L)换页符作为空白,许多工具将其视为分页符;但部分编辑器与网页代码查看器不能识别。

源文件编码

  • 核心 Python 发行版代码始终使用 UTF-8,且不写编码声明;
  • 标准库中非 UTF-8 编码仅用于测试目的;非 ASCII 字符应少用,最好只用于地名和人名;若将非 ASCII 字符作为数据,避免像 z̯̯͡a̧͎̺l̡͓̫g̹̲o̡̼̘ 这类噪声字符以及 BOM(字节序标记);
  • 标准库中所有标识符必须使用纯 ASCII,并尽量使用英文单词;
  • 面向全球受众的开源项目被鼓励采纳类似策略。

导入规范(Imports)

  • 导入通常每行一个:
# Correct:
import os
import sys

# Wrong:
import sys, os

但从同一模块导入多个名字时例外:

from subprocess import Popen, PIPE
  • 导入总是放在文件顶部:紧跟模块注释和 docstring 之后、模块级全局量与常量之前;
  • 导入分组顺序(组间留一个空行):
    1. 标准库导入;
    2. 相关的第三方导入;
    3. 本地应用/库特定导入。
  • 推荐绝对导入,通常更易读、错误消息更好;显式相对导入在复杂包布局中是可接受的替代(标准库应始终使用绝对导入):
import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

# acceptable explicit relative imports
from . import sibling
from .sibling import example
  • 从含类的模块导入类时,通常直接写:
from myclass import MyClass
from foo.bar.yourclass import YourClass

若导致本地名字冲突,则改为显式模块导入并使用限定名:

import myclass
import foo.bar.yourclass
# 使用 myclass.MyClass 与 foo.bar.yourclass.YourClass
  • 避免通配导入(from <module> import *):它使命名空间中存在哪些名字不清晰,让读者和自动化工具都困惑。唯一可辩护的用例是"重新发布内部接口为公共 API"(例如用可选加速模块的定义覆盖纯 Python 实现,且事先不知道具体覆盖哪些名字)。

模块级 Dunder 名字

模块级"dunder"(双下划线前后缀名字),如 __all__、__author__、__version__ 等,应放在模块 docstring 之后、任何导入语句之前(from __future__ 导入除外——Python 强制 future 导入必须出现在除 docstring 外的任何代码之前):

"""This is the example module.

This module does stuff.
"""

from __future__ import barry_as_FLUFL

__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'

import os
import sys

字符串引号

Python 中单引号与双引号字符串等价,PEP 8 不强制二选一,选定一种并坚持。当字符串内包含单引号或双引号时,使用另一种引号以避免转义反斜杠,提高可读性。三重引号字符串始终使用双引号,以与 PEP 257 的 docstring 约定保持一致。

表达式与语句中的空白符(Whitespace)

避免多余空白的情形(Pet Peeves)

  • 圆括号、方括号、花括号内侧:spam(ham[1], {eggs: 2})(正确)vs spam( ham[ 1 ], { eggs: 2 } )(错误);
  • 尾随逗号与闭合括号之间:foo = (0,)(正确)vs bar = (0, )(错误);
  • 逗号、分号、冒号之前:if x == 4: print(x, y); x, y = y, x(正确)vs if x == 4 : print(x , y) ; x , y = y , x(错误);
  • 切片中冒号例外:切片冒号类似最低优先级的二元运算符,两侧应有等量空白;扩展切片两个冒号间距相同;切片参数省略时省略空格:
# Correct:
ham[1:9], ham[1:9:3], ham[:9:3], ham[1::3], ham[1:9:]
ham[lower:upper], ham[lower:upper:], ham[lower::step]
ham[lower+offset : upper+offset]
ham[: upper_fn(x) : step_fn(x)], ham[:: step_fn(x)]
ham[lower + offset : upper + offset]

# Wrong:
ham[lower + offset:upper + offset]
ham[1: 9], ham[1 :9], ham[1:9 :3]
ham[lower : : step]
ham[ : upper]
  • 函数调用参数列表的左括号之前:spam(1)(正确)vs spam (1)(错误);
  • 索引/切片的左括号之前:dct['key'] = lst[index](正确)vs dct ['key'] = lst [index](错误);
  • 赋值运算符周围超过一个空格(对齐用):
# Correct:
x = 1
y = 2
long_variable = 3

# Wrong:
x             = 1
y             = 2
long_variable = 3

其他推荐

  • 任何地方避免行尾空白:它通常不可见,容易引发困惑(例如反斜杠后跟空格再加换行不构成续行标记);CPython 等许多项目的 pre-commit 钩子会拒绝这类提交;
  • 二元运算符两侧始终加单个空格:赋值 =、增强赋值 +=/-= 等、比较 ==/</>/!=/<=/>=/in/not in/is/is not、布尔 and/or/not;
  • 不同优先级运算符混用时,考虑在最低优先级运算符周围加空白;但永远不超过一个空格,且二元运算符两侧空白必须相等:
# Correct:
i = i + 1
submitted += 1
x = x*2 - 1
hypot2 = x*x + y*y
c = (a+b) * (a-b)

# Wrong:
i=i+1
submitted +=1
x = x * 2 - 1
hypot2 = x * x + y * y
c = (a + b) * (a - b)
  • 函数注解遵循冒号常规规则,-> 箭头两侧若有则必须有空格:
# Correct:
def munge(input: AnyStr): ...
def munge() -> PosInt: ...

# Wrong:
def munge(input:AnyStr): ...
def munge()->PosInt: ...
  • 关键字参数或未注解函数参数默认值处的 = 两侧不加空格;但当参数同时有注解与默认值时,= 两侧要加空格:
# Correct:
def complex(real, imag=0.0):
    return magic(r=real, i=imag)

# Wrong:
def complex(real, imag = 0.0):
    return magic(r = real, i = imag)

# Correct (annotated + default):
def munge(sep: AnyStr = None): ...
def munge(input: AnyStr, sep: AnyStr = None, limit=1000): ...

# Wrong:
def munge(input: AnyStr=None): ...
def munge(input: AnyStr, limit = 1000): ...
  • 复合语句(同一行多条语句)通常不鼓励:
# Correct:
if foo == 'blah':
    do_blah_thing()
do_one()
do_two()
do_three()

# Wrong:
if foo == 'blah': do_blah_thing()
do_one(); do_two(); do_three()

小主体的 if/for/while 偶尔可与正文同写一行,但绝不要在多子句语句(如 if/else、try/finally)上这样做,也不要折叠长行:

# Definitely not:
if foo == 'blah': do_blah_thing()
else: do_non_blah_thing()

try: something()
finally: cleanup()

do_one(); do_two(); do_three(long, argument,
                             list, like, this)

if foo == 'blah': one(); two(); three()

何时使用尾随逗号

尾随逗号通常可选,但构造单元素元组时强制要求,且建议用(技术上冗余的)括号包裹:

# Correct:
FILES = ('setup.cfg',)

# Wrong:
FILES = 'setup.cfg',

当尾随逗号冗余时,若列表/参数/导入项预期会随时间扩展,它往往很有帮助:每个值独占一行、总是加尾随逗号、闭合符放在下一行。但闭合定界符同一行的尾随逗号无意义(单元素元组除外):

# Correct:
FILES = [
    'setup.cfg',
    'tox.ini',
    ]
initialize(FILES,
           error=True,
           )

# Wrong:
FILES = ['setup.cfg', 'tox.ini',]
initialize(FILES, error=True,)

注释(Comments)

  • 与代码矛盾的注释比没有注释更糟;代码变更时务必同步更新注释;
  • 注释应是完整句子:首字母大写(除非是以小写字母开头的标识符——绝不改变标识符大小写);
  • 块注释由完整句子构成,每个句子以句号结尾;多句注释中句号后留一或两个空格(最后一句除外);
  • 确保注释对阅读者清晰易懂;非英语国家的 Python 开发者:除非 120% 确定代码不会被母语不同的人阅读,否则请用英文写注释。

块注释:适用于其后部分(或全部)代码,缩进到与代码相同层级;每行以 # 加一个空格开头(注释内缩进文本除外);段落之间用只含单个 # 的行分隔。

行内注释:尽量少用。行内注释是与语句同行的注释,与语句至少隔两个空格,以 # 加一个空格开头。陈述显而易见内容的行内注释是不必要的干扰:

# Wrong: states the obvious
x = x + 1                 # Increment x

# Correct: useful
x = x + 1                 # Compensate for border

文档字符串(Docstrings):完整约定见 PEP 257。要点:

  • 为所有公共模块、函数、类、方法写 docstring;非公共方法不必写,但应在 def 行后加注释说明其作用;
  • 多行 docstring 的结束 """ 应独占一行:
"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""
  • 单行 docstring 的结束 """ 留在同一行:
"""Return an ex-parrot."""

命名约定(Naming Conventions)

命名风格总览

PEP 8 区分的常见命名风格:

  • b(单个小写字母)、B(单个大写字母)、lowercase、lower_case_with_underscores、UPPERCASE、UPPER_CASE_WITH_UNDERSCORES;
  • CapitalizedWords(又称 CapWords、CamelCase、StudlyCaps)——注意:在 CapWords 中使用缩写时,缩写所有字母大写,即 HTTPServerError 优于 HttpServerError;
  • mixedCase(与 CapitalizedWords 的区别是首字母小写);
  • Capitalized_Words_With_Underscores("丑陋",应避免)。

此外还有用短唯一前缀分组相关名字的风格(如 os.stat() 返回的 st_mode、st_size、st_mtime)。X11 用前缀 X,而 Python 中属性/方法名带对象前缀、函数名带模块前缀,通常无需这种前缀。

下划线特殊形式:

  • _single_leading_underscore:弱"内部使用"标记(如 from M import * 不会导入下划线开头的名字);
  • single_trailing_underscore_:避免与 Python 关键字冲突的约定用法,如 tkinter.Toplevel(master, class_='ClassName');
  • __double_leading_underscore:用于类属性时触发名字改写(name mangling),在类 FooBar 内部 __boo 变成 _FooBar__boo;
  • __double_leading_and_trailing_underscore__:"魔法"对象/属性(如 __init__、__import__、__file__),绝不要发明这类名字,只按文档使用。

各类名字的具体约定

  • 要避免的名字:绝不使用 l(小写 el)、O(大写 oh)、I(大写 eye)作为单字符变量名——某些字体下它们与数字 1 和 0 难以区分;必须用 l 时改用 L;
  • ASCII 兼容性:标准库标识符必须兼容 ASCII(依据 PEP 3131 的策略规范);
  • 包与模块名:模块名应短小、全小写,必要时可用下划线改善可读性;包名也应短小、全小写,但不鼓励使用下划线。C/C++ 扩展模块若配有提供更高级接口的 Python 模块,C/C++ 模块以前导下划线命名(如 _socket);
  • 类名:通常用 CapWords 约定;若接口以可调用为主且有文档,也可使用函数命名约定;内置名字大多为单个单词(或两个连写单词),CapWords 仅用于异常名与内置常量;
  • 类型变量名(PEP 484):通常用 CapWords 并偏好短名:T、AnyStr、Num;建议为协变/逆变变量加 _co/_contra 后缀:
from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)
  • 异常名:异常是类,适用类命名约定;若异常确实是错误,名字加 "Error" 后缀;
  • 全局变量名:约定与函数相同;为 from M import * 设计的模块应使用 __all__ 机制阻止导出全局量,或用前导下划线标注"模块非公共";
  • 函数与变量名:函数名全小写,必要时用下划线分词;变量名同函数名;mixedCase 仅在已是流行风格的上下文(如 threading.py)中为保持向后兼容而允许;
  • 函数与方法参数:实例方法第一参数始终用 self;类方法第一参数始终用 cls;参数名与保留字冲突时,优先加单个尾随下划线而非缩写或拼写变形(class_ 优于 clss,最好用同义词规避冲突);
  • 方法名与实例变量:遵循函数命名规则(小写 + 下划线分词);非公共方法/实例变量用一个前导下划线;为避免与子类名字冲突用两个前导下划线触发名字改写——类 Foo 的属性 __a 无法通过 Foo.__a 访问(执着的调用者可访问 Foo._Foo__a)。双前导下划线一般只用于"设计为可被继承"的类中避免属性冲突;
  • 常量:通常在模块级定义,全大写 + 下划线分词,如 MAX_OVERFLOW、TOTAL。

面向继承的设计(Designing for Inheritance)

  • 总是决定类的属性(方法 + 实例变量)是公共还是非公共;拿不准时选非公共——把非公共改为公共容易,反之则难;
  • 公共属性:期望无关客户端使用、承诺避免破坏性变更;非公共属性:不供第三方使用、不做任何不变更或删除的保证;
  • Python 中没有真正"私有"(不做额外努力的话),所以 PEP 8 不用 "private" 一词;
  • 还有"子类 API"(其他语言常称 "protected")这一类别:设计可继承类时,要明确哪些属性属于公共、哪些属于子类 API、哪些仅限基类使用。

具体指导:

  • 公共属性无前导下划线;
  • 公共属性名与保留字冲突时追加尾随下划线(但 cls 仍是已知为类对象的变量/参数的推荐拼写,尤其是类方法第一参数);
  • 简单公共数据属性直接暴露属性名即可,不要写复杂的访问器/修改器;需要时用 property 在属性访问语法背后隐藏功能实现(尽量无副作用,缓存类副作用可接受;避免为计算昂贵的操作使用 property,属性记法会让调用者误以为访问开销很小);
  • 类设计为可被继承、且有不希望子类使用的属性时,用双前导下划线 + 无尾随下划线触发名字改写(注意:改写只使用简单类名,子类若同名同类名仍可能冲突;名字改写会让调试、__getattr__ 等场景不便,需权衡)。

公共与内部接口(Public and Internal Interfaces)

  • 向后兼容保证只适用于公共接口;文档化的接口视为公共(除非明确声明为临时或豁免),所有未文档化接口应假定为内部;
  • 为便于内省,模块应使用 __all__ 显式声明公共 API 名字;__all__ 置空表示模块无公共 API;
  • 即便设置了 __all__,内部接口(包、模块、类、函数、属性等)仍应以单个前导下划线为前缀;
  • 若任一包含命名空间(包、模块、类)是内部的,该接口也视为内部;
  • 导入的名字永远应视为实现细节:其他模块不得依赖对这类导入名字的间接访问,除非它们是被显式文档化的模块 API 一部分(如 os.path 或包的 __init__ 暴露子模块功能)。

编程建议(Programming Recommendations)

  • 不依赖特定 Python 实现的性能特性(PyPy、Jython、IronPython、Cython、Psyco 等):例如不要依赖 CPython 对 a += b / a = a + b 形式就地字符串拼接的高效实现;性能敏感处应改用 ''.join(),保证各实现下都是线性时间;
  • 与单例(如 None)比较永远用 is / is not,不要用相等运算符;警惕 if x 实际想表达 if x is not None 的情况——其他值可能是布尔上下文中为假的容器类型;
  • 用 is not 而非 not ... is:if foo is not None:(正确)vs if not foo is None:(错误);
  • 富比较最好实现全部六个运算(__eq__、__ne__、__lt__、__le__、__gt__、__ge__),可用 functools.total_ordering() 生成缺失方法;PEP 207 表明 Python 假定自反性,解释器可能交换 y > x 与 x < y 等;sort()、min() 保证用 <,max() 用 >,但实现全部六个仍最稳妥;
  • 总是用 def 语句而非把 lambda 直接赋给标识符:def f(x): return 2*x(正确)vs f = lambda x: 2*x(错误)——前者函数对象名为 f 而非 <lambda>,对 traceback 与字符串表示更有用;
  • 异常从 Exception 派生而非 BaseException(后者留给"捕获它几乎总是错"的异常);基于"捕获方需要区分什么"来设计异常层级,回答"出了什么问题",而不仅是"出了问题"(见 PEP 3151 内建异常层级教训);错误异常类名加 "Error" 后缀,非错误的流程控制信号异常无需特殊后缀;
  • 正确使用异常链:raise X from Y 表示显式替换且保留原始 traceback;故意用 raise X from None 替换内层异常时,确保把相关细节转移给新异常(如把 KeyError 转 AttributeError 时保留属性名,或在消息中嵌入原文);
  • 捕获异常时尽量指明具体异常,避免裸 except:——它连 SystemExit 和 KeyboardInterrupt 都捕获,使 Ctrl-C 难以中断程序,且可能掩盖其他问题;想捕获全部程序错误用 except Exception:(裸 except 等价于 except BaseException:)。裸 except 仅限两种场景:① 处理器会打印或记录 traceback;② 代码需要做清理再 raise 让异常向上传播(此时 try...finally 可能是更好选择);
  • 捕获操作系统错误时,优先使用 Python 3.3 引入的显式异常层级,而非内省 errno 值;
  • try 子句保持最小,只包含必要代码,避免掩盖 bug:
# Correct:
try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)

# Wrong:
try:
    # Too broad!
    return handle_value(collection[key])
except KeyError:
    # Will also catch KeyError raised by handle_value()
    return key_not_found(key)
  • 资源局部于某段代码时用 with 语句确保及时可靠清理;try/finally 也可接受;
  • 上下文管理器除获取/释放资源外还有别的用途时,应通过独立函数/方法调用:with conn.begin_transaction(): 优于 with conn:,后者无法提示 __enter__/__exit__ 除了关闭连接还在做其他事;
  • return 语句保持一致:要么全部返回表达式,要么全部不返回;若任一 return 返回表达式,则无值返回处应显式 return None,且函数末尾(可达时)应有显式 return 语句:
# Correct:
def foo(x):
    if x >= 0:
        return math.sqrt(x)
    else:
        return None

def bar(x):
    if x < 0:
        return None
    return math.sqrt(x)

# Wrong:
def foo(x):
    if x >= 0:
        return math.sqrt(x)

def bar(x):
    if x < 0:
        return
    return math.sqrt(x)
  • 用 ''.startswith() / ''.endswith() 而非字符串切片检查前缀/后缀:if foo.startswith('bar'):(正确)vs if foo[:3] == 'bar':(错误);
  • 类型比较用 isinstance():isinstance(obj, int)(正确)vs type(obj) is type(1)(错误);
  • 空序列在布尔上下文中为假:if not seq: / if seq:(正确)vs if len(seq): / if not len(seq):(错误);
  • 不要写依赖显著尾随空白的字符串字面量——它视觉上不可区分,部分编辑器(或 reindent.py)会裁剪;
  • 不要用 == 比较布尔值与 True/False:if greeting:(正确);if greeting == True: 错误,if greeting is True: 更糟;
  • 不鼓励在 try...finally 的 finally 子句中使用会跳出该子句的 return/break/continue——这会隐式取消正在传播的活动异常:
# Wrong:
def foo():
    try:
        1 / 0
    finally:
        return 42

函数注解与变量注解

函数注解(随 PEP 484 接受而更新):

  • 函数注解使用 PEP 484 语法(格式化规则见前文空白符小节);
  • 本 PEP 先前推荐的注解风格实验不再鼓励;但标准库之外,在 PEP 484 规则内做实验(如给大型第三方库/应用加注解、评估易加性与可理解性收益)现在受到鼓励;
  • Python 标准库应保守采用注解,但新代码与大型重构允许使用;
  • 想为注解做不同用途的代码,建议在文件顶部加 # type: ignore 注释,让类型检查器忽略所有注解(更细粒度的抑制方式见 PEP 484);
  • 类型检查器与 linter 一样是可选、独立的工具,Python 解释器默认不应因类型检查发出消息或改变行为;
  • 不需要类型检查器的用户可完全忽略;第三方库用户可能想对库运行类型检查,为此 PEP 484 推荐使用 stub 文件(.pyi)——类型检查器优先读取 .pyi 而非对应 .py;stub 可与库一同分发,也可经库作者许可单独通过 typeshed 分发。

变量注解(PEP 526):

  • 模块级、类与实例变量、局部变量的注解:冒号后一个空格,冒号前无空格;
  • 若有右值,等号两侧各一个空格:
# Correct:
code: int

class Point:
    coords: Tuple[int, int]
    label: str = '<unknown>'

# Wrong:
code:int  # No space after colon
code : int  # Space before colon

class Test:
    result: int=0  # No spaces around equality sign
  • 虽然 PEP 526 面向 Python 3.6 被接受,但变量注解语法在所有 Python 版本上都是 stub 文件的推荐语法(见 PEP 484)。

在仓库中落地:把 PEP 8 变成可问答的知识库

materials 仓库把这份 1600+ 行的规范全文作为 RAG 语料,展示了"大型规范文档如何被检索式问答系统消化"的完整链路,所有示例均围绕 python-llamaindex/data/pep8.rst 展开。

加载文档与最简问答

documents.py 演示最基础的加载:

from llama_index.core import SimpleDirectoryReader

reader = SimpleDirectoryReader(input_files=["./data/pep8.rst"])
documents = reader.load_data()

print(documents[0].text)

demo.py 在此基础上构建 VectorStoreIndex 并回答问题:

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex

reader = SimpleDirectoryReader(input_files=["./data/pep8.rst"])
documents = reader.load_data()

index = VectorStoreIndex.from_documents(documents)

query_engine = index.as_query_engine()
print(query_engine.query("What is this document about?"))

这正对应本文反复梳理的内容——模型可以从这份风格指南中直接回答"文档主题是什么"。

索引持久化复用

single_query.py 给出带磁盘缓存的健壮版本:首次构建索引后通过 index.storage_context.persist(persist_dir=...) 落盘,下次直接从 storage 目录用 load_index_from_storage 加载,避免重复构建:

def get_index(persist_dir=PERSIST_DIR, data_file=DATA_FILE):
    if persist_dir.exists():
        storage_context = StorageContext.from_defaults(persist_dir=str(persist_dir))
        index = load_index_from_storage(storage_context)
        print("Index loaded from storage...")
    else:
        reader = SimpleDirectoryReader(input_files=[str(data_file)])
        documents = reader.load_data()
        index = VectorStoreIndex.from_documents(documents)
        index.storage_context.persist(persist_dir=str(persist_dir))
        print("Index created and persisted to storage...")
    return index

多索引对比与异步查询

indices.py 对同一份 PEP 8 文档同时构建三种索引——VectorStoreIndex、SummaryIndex、TreeIndex——并用 asyncio 调用各自的 query engine 对比回答同一问题,适合观察不同索引结构对检索风格指南类文档的效果差异;async_query.py 则展示用 asyncio.gather 并发执行多个查询(例如"文档主题是什么"与"总结 Python 命名约定"),返回后逐一打印结果。

不同模型与 Embedding 组合

仓库还提供了三套本地/云端模型替换方案:

  • demo_ollama.py:完全本地化,用 OllamaEmbedding(model_name="embeddinggemma", request_timeout=60.0, context_window=8000) 做嵌入、Ollama(model="llama3.2") 做生成,无需联网即可对 PEP 8 问答;
  • demo_google.py:GoogleGenAIEmbedding(model="models/embedding-gecko-001") + GoogleGenAI(model="gemini-2.5-flash");
  • demo_gpt5.py:OpenAI(model="gpt-5.1") 回答 "Summarize the import rules."——恰好可以检验本文"导入规范"一节的归纳是否与模型检索结果一致。

运行环境依赖集中在 python-llamaindex/requirements.txt:核心为 llama-index==0.14.10 及其 llama-index-core、llama-index-readers-file、llama-index-llms-openai、llama-index-embeddings-openai、llama-index-llms-ollama、llama-index-llms-google-genai 等配套包(具体版本请以该文件为准)。若要本地复现,建议按该文件安装依赖后,在 python-llamaindex 目录中依次运行各示例脚本。

结语

PEP 8 不是一套必须逐条死守的教条,而是以"可读性优先、项目内部一致性优先"为纲的可执行约定集:从缩进、行宽、空行、导入顺序,到注释、命名、异常与注解风格,它把大量实战经验沉淀为可机械执行的规则。在 materials 仓库中,这份全文又作为一个高质量语料,被 python-llamaindex 的多个脚本读入 LlamaIndex,演示了如何用 RAG 让开发者随时以自然语言查询编码规范——这正是"规范文档 + 检索问答"的一种典型落地形态。

登录后查看全文
materials