降低 Python 复杂度
文件:$ARGUMENTS
代码复杂度最好保持在较低水平。复杂度通过 Python 词法标记中属于指令性代码(可执行语句)的数量来衡量。声明用于组织代码但不增加逻辑,因此不计入。
计数规则
imperative_tokens.py(位于本文件旁边)是具体定义。
不计入:
def和class头部:从第一个装饰器到冒号(打开函数体)为止的部分,包括装饰器、参数、默认值、基类、返回类型注解。所有这些仅定义时评估一次,用于声明接口。- 类型注解(
x: int = 1计为x = 1,单独的x: int计为x = 1而不是x: int)以及type别名。 - 导入、注释、文档字符串、换行符和缩进。
- 函数调用中关键字参数的名称:
f(key=value)与f(value)具有相同权重。在大多数情况下,推荐使用关键字传递参数,因此它不增加成本。 - 属性限定:
a.b.c.d与d具有相同权重。点路径命名一个对象。如果计数它,会奖励from numpy import log而不是np.log,或者为self.x使用本地别名,这两种情况都不会改变任何逻辑。
计入:所有其他标记。语句(if、for、while、try、with、return、raise……)、赋值、运算符、调用、字面量、推导式和 lambda,以及它们的逗号、冒号和成对括号。因此,一个调用比执行相同操作的运算符多一个标记:a.update(b) 为 4 个标记,而 a |= b 为 3 个。
对于 notebook(.ipynb),仅计算代码单元。魔术命令或 Shell 行(%config …、!pip …)计为 IPython 将其转换成的调用。在单元格魔术(%%bash、%%html)下的单元计为 0。例外情况是运行代码主体为 Python 的单元魔术(IPython 的 ExecutionMagics,例如 %%time 和 %%capture):该魔术计为行魔术,其主体计为代码。对于非内置(非安装的 IPython 中自带)的魔术,例如来自扩展的魔术,计为 0,并且脚本会打印警告:请在报告中传递该警告。内核不是 Python 的 notebook 计为 0。脚本仅在给定 Python notebook 时导入 IPython,并询问它哪些魔术是内置的。
计数只是一个代理
更低的计数是简化的证据,而非简化本身。
- 允许重大重构: 新的辅助函数、新的基类、新文件。然后,在步骤 4 中,将计数与所有受影响文件的组合进行比较,因此在文件之间移动逻辑净效果为零。
- 需要其自身的理由: 将逻辑移动到脚本不查看的地方——例如默认值、装饰器参数、基类表达式或新依赖项——需要提案说明除了计数降低之外该更改好的原因。
- 禁止: 将代码放入字符串中用于
eval或exec或类似的外部执行。 - 内联仅使用一次的变量仅在不会损害可读性时可以接受。为中间变量取一个好名称有助于读者理解意图。
- 不属于降低: 删除行为(边界处的验证、错误处理、支持的情况),以及为了减少几个标记而牺牲可读性(密集型单行代码,丢失尾随逗号)。
项目自身的规则(CLAUDE.md、编码指南)优先于计数。
非严格等价的更改
如果论证表明程序即使行为改变也保持正确,则可以为了简化而改变行为。提案需说明差异所在、在哪些输入上,以及基于代码的论证和证据:
- 差异输入不可能发生。 证据:构建或验证该值的代码。
- 没有代码观察到该差异。 证据:列出该值的每个消费者。
- 差异是可观察但无害的: 例如从已设置种子的生成器取出不同值、较慢的算法、更早地抛出错误。这需要用户的明确同意。对于公共返回值、写入的输出或测试可观察到的任何差异,同样需要用户同意。
以下是一些示例,展示了论证的形式。任何其他改变行为的更改都以此方式进行论证,无论其是否与这些示例类似:
| 更简单的形式 | 替换 | 差异之处 |
|---|---|---|
x or default | x if x is not None else default | 会错误地替换假值 x(0, "", []) |
zip(a, b) | 使用 range(len(a)) 索引两者 | 较短的 b 会静默截断;使用 strict=True 可以保留检查 |
a // b | int(a / b) | 负操作数取整方式不同 |
max(xs, key=f) | sorted(xs, key=f)[-1] | 平局时,获胜的是相等的第一个项,而不是最后一个 |
xs.sort() | xs = sorted(xs) | 调用者传入的列表发生了变异 |
Counter(xs) | 计数循环 | 缺少的键读取为 0 而不是引发异常 |
用 @dataclass 实现,读取为 row.name | 用字典记录实现,读取为 row["name"] | 索引、.get、** 解包和 JSON 序列化将不再工作 |
论证必须基于代码,而非基于当前数据:“文件中没有重复项”不是有效的论证,“可能唯一”也不是。移除行为仍然被排除在外:边界处的验证不能通过论证被移除。
不确定时,由用户决定。 如果证据不完整(存储库外的消费者、无法读取的构建值的代码)或不清楚差异是否无害,不要做出决定。向用户提供更改选项,说明差异和未知情况,继续处理其他提案,并仅在用户同意后应用。
标准库形式
以下是一些常见情况的示例,展示这类替换的样子。这不是一个完整目录:内置函数、标准库以及项目已安装的依赖项提供了更多选择,表中未列出的替换与表中列出的同样有效。
| 标准形式 | 替换 | 差异之处 |
|---|---|---|
@dataclass,使用 field(default_factory=list)、order=True、frozen=True | 一个仅存储参数的 __init__;手写的 __eq__、__repr__、__lt__、__hash__ | 原本没有 __eq__ 的类现在按值比较并且不可哈希(eq=False 保持身份);__eq__ 还会比较类;显式的 None 不再成为默认值 |
any(p(x) for x in xs)、all(…)、next(filter(p, xs), None) | 带有 break 的标志或搜索循环 | 无 |
defaultdict(list) | if key not in groups: groups[key] = [] | 读取缺少的键会插入它 |
@cache、@cached_property | 记忆字典;一个 if self._x is None 惰性属性 | 方法上的 @cache 会保持它调用的每个实例存活;属性通过 del 重置,而不是通过赋值 None |
itemgetter("foo")、str.strip、operator.mul | 仅索引、调用一个方法或应用一个运算符的 lambda | str.strip 在非字符串的值上会引发异常 |
Path(path).read_text() | with open(path) as file: 和 file.read() | 无 |
name.removeprefix(prefix)、line.partition("=") | startswith 和切片;split 和长度检查 | 无 |
chain.from_iterable(xss) | [x for xs in xss for x in xs] | 迭代器:在结果需要索引或读取两次的地方用 list 包装 |
batched(xs, n) | 在 range(0, len(xs), n) 上使用 xs[i:i + n] | 返回元组迭代器,而非切片列表 |
@singledispatch | isinstance 链 | 注册的最具体类获胜,而不是第一个匹配的测试;分发的参数是第一个,通过位置传递 |
@singledispatch 和 @dataclass 的参数将逻辑移入了脚本不查看的头部。它们除了计数以外的理由:生成的方法遵循字段列表且不会偏离;每个类型都有自己的函数,新类型不会影响现有函数。
其他形式仅在特定上下文中有用,因此需要额外考虑:
itertools.product或itertools.combinations可以替换嵌套循环。functools.reduce可以替换没有内置的折叠操作。
步骤
-
基线测量。 使用项目的解释器(Python 3.12 或更高版本)对参数中的文件运行脚本,并保存输出:
python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <file.py | notebook.ipynb> [...]现在运行测试:更改前失败的测试套件无法验证更改后的内容。如果用户只要求测量,则报告测量结果并停止。
-
提出建议。 阅读代码以理解其计算逻辑,而不是寻找特定模式。针对每个函数、循环和分支,询问是否可以用更少的代码表达相同的结果。本技能中的列表和表格展示了简化的样子。它们不是搜索空间:大多数可简化的内容特定于当前代码,而且任何列表都无法预测。仅检查列出的模式是不完整的。
常见的发现,大致按收益递减排序:
- 死代码:未使用的函数、参数和永远无法到达的分支;
- 相同逻辑重复出现(本文件或其他文件中),可以由共享的辅助函数或基类统一定义;
- 手动编写的代码已由标准库、内置函数或已安装的依赖项提供;标准库工具如
itertools、functools、operator、collections或dataclasses可能有所帮助,“标准库形式” 部分列出了常见情况; - 构建值的循环:通常推导式优于循环,有时
filter或map内置函数比推导式更简单; - 可以用重载运算符替换的方法调用:
a | b代替a.union(b),a |= b代替a.update(b),a @ b代替a.dot(b)。首先检查操作数类型:集合上的|=需要集合,而.update()接受任何可迭代对象; - 可以折叠为数据(映射)或通用路径的分支;
- 仅用于撤销的状态和转换;
- 远离程序边界的防御性检查;
- 比其输入要求更严格的代码,其中更简单的形式仅在不可达输入或差异不被观察到的情况下不同(上表)。
然后再次遍历代码,首先处理最长的函数,寻找不属于上述任何一类的改进:不同的算法或数据结构使得簿记变得不必要;重新排列计算使特殊情况消失;项目已使用的依赖项中的函数能完成整个工作;两个函数仅在一个值上不同。这样的提案与列出的任何提案一样遵循相同规则。
要评估代码片段,例如提案前后的行,可以在没有文件参数的情况下将其管道传递给脚本。它将仅打印计数。代码片段必须能够独立解析,因此需要取消缩进:
python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <<'EOF' uncounted |= set(range(first, last)) EOF以代码形状展示每个提案:关键行前后对比、预期的标记节省、它影响的其它文件以及上述部分要求的任何理由或论证。在用户同意后应用,或如果用户已要求进行更改,则直接应用。
-
应用并验证,一次一个提案,以便失败可以追溯到其原因。
- 在首次编辑基线范围外的文件之前,测量它并将其添加到基线。新文件从 0 开始。
- 测试通过,保持未修改状态。与其检查的代码一起编辑的测试不再有效;如果必须更改(例如,它调用了被删除的辅助函数),需说明。
- 从未执行更改后代码行的测试不能证明什么。对于这些行,在相同输入(包括边界情况)上运行旧版本(
git stash或git show HEAD:<path>到临时文件)和新版本,并比较输出。浮点结果应相同,否则报告需说明差异大小。 - 非严格等价的更改需要在论证允许的输入上进行比较。然后检查论证本身:阅读构建值的代码,或搜索每个消费者。不成立的论证会导致提案被放弃。
- 公共行为的更改(签名、异常类型、输出顺序)不是等价更改。它需要用户的明确同意。
-
重新测量。 对受影响的所有文件运行脚本:参数中的文件以及更改编辑或创建的其他每个文件。已删除文件的计数为 0。组合总数低于组合基线,否则更改被撤销。未通过步骤 3 的更改也会被撤销。
-
报告。 每个受影响文件和组合:变更前、变更后的标记数以及差异。然后列出验证了等价性的内容(哪些测试,哪些直接比较)、每个非严格等价的更改(包含差异和论证)、等待用户决策的每个更改以及被放弃的每个提案及其原因。