PEP 8 官方风格指南全文精读:Python 代码规范、命名约定与 LlamaIndex 实践
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")。风格指南的本质是追求一致性,其优先级排序为:
- 与本风格指南一致;
- 与所在项目一致(更重要);
- 与单个模块或函数内部保持一致(最重要)。
PEP 8 同时明确给出允许打破规则的场景(不要为了合规而破坏向后兼容):
- 遵守规则反而让代码更难读时;
- 为与周边已打破该规则的代码保持一致时(顺带说明这也是清理历史代码的机会);
- 代码早于该规则出现、且没有理由去改动它时;
- 需要兼容不支持该特性推荐的旧版 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 之后、模块级全局量与常量之前;
- 导入分组顺序(组间留一个空行):
- 标准库导入;
- 相关的第三方导入;
- 本地应用/库特定导入。
- 推荐绝对导入,通常更易读、错误消息更好;显式相对导入在复杂包布局中是可接受的替代(标准库应始终使用绝对导入):
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})(正确)vsspam( ham[ 1 ], { eggs: 2 } )(错误); - 尾随逗号与闭合括号之间:
foo = (0,)(正确)vsbar = (0, )(错误); - 逗号、分号、冒号之前:
if x == 4: print(x, y); x, y = y, x(正确)vsif 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)(正确)vsspam (1)(错误); - 索引/切片的左括号之前:
dct['key'] = lst[index](正确)vsdct ['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:(正确)vsif 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(正确)vsf = 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'):(正确)vsif foo[:3] == 'bar':(错误); - 类型比较用
isinstance():isinstance(obj, int)(正确)vstype(obj) is type(1)(错误); - 空序列在布尔上下文中为假:
if not seq:/if seq:(正确)vsif 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 让开发者随时以自然语言查询编码规范——这正是"规范文档 + 检索问答"的一种典型落地形态。