Community编程与开发github.com

python-reduce-complexity

测量并降低 Python 代码的复杂度,通过内嵌脚本计算必要的指令性词法标记数量。提出简化方案,验证功能等价性,或论证差异无关紧要,并重新测量以确认计数下降。适用于用户要求评估、降低、比较或审计代码复杂度时。

python-reduce-complexity 是什么?

该技能的核心功能是测量和降低 Python 代码的复杂度,复杂度指标为指令性词法标记(imperative lexical tokens)的数量。它通过一个内嵌的 `imperative_tokens.py` 脚本来实现,该脚本精确定义了哪些代码结构会被计入(如语句、赋值、运算符、调用、列表推导式等),以及哪些结构不计入(如函数/类定义头、类型注解、导入、注释、关键字参数名称、属性限定等)。技能的工作流程分为五个步骤:(1) 基线测量,运行脚本获取初始标记数;(2) 提出简化建议,分析代码寻找可以简化或替代的模式(如删除死代码、合并重复逻辑、使用标准库替代手写循环等);(3) 逐一应用建议并验证功能等价性,确保测试通过或通过新旧版本对比验证;(4) 重新测量所有受影响文件的总计数,确保总计数下降;(5) 生成报告,列出每个文件的标记数变化、等价性验证方式以及任何非严格等价变更的论证。该技能尤其强调降低计数只是一个简化操作的证据,而非简化本身,允许在有充分理由的情况下改变行为(如论证不可达输入、差异不被观察或无害)。支持 Python 文件和 Jupyter Notebook(.ipynb),会正确处理 IPython magic 命令。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jachymb/skills/tree/main/python-reduce-complexity

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

降低 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 defaultx if x is not None else default会错误地替换假值 x(0, "", [])
zip(a, b)使用 range(len(a)) 索引两者较短的 b 会静默截断;使用 strict=True 可以保留检查
a // bint(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仅索引、调用一个方法或应用一个运算符的 lambdastr.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]返回元组迭代器,而非切片列表
@singledispatchisinstance 链注册的最具体类获胜,而不是第一个匹配的测试;分发的参数是第一个,通过位置传递

@singledispatch 和 @dataclass 的参数将逻辑移入了脚本不查看的头部。它们除了计数以外的理由:生成的方法遵循字段列表且不会偏离;每个类型都有自己的函数,新类型不会影响现有函数。

其他形式仅在特定上下文中有用,因此需要额外考虑:

  • itertools.product 或 itertools.combinations 可以替换嵌套循环。
  • functools.reduce 可以替换没有内置的折叠操作。

步骤

  1. 基线测量。 使用项目的解释器(Python 3.12 或更高版本)对参数中的文件运行脚本,并保存输出:

    python "${CLAUDE_SKILL_DIR}/imperative_tokens.py" <file.py | notebook.ipynb> [...]
    

    现在运行测试:更改前失败的测试套件无法验证更改后的内容。如果用户只要求测量,则报告测量结果并停止。

  2. 提出建议。 阅读代码以理解其计算逻辑,而不是寻找特定模式。针对每个函数、循环和分支,询问是否可以用更少的代码表达相同的结果。本技能中的列表和表格展示了简化的样子。它们不是搜索空间:大多数可简化的内容特定于当前代码,而且任何列表都无法预测。仅检查列出的模式是不完整的。

    常见的发现,大致按收益递减排序:

    • 死代码:未使用的函数、参数和永远无法到达的分支;
    • 相同逻辑重复出现(本文件或其他文件中),可以由共享的辅助函数或基类统一定义;
    • 手动编写的代码已由标准库、内置函数或已安装的依赖项提供;标准库工具如 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
    

    以代码形状展示每个提案:关键行前后对比、预期的标记节省、它影响的其它文件以及上述部分要求的任何理由或论证。在用户同意后应用,或如果用户已要求进行更改,则直接应用。

  3. 应用并验证,一次一个提案,以便失败可以追溯到其原因。

    • 在首次编辑基线范围外的文件之前,测量它并将其添加到基线。新文件从 0 开始。
    • 测试通过,保持未修改状态。与其检查的代码一起编辑的测试不再有效;如果必须更改(例如,它调用了被删除的辅助函数),需说明。
    • 从未执行更改后代码行的测试不能证明什么。对于这些行,在相同输入(包括边界情况)上运行旧版本(git stash 或 git show HEAD:<path> 到临时文件)和新版本,并比较输出。浮点结果应相同,否则报告需说明差异大小。
    • 非严格等价的更改需要在论证允许的输入上进行比较。然后检查论证本身:阅读构建值的代码,或搜索每个消费者。不成立的论证会导致提案被放弃。
    • 公共行为的更改(签名、异常类型、输出顺序)不是等价更改。它需要用户的明确同意。
  4. 重新测量。 对受影响的所有文件运行脚本:参数中的文件以及更改编辑或创建的其他每个文件。已删除文件的计数为 0。组合总数低于组合基线,否则更改被撤销。未通过步骤 3 的更改也会被撤销。

  5. 报告。 每个受影响文件和组合:变更前、变更后的标记数以及差异。然后列出验证了等价性的内容(哪些测试,哪些直接比较)、每个非严格等价的更改(包含差异和论证)、等待用户决策的每个更改以及被放弃的每个提案及其原因。

相关技能