awesome-python 审核日志机制：Overrides、Git 归档与策展决策的可追溯性

本文以 awesome-python 仓库中的 docs/audit-logs.md 为核心，讲解这份"审核日志"如何记录维护者超出成文规则的例外决策：包括命名例外（Naming Exceptions）与成熟稳定保留（Mature-stable Keeps）两类 Overrides 的完整清单，以及"Git 历史即归档"的决策留痕机制。读完你可以掌握这套策展型 awesome 列表的审核运作方式：每次条目删除如何落到带理由的 commit、每次破格保留如何在注册表中登记、以及维护者如何以实时数据（GitHub 活跃度、PyPI 下载量）为依据复核每一条条目。

审核日志的定位：Git 历史之上的速览注册表

docs/audit-logs.md 开篇即定义了该文件的性质：

awesome-python is audited section by section. Every entry gets re-verified against live data, and every removal lands in a commit whose body carries the reason. Git history is the archive. This file is the at-a-glance register of maintainer decisions that a single commit can't show.

翻译其要点：

1. 逐 Section 审核（audited section by section）：整个列表不是一次性快照，而是按章节（Section）周期性复核；
2. 每条目的每次删除都会落入一个 commit，且 commit 正文（body）必须携带删除理由——Git 历史本身是"归档"；
3. audit-logs.md 本身不是归档，而是注册表（register）：它只登记那些单个 commit 无法完整呈现的维护者决策——即 Overrides（例外决策）。

"审核"（Audit）一词在仓库中有正式定义。CONTEXT.md 的 Maintenance 词汇表将 Audit 界定为：对一或多个 Section 的周期性维护扫描，其中每个 Entry 的裁决都要对照当前证据重新验证，Challenger 被晋升或降级，过大的 Use Case 被拆分，删除与收录被重新裁定；维护者通过交互式预览裁决，条目变更只在其明确放行后才落地。2026 年 8 月的"shortlist-reform sweeps"是该列表的第一批 Audit（见 CONTEXT.md 与 docs/adr/0001-shortlist-not-catalog.md）。

而 AGENTS.md 对审核的执行细节做了硬性约束（AGENTS.md）：

• 每个 keep/drop 理由必须在决策时对照当前在线数据验证——下载量、仓库活跃度与归档状态、PyPI 元数据、项目文档；
• 增删条目时一个 commit 只动一个条目；例外是 prune sweep：一个 Section 一个 commit，commit body 中逐一列出每个被删条目及其理由。

这解释了 audit-logs.md 的分工设计：逐条删除的"证据链"在 Git 里（每个 commit 一条理由），而跨条目的、需要集中展示的例外决策则登记在 audit-logs.md 中，供人与 Agent 快速查阅。

Overrides 规则：允许破格，但必须登记

docs/audit-logs.md 的 Overrides 一节指出：CONTRIBUTING.md 允许维护者为特定条目或使用场景突破任何限制，每一次 override 都要记录在此文件中。

对应的成文规则见 CONTRIBUTING.md 的 Admission 部分：维护者可以对任何一条限制——条目上限（Cap）、活跃度要求、稳定性要求——针对特定条目或使用场景做出显式决定予以突破。但规则同时划定了边界：

• Override 是**逐案（case-by-case）**的，不会为任何提交放宽成文规则；
• 提交者在 PR 中引用既有的 override 不具有任何效力。

CONTEXT.md 对 Override 的定义进一步说明：它是维护者在 Audit 中做出、并显式记录下来的决定，使某条目或某类结构形态越过某条成文限制——活跃度红线、稳定性门槛、条目上限或结构规则——而一个 Override 永远不会为其他条目松动成文规则，提交者不得引用它。

也就是说，audit-logs.md 里的两个清单正是这类"显式记录"的落地：下面两节将其完整继承并展开。

命名例外（Naming Exceptions）

成文规则是：显示名（display name）使用规范的 PyPI 包名，以便开发者直接复制进 pip install；维护者在 CONTRIBUTING.md 的 Naming Convention 中要求通过 PyPI 官方 JSON 元数据接口（pypi.org/pypi/{package}/json）确认规范名，不在 PyPI 上的项目则用 GitHub 仓库名。

docs/audit-logs.md 登记的命名例外共 12 条，均为维护者决定保留与 PyPI 包名不同的显示名：

显示名	实际 PyPI 包名
autobahn-python	autobahn
django-rest-framework	djangorestframework
django-rules	rules
fasthtml	python-fasthtml
jinja	Jinja2
mem0	mem0ai
pangu.py	pangu
playwright-python	playwright
pytorch	torch
strawberry	strawberry-graphql
strawberry-django	strawberry-graphql-django

从 README.md 中可以逐一印证这些条目：例如 Template Engines 下的 jinja 链接指向 Jinja 仓库、Web APIs 下的 strawberry 与 strawberry-django、Deep Learning 下的 pytorch、Testing 下的 playwright-python 等。这类例外的共性是：显示名更贴近读者的惯用称呼（"PyTorch"、"Jinja"、"Playwright"），而 PyPI 包名反而是带前缀或大小写变体的形式。若提交者按规范名规则机械地"纠正"显示名，反而会破坏列表的可读性与惯例——这正是命名例外存在的原因。

对实现者而言还有一个结构性细节：显示名并不只是展示层。website/readme_parser.py 的 _parse_list_entries（website/readme_parser.py#L195-L265）会把列表项中第一个链接的文本解析为 ParsedEntry.name、链接目标解析为 url。也就是说显示名直接进入站点数据模型；而 PyPI 下载量、GitHub star 等信号是按包名/仓库名关联的，两者出现"显示名 ≠ 包名"的条目时，关联逻辑必须以包名为准。

成熟稳定保留（Mature-stable Keeps）

docs/audit-logs.md 登记的第二类 Override：

These entries sit past the 12-month activity requirement without an override. Each one is kept by editorial judgment: mature, stable, and no successor exists.

完整清单如下（5 条）：

条目
ftfy
itsdangerous
jieba
jinja
sortedcontainers

对照 CONTRIBUTING.md 的 Quality Requirements 第 2 条"Active: Commits within the last 12 months"，这 5 个条目已经超出了 12 个月活跃度红线，但文档明确说明它们并非以正式 override 名义保留，而是逐条依据编辑判断保留：成熟、稳定、且不存在继任者。这正是 audit-logs.md 开篇所说"单个 commit 无法展示"的那类决策——一次 prune sweep 的 commit 里只会写"删除了 X 因为 Y"，而"为什么红线外的这几个不删"需要注册表来集中陈述。

这 5 条在 README.md 中分布在不同 Section：ftfy 在 Text Processing / Encoding and Unicode、itsdangerous 在 Security 相关区域、jieba 在 Natural Language Processing / Chinese、jinja 在 Template Engines、sortedcontainers 在 Algorithms and Design Patterns / Algorithms，体现了 Audit 是按 Section 逐节扫描、跨节保留决策需要汇总登记的现实。

"Git 历史即归档"：为什么没有单独的移除条目归档文件

docs/adr/0001-shortlist-not-catalog.md 记录了列表从"目录（catalog）"转向"短名单（shortlist）"的架构决策，其中对"被删条目往哪里去"给出了明确取舍：

• 被否选项：把移除的条目归档到单独文件——"rejected because it recreates the catalog one click away and dilutes the identity the change exists to restore"（被否决，因为它在一步之遥外重新造出了一个目录，稀释了这次变革要恢复的定位）；
• 被选方案：removed entries deleted outright，Git 历史就是归档。

这与 audit-logs.md 的"Git history is the archive"完全一致，也与 AGENTS.md 的 commit 纪律（prune sweep 一个 Section 一个 commit、body 逐条列删除理由）形成闭环：任何人想追溯某条目何时、为何被删，git log 加 commit body 即可复现完整证据链；audit-logs.md 只保留需要"一览"的例外决策。从源码结构看，这套归档方式还有一个工程上的好处：website/fetch_github_stars.py#L6 的注释指出，README 中移除的条目会在 star 缓存里留下"无害的孤儿键"，数据缓存本身不做持久归档——归档职责完全由 Git 承担，站点数据层保持可重建。

支撑审核的实时数据管道

audit-logs.md 强调"every entry gets re-verified against live data"，仓库中确实存在配套的数据采集脚本，可作为审核证据链的实现佐证：

GitHub 活跃度（12 个月活跃度检查的依据）：website/fetch_github_stars.py 通过 GitHub GraphQL API 批量拉取所有 README 中仓库的 star 数、owner 及默认分支最近一次提交时间（last_commit_at，见 website/fetch_github_stars.py#L60 的查询字段）。关键参数（website/fetch_github_stars.py#L21-L26）：

• CACHE_MAX_AGE_HOURS = 12：缓存 12 小时有效，过期重新抓取；
• BATCH_SIZE = 50：每批 50 个仓库，GraphQL 查询用别名聚合；
• 运行需要 GITHUB_TOKEN 环境变量；输出文件 data/github_stars.json 被 gitignore，CI 部署时抓取，本地运行仅供预览。

"12 个月内是否有 commit"的活跃度红线（Mature-stable Keeps 所突破的那条）正是由 last_commit_at 这类字段支撑的。

PyPI 下载量（收录裁决的首要信号）：CONTRIBUTING.md 明确"admission is decided by maintainer editorial judgment, informed primarily by PyPI download counts rather than GitHub stars"。仓库提供了三路下载量采集脚本——website/fetch_pypi_downloads_via_bigquery.py、website/fetch_pypi_downloads_via_clickpy.py、website/fetch_pypi_downloads_via_pepy.py——Makefile 中 fetch_pypi_downloads 目标默认走 ClickPy 通道。维护者的编辑判断会覆盖这些信号的已知失效模式（CI 刷量、模型权重下载被计为 pip 安装、大但专众被误读为小众），这也是 CONTEXT.md 中 Obvious Choice 定义的组成部分。

结构解析（Use Case 边界的机器可读性）：审核按 Section/Use Case 进行，而 Use Case 的边界由 README 结构定义（子分类即 Use Case，扁平 Section 即单一 Use Case，见 CONTEXT.md）。website/readme_parser.py#L445-L471 的 parse_readme 用 markdown-it-py 解析出 Group → Section → Subcategory → Entry 的树，其模块注释还记录了若干经验验证的行为（## Projects 之上的内容被忽略、新子分类无需改解析器、"Total entries" 计数包含子项等）。测试用例 website/tests/test_readme_parser.py 与 website/tests/test_fetch_github_stars.py 分别锁定解析行为与抓取逻辑，使"审核单位"的划分在实现层有据可查。

对提交者与维护者的实践含义

结合 audit-logs.md 与仓库文档，可以提炼出几条操作层面的结论：

1. 查例外先看注册表：任何显示名与 PyPI 包名不一致、或活跃度红线外的条目，先查 docs/audit-logs.md——若在两份清单中，说明是维护者显式决定，按 CONTRIBUTING.md 规则，提交者引用 override 不具效力；
2. 查删除理由走 Git：被删条目不在 audit-logs.md 里找，而在 git 历史中按 Section 的 prune sweep commit 及其 body 找；
3. 新 override 必须登记：维护者做出任何突破成文限制的决定（无论命名、活跃度、上限还是结构），应当同步更新 docs/audit-logs.md，使注册表与实际规则状态一致；
4. 证据必须实时：依据 AGENTS.md，keep/drop 理由必须在决策时对照当前在线数据验证，训练数据记忆不算证据——这保证了注册表与 Git 归档记录的都是"决策时刻的事实"，而非事后追认。

小结

docs/audit-logs.md 体量虽小，却是 awesome-python 策展机制中"规则—例外—归档"三层结构里唯一面向例外决策的公开文件：逐条删除的证据在 Git（每个 commit 带理由），破格保留的决策在此登记（12 条命名例外 + 5 条成熟稳定保留），而成文规则与裁决口径则分列于 CONTRIBUTING.md、CONTEXT.md 与 docs/adr/0001-shortlist-not-catalog.md。对读者、贡献者乃至自动化 Agent 而言，这份注册表配合仓库内的数据抓取脚本与解析器，构成了一套可验证、可追溯的策展决策体系。