awesome-python ADR 0001 详解把列表从目录重构为显而易见选择的短名单【免费下载链接】awesome-pythonThe definitive list that answers I want to do X in Python, which tool should I use?项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python本文基于 awesome-python 仓库中的架构决策记录 docs/adr/0001-shortlist-not-catalog.md状态accepted完整还原一次编辑策略重构的决策过程为什么一个条目超过 576 条、分类无限膨胀的 awesome-* 列表要放弃目录catalog定位转而成为回答I want to do X in Python, which tool should I use?这一唯一问题的短名单shortlist。读完后你将掌握这套 curation 体系的完整规则Use Case、Obvious Choice、Challenger、Displacement、Cap、Split、其证据链来源PyPI 下载量而非 GitHub stars、以及规则如何在 CONTRIBUTING.md、CONTEXT.md、docs/audit-logs.md 和网站构建管线中落地执行。1. 背景旧的收录模型如何失效ADR 记录了触发重构的三个事实均以 2026 年中为时间基准列表当时持有576 个条目分布在 75 个 Section。当前 README.md 中的###章节数为 77含后续增减与这一量级吻合条目流入量同比增长24 倍过去 12 个月新增 96 条而前一年只有 4 条且增量集中在 AI and Agents 这类 Section该 Section 曾达 41 个条目旧的收录模型是三条泳道——Industry Standard、Rising Star、Hidden Gem且只有第一条泳道有上限。这个模型会接纳任何孤立来看足够好的项目结果是分类无限增长列表不再回答读者的实际问题X 这件事我用什么重构的哲学依据被直接写进 ADR即 Zen of Python 的一条There should be one — and preferably only one — obvious way to do it.也就是说列表的定位从好的 Python 项目大全收窄为每个使用场景下显而易见的少数选择。2. 决策内容新规则的完整定义这一节逐条继承 ADR《The decision》部分并结合仓库文件补充其执行细节。2.1 收录边界测试从用 Python 写的变为服务 Python 开发者ADR 用一个新测试替换了旧要求primarily written in Python (50%)新测试Serves Python Developers只要 Python 开发者在自己的 Python 工作中使用它实现语言和打包方式就无关紧要——uv和ty是 Rust 写的agent skill packs 是 markdown都属于反过来一个没人会在 Python 工作中使用的纯 Python 项目不收录CONTEXT.md 中显式标注旧术语为应避免项_Avoid_: Python-first, written-in-Python (old requirement — removed)防止旧心智模型回流。CONTRIBUTING.md 的Quality Requirements第一条与该测试完全对齐并给出四个并行的硬性质量门槛Active12 个月内有提交、Stable非 alpha/beta/experimental、DocumentedREADME 有示例和用例说明、Established仓库至少 1 个月历史。2.2 Use Case 结构投稿者不能创造自己需要的分类ADR 规定 Use Case 由列表既有结构定义an entry PR can never create the subcategory it needs。结合 CONTEXT.md 的结构词汇表列表的层级是层级定义与规则的关系Thematic Group粗体分组行如 AI ML、Web Development在 TOC 和正文中聚类 Section纯组织不绑定规则SectionREADME.md 中的###标题如 Testing、AI and Agents位于某个 Thematic Group 之下无子分类时整个 Section 就是单个 Use CaseSubcategorySection 内带缩进条目的命名项目符号如 Testing 下的 Mock每个 Subcategory 就是一个 Use CaseEntry单个条目格式- name - Description.是被收录/被替换/被修剪的最小单位有 PyPI 包名时以 PyPI 包名为显示名否则用仓库名一个值得注意的辨析CONTEXT.md 特意警告不要用 Category 一词——TOC 里虽然叫 categories但规则绑定的是 Use Case 而非 Section。投稿 PR 不能新建 Section 或 Subcategory 来给项目安家结构变更新 Section、新 Subcategory、把过大的 Use Case 拆细是维护者专属操作CONTRIBUTING.md 的 Automatic Rejection 第一条就把PR 创建新的 section 或 subcategory 并往里填内容列为直接关闭项。2.3 Cap每 Use Case 至多 3 个 Obvious Choice 2 个 Challenger硬上限 5ADR 给出的数字是最多 3 个 Obvious Choices外加最多 2 个标记为 Challenger 的条目硬上限 5并注明numbers provisional, to be reviewed after the prune——数字是临时性的要在清剪完成后复审。CONTRIBUTING.md 对此的表述进一步澄清了数字与质的关系Hard maximum: 5 entries per use case. This is a qualitative bar first and a numeric backstop second — most use cases should carry fewer.即先定性门槛后数量兜底是天花板而非地板一个新建的 Use Case 完全可以只放 1 个条目。CONTEXT.md 中 Cap 词条的措辞与之一致a ceiling, not a floor。两层条目的区别与准入标准Obvious Choice资深 Python 开发者被问到这件事用什么时会不假思索说出的名字。注意 CONTEXT.md 标注旧名 Industry Standard 为应避免项Challenger还不是显而易见选择、但是某个在位者的可信继任者。其准入要求采用轨迹证据adoption-trajectory evidence而不是单纯的流行度。旧泳道名 Rising Star 和 Hidden Gem 均被标注废弃——ADR《Considered options》解释了原因Rising Star 的势头在新模型下应作为 Challenger 名额或 Displacement 论据的证据Hidden Gem 则与obvious在定义上互斥。条目文本中没有任何 Challenger 标记——位置即标记Use Case 内 Obvious Choices 排前、Challengers 排后各自按 PyPI 月下载量降序标准库模块一律排在使用场景最前无下载量信号的项目agent skill packs、非 PyPI 分发的项目在同层内按字母序殿后。这意味着一个 Use Case 的末尾条目可能就是 Challenger 而非普通在位者。2.4 证据信号PyPI 下载量优先于 GitHub stars且判断保留裁量ADR 规定收录由维护者编辑判断决定判断primarily参考的信号是 PyPI 下载量而非 GitHub stars且判断最终生效stated as final。判断权同时覆盖该信号的已知失效模式CI / 依赖拉高导致的虚高下载量模型类项目以权重文件形式被下载消费而非 pip 安装CONTEXT.md 将这一条扩展到一切非 pip 消费形式如 renpy 的 SDK 下载、thumbor 这类部署型服务大而特定的受众被误读为niche。这套下载量优先的证据链在仓库中有对应工具支撑website/目录提供了三条抓取 PyPI 下载量的实现——website/fetch_pypi_downloads_via_bigquery.pyGoogle BigQuery 官方数据集、website/fetch_pypi_downloads_via_pepy.pyPePy API和 website/fetch_pypi_downloads_via_clickpy.pyClickPy维护者可交叉验证下载量数据另有 website/fetch_github_stars.py 抓取 stars 作为对照参考。而 AGENTS.md 进一步规定每个保留/移除理由都必须在决策时对照实时在线数据核验下载量、仓库活跃度与归档状态、PyPI 元数据、项目文档层级判定obvious choice vs challenger还需检索证据采用轨迹、社区口碑训练数据的记忆不是证据无法核验的必须标注为判断。2.5 Displacement满员后的唯一入口ADR 规定一旦 Use Case 达到上限唯一的进入方式是 Displacement——PR 必须指名它替换的条目并论证新项目把那个条目的活儿干得更好。CONTRIBUTING.md 用 One in, one out 概括且 CONTRIBUTING.md 的 Automatic Rejection 明确Use Case 已满且 PR 没有 Displacement 论证的直接关闭。CONTEXT.md 中还记录了一个相关概念Second TierChallenger 名额可以由被降级的在位者占据如 clickhouse-driver 排在官方客户端之后、django-haystack 排在 Search 场景的后面它同样占用两个 Challenger 名额、同样以位置为标记采用轨迹门槛只约束新准入不约束降级。2.6 标准库、资源类 Section 与追溯清剪标准库只有当 stdlib 模块本身就是该 Use Case 的显而易见选择时才占位——ADR 与 CONTRIBUTING.md 共用同一个判例tomllib yes, unittest noResources 类 SectionNewsletters、Podcasts、Websites暂时不在改革范围内且从源码结构看网站构建管线根本不解析它们CLAUDE.mdResources sections are not project entries: out of audit scope, and the website never parses them追溯清剪retroactive prune存量条目接受同一测试执行方式是分阶段、最差先行的清剪per-section sweep commits每个 Section 一个提交提交体逐一列出移除原因被移除条目直接删除——git 历史就是档案。这一提交纪律在 AGENTS.md 中成文a prune sweep is one commit per section, its body listing each removal with its reason与常规每次提交一个条目的规则互为例外。3. 被否决的备选方案ADR 的价值所在ADR《Considered options》完整保留了三条被否决路线及其否决理由这是理解为什么是现在这套规则的关键备选方案否决理由保留三条泳道、每条泳道都加上限一旦准入变成比较性的够不够好才能进来就是答错了的问题Rising Star 的势头应当转化为 Challenger 名额或 Displacement 的证据Hidden Gem 与obvious定义上互斥只立新规则、不做追溯清剪每个被拒 PR 都会遭遇但 X 还在列表上的先例论证且读者看不到任何变化把被移除条目存档到单独文件等于在一次点击可达处重建目录稀释这次变革要恢复的列表身份这三条否决理由分别对应规则体系中的三处设计Displacement 机制否决项 1、分阶段 prune否决项 2、git history is the archive否决项 3。读 ADR 时应把决策与备选对照着读才能明白为什么直接删除不是粗暴而是刻意选择。4. 后果ADR 明确接受的代价ADR《Consequences》部分逐条列出已接受的代价每一条都值得工程/内容项目做类似重构时参照列表大幅缩水。ADR 给出的量化事实是维护者对三个最大 Section 的预览保留了 80 条中的 45 条并预判most future PRs will be rejected for fullness, not badness——未来多数 PR 会因满员而非项目差被拒主动放弃长尾搜索流量。awesome-python.com 将不再承载数百个小众工具名因此失去对应的长尾检索流量。ADR 的表态是明确接受的reader trust over search surface读者信任优先于搜索覆盖面快速变化领域靠 Displacement 吸收流失。AI and Agents 这类领域按当前用量列出领跑者人员/项目更替通过 Displacement 完成过大的 Use Case 由维护者修剪或 Split拆分为更细的 Use Case。CONTEXT.md 对 Split 的定义是在规模反映真正不同的活儿时优先于任何修剪考虑的、维护者专属的结构重组外链 awesome-* 列表作为泄压阀。CONTRIBUTING.md 明确指向这类列表例如 awesome-python-testingthey exist precisely so this list doesnt have to be one——想要穷举目录的读者走那些列表本列表因此不必成为目录。5. 规则如何落地仓库中的执行证据ADR 是决定而本仓库中至少有四处机制保证决定被执行且彼此交叉印证5.1 CONTEXT.md给规则和 LLM 的统一词汇表CONTEXT.md 全文定义了本决策引入的领域语言Entry、Sub-item、Use Case、Obvious Choice、Cap、Displacement、Challenger、Second Tier、Override、Split、Audit并为每个词条附 Avoid 旧名对照。ADR 结尾的 See CONTEXT.md for the vocabulary 正是指向这里。值得一提的是website/ 的构建管线会渲染出 website/templates/llms.txt 对应的 llms.txt 文件——这套结构化词汇同时服务于人类维护者和 LLM 消费者。5.2 CONTRIBUTING.md可执行的准入与拒绝清单CONTRIBUTING.md 把 ADR 的抽象规则翻译成 PR 评审可直接套用的检查项5 条 Quality Requirements、Admission 上限、Displacement、Dual-listing同一工具在多个 Use Case 各占一席须独立挣得每席且是维护者决策、Override 条款维护者可对特定条目/场景显式超限但逐案生效、不可被投稿者引用以及 5 步 Review Process格式、分类、查重、活跃度、准入和 9 条 Automatic Rejection 条款。5.3 docs/audit-logs.md超越单次提交的决策登记册docs/audit-logs.md 是单个 commit 无法展示的维护者决策一览登记册与 ADR 的git history is the archive原则互补普通移除理由写在 prune sweep 的提交体里而结构性例外记在此处。目前已登记两类Naming Exceptions显示名偏离 PyPI 包名规则的 10 个条目如pytorch对应包名torch、jinja对应Jinja2Mature-stable Keeps5 个超出12 个月活动要求但按成熟、稳定、无继任者的编辑判断保留的条目ftfy、itsdangerous、jieba、jinja、sortedcontainers。这正对应 CONTEXT.md 中 Override 词条的定义维护者在 Audit 中做出、显式记录、逐案生效的超限决定且submitters cannot cite one。5.4 构建管线结构词汇与解析器的对应关系website/readme_parser.py 用 markdown-it-py 把 README.md 解析为结构化数据其类型定义与 ADR/CONTEXT 词汇一一对应ParsedGroup↔ Thematic Group、ParsedSection↔ Section、ParsedEntry.subcategory↔ Subcategory、ParsedEntry.also_see↔ Sub-item缩进的 awesome-* 链接不占名额、不计入 Cap、随父条目存亡。模块 docstring 还记录了几个对 README 编辑者很重要的经验事实## Projects之前的内容被忽略新增 Subcategory 不需要改解析器无前置链接的项目符号 缩进条目即可被识别构建输出的 Total entries 统计包含 Sub-item 而不仅是 Entry。这说明 ADR 的结构由列表既有结构定义在技术上是可自举的——结构词汇表与解析器、CONTRIBUTING 规则、审计流程形成了闭环。6. 小结一份可复用的列表瘦身决策模板ADR 0001 的价值不止于 awesome-python 自身它完整示范了内容型/索引型开源项目从目录转向短名单时的决策结构先用数据定义病态576 条、24x 流入、AI 类 41 条再给重构立一个可检验的单句目标Zen of Python 的 one obvious way规则按边界测试 → 单位Use Case→ 名额Cap→ 信号PyPI 下载量→ 满员入口Displacement→ 追溯清剪顺序定义并明确数字是临时值、留待清剪后复审备选方案与否决理由同文保留防止规则在后续评审中被还原代价显式入账缩水幅度、搜索流量、快速领域的更替机制避免重构后各方对结果各执一词词汇表CONTEXT.md、操作规范CONTRIBUTING.md、决策登记册audit-logs.md、构建管线readme_parser.py / llms.txt四件套保证决策不悬浮在文档层而是可执行、可审计、可被机器消费的。如果需要在 awesome-python 中提交或评审条目请以 CONTRIBUTING.md 为操作准绳、以 CONTEXT.md 为术语基准并留意 docs/audit-logs.md 中已登记的例外——那正是本 ADR 所说的判断保留裁量但裁量被记录的具体体现。【免费下载链接】awesome-pythonThe definitive list that answers I want to do X in Python, which tool should I use?项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 awesome-python ADR 0001 详解：把列表从“目录“重构为“显而易见选择的短名单“
awesome-python ADR 0001 详解把列表从目录重构为显而易见选择的短名单【免费下载链接】awesome-pythonThe definitive list that answers I want to do X in Python, which tool should I use?项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python本文基于 awesome-python 仓库中的架构决策记录 docs/adr/0001-shortlist-not-catalog.md状态accepted完整还原一次编辑策略重构的决策过程为什么一个条目超过 576 条、分类无限膨胀的 awesome-* 列表要放弃目录catalog定位转而成为回答I want to do X in Python, which tool should I use?这一唯一问题的短名单shortlist。读完后你将掌握这套 curation 体系的完整规则Use Case、Obvious Choice、Challenger、Displacement、Cap、Split、其证据链来源PyPI 下载量而非 GitHub stars、以及规则如何在 CONTRIBUTING.md、CONTEXT.md、docs/audit-logs.md 和网站构建管线中落地执行。1. 背景旧的收录模型如何失效ADR 记录了触发重构的三个事实均以 2026 年中为时间基准列表当时持有576 个条目分布在 75 个 Section。当前 README.md 中的###章节数为 77含后续增减与这一量级吻合条目流入量同比增长24 倍过去 12 个月新增 96 条而前一年只有 4 条且增量集中在 AI and Agents 这类 Section该 Section 曾达 41 个条目旧的收录模型是三条泳道——Industry Standard、Rising Star、Hidden Gem且只有第一条泳道有上限。这个模型会接纳任何孤立来看足够好的项目结果是分类无限增长列表不再回答读者的实际问题X 这件事我用什么重构的哲学依据被直接写进 ADR即 Zen of Python 的一条There should be one — and preferably only one — obvious way to do it.也就是说列表的定位从好的 Python 项目大全收窄为每个使用场景下显而易见的少数选择。2. 决策内容新规则的完整定义这一节逐条继承 ADR《The decision》部分并结合仓库文件补充其执行细节。2.1 收录边界测试从用 Python 写的变为服务 Python 开发者ADR 用一个新测试替换了旧要求primarily written in Python (50%)新测试Serves Python Developers只要 Python 开发者在自己的 Python 工作中使用它实现语言和打包方式就无关紧要——uv和ty是 Rust 写的agent skill packs 是 markdown都属于反过来一个没人会在 Python 工作中使用的纯 Python 项目不收录CONTEXT.md 中显式标注旧术语为应避免项_Avoid_: Python-first, written-in-Python (old requirement — removed)防止旧心智模型回流。CONTRIBUTING.md 的Quality Requirements第一条与该测试完全对齐并给出四个并行的硬性质量门槛Active12 个月内有提交、Stable非 alpha/beta/experimental、DocumentedREADME 有示例和用例说明、Established仓库至少 1 个月历史。2.2 Use Case 结构投稿者不能创造自己需要的分类ADR 规定 Use Case 由列表既有结构定义an entry PR can never create the subcategory it needs。结合 CONTEXT.md 的结构词汇表列表的层级是层级定义与规则的关系Thematic Group粗体分组行如 AI ML、Web Development在 TOC 和正文中聚类 Section纯组织不绑定规则SectionREADME.md 中的###标题如 Testing、AI and Agents位于某个 Thematic Group 之下无子分类时整个 Section 就是单个 Use CaseSubcategorySection 内带缩进条目的命名项目符号如 Testing 下的 Mock每个 Subcategory 就是一个 Use CaseEntry单个条目格式- name - Description.是被收录/被替换/被修剪的最小单位有 PyPI 包名时以 PyPI 包名为显示名否则用仓库名一个值得注意的辨析CONTEXT.md 特意警告不要用 Category 一词——TOC 里虽然叫 categories但规则绑定的是 Use Case 而非 Section。投稿 PR 不能新建 Section 或 Subcategory 来给项目安家结构变更新 Section、新 Subcategory、把过大的 Use Case 拆细是维护者专属操作CONTRIBUTING.md 的 Automatic Rejection 第一条就把PR 创建新的 section 或 subcategory 并往里填内容列为直接关闭项。2.3 Cap每 Use Case 至多 3 个 Obvious Choice 2 个 Challenger硬上限 5ADR 给出的数字是最多 3 个 Obvious Choices外加最多 2 个标记为 Challenger 的条目硬上限 5并注明numbers provisional, to be reviewed after the prune——数字是临时性的要在清剪完成后复审。CONTRIBUTING.md 对此的表述进一步澄清了数字与质的关系Hard maximum: 5 entries per use case. This is a qualitative bar first and a numeric backstop second — most use cases should carry fewer.即先定性门槛后数量兜底是天花板而非地板一个新建的 Use Case 完全可以只放 1 个条目。CONTEXT.md 中 Cap 词条的措辞与之一致a ceiling, not a floor。两层条目的区别与准入标准Obvious Choice资深 Python 开发者被问到这件事用什么时会不假思索说出的名字。注意 CONTEXT.md 标注旧名 Industry Standard 为应避免项Challenger还不是显而易见选择、但是某个在位者的可信继任者。其准入要求采用轨迹证据adoption-trajectory evidence而不是单纯的流行度。旧泳道名 Rising Star 和 Hidden Gem 均被标注废弃——ADR《Considered options》解释了原因Rising Star 的势头在新模型下应作为 Challenger 名额或 Displacement 论据的证据Hidden Gem 则与obvious在定义上互斥。条目文本中没有任何 Challenger 标记——位置即标记Use Case 内 Obvious Choices 排前、Challengers 排后各自按 PyPI 月下载量降序标准库模块一律排在使用场景最前无下载量信号的项目agent skill packs、非 PyPI 分发的项目在同层内按字母序殿后。这意味着一个 Use Case 的末尾条目可能就是 Challenger 而非普通在位者。2.4 证据信号PyPI 下载量优先于 GitHub stars且判断保留裁量ADR 规定收录由维护者编辑判断决定判断primarily参考的信号是 PyPI 下载量而非 GitHub stars且判断最终生效stated as final。判断权同时覆盖该信号的已知失效模式CI / 依赖拉高导致的虚高下载量模型类项目以权重文件形式被下载消费而非 pip 安装CONTEXT.md 将这一条扩展到一切非 pip 消费形式如 renpy 的 SDK 下载、thumbor 这类部署型服务大而特定的受众被误读为niche。这套下载量优先的证据链在仓库中有对应工具支撑website/目录提供了三条抓取 PyPI 下载量的实现——website/fetch_pypi_downloads_via_bigquery.pyGoogle BigQuery 官方数据集、website/fetch_pypi_downloads_via_pepy.pyPePy API和 website/fetch_pypi_downloads_via_clickpy.pyClickPy维护者可交叉验证下载量数据另有 website/fetch_github_stars.py 抓取 stars 作为对照参考。而 AGENTS.md 进一步规定每个保留/移除理由都必须在决策时对照实时在线数据核验下载量、仓库活跃度与归档状态、PyPI 元数据、项目文档层级判定obvious choice vs challenger还需检索证据采用轨迹、社区口碑训练数据的记忆不是证据无法核验的必须标注为判断。2.5 Displacement满员后的唯一入口ADR 规定一旦 Use Case 达到上限唯一的进入方式是 Displacement——PR 必须指名它替换的条目并论证新项目把那个条目的活儿干得更好。CONTRIBUTING.md 用 One in, one out 概括且 CONTRIBUTING.md 的 Automatic Rejection 明确Use Case 已满且 PR 没有 Displacement 论证的直接关闭。CONTEXT.md 中还记录了一个相关概念Second TierChallenger 名额可以由被降级的在位者占据如 clickhouse-driver 排在官方客户端之后、django-haystack 排在 Search 场景的后面它同样占用两个 Challenger 名额、同样以位置为标记采用轨迹门槛只约束新准入不约束降级。2.6 标准库、资源类 Section 与追溯清剪标准库只有当 stdlib 模块本身就是该 Use Case 的显而易见选择时才占位——ADR 与 CONTRIBUTING.md 共用同一个判例tomllib yes, unittest noResources 类 SectionNewsletters、Podcasts、Websites暂时不在改革范围内且从源码结构看网站构建管线根本不解析它们CLAUDE.mdResources sections are not project entries: out of audit scope, and the website never parses them追溯清剪retroactive prune存量条目接受同一测试执行方式是分阶段、最差先行的清剪per-section sweep commits每个 Section 一个提交提交体逐一列出移除原因被移除条目直接删除——git 历史就是档案。这一提交纪律在 AGENTS.md 中成文a prune sweep is one commit per section, its body listing each removal with its reason与常规每次提交一个条目的规则互为例外。3. 被否决的备选方案ADR 的价值所在ADR《Considered options》完整保留了三条被否决路线及其否决理由这是理解为什么是现在这套规则的关键备选方案否决理由保留三条泳道、每条泳道都加上限一旦准入变成比较性的够不够好才能进来就是答错了的问题Rising Star 的势头应当转化为 Challenger 名额或 Displacement 的证据Hidden Gem 与obvious定义上互斥只立新规则、不做追溯清剪每个被拒 PR 都会遭遇但 X 还在列表上的先例论证且读者看不到任何变化把被移除条目存档到单独文件等于在一次点击可达处重建目录稀释这次变革要恢复的列表身份这三条否决理由分别对应规则体系中的三处设计Displacement 机制否决项 1、分阶段 prune否决项 2、git history is the archive否决项 3。读 ADR 时应把决策与备选对照着读才能明白为什么直接删除不是粗暴而是刻意选择。4. 后果ADR 明确接受的代价ADR《Consequences》部分逐条列出已接受的代价每一条都值得工程/内容项目做类似重构时参照列表大幅缩水。ADR 给出的量化事实是维护者对三个最大 Section 的预览保留了 80 条中的 45 条并预判most future PRs will be rejected for fullness, not badness——未来多数 PR 会因满员而非项目差被拒主动放弃长尾搜索流量。awesome-python.com 将不再承载数百个小众工具名因此失去对应的长尾检索流量。ADR 的表态是明确接受的reader trust over search surface读者信任优先于搜索覆盖面快速变化领域靠 Displacement 吸收流失。AI and Agents 这类领域按当前用量列出领跑者人员/项目更替通过 Displacement 完成过大的 Use Case 由维护者修剪或 Split拆分为更细的 Use Case。CONTEXT.md 对 Split 的定义是在规模反映真正不同的活儿时优先于任何修剪考虑的、维护者专属的结构重组外链 awesome-* 列表作为泄压阀。CONTRIBUTING.md 明确指向这类列表例如 awesome-python-testingthey exist precisely so this list doesnt have to be one——想要穷举目录的读者走那些列表本列表因此不必成为目录。5. 规则如何落地仓库中的执行证据ADR 是决定而本仓库中至少有四处机制保证决定被执行且彼此交叉印证5.1 CONTEXT.md给规则和 LLM 的统一词汇表CONTEXT.md 全文定义了本决策引入的领域语言Entry、Sub-item、Use Case、Obvious Choice、Cap、Displacement、Challenger、Second Tier、Override、Split、Audit并为每个词条附 Avoid 旧名对照。ADR 结尾的 See CONTEXT.md for the vocabulary 正是指向这里。值得一提的是website/ 的构建管线会渲染出 website/templates/llms.txt 对应的 llms.txt 文件——这套结构化词汇同时服务于人类维护者和 LLM 消费者。5.2 CONTRIBUTING.md可执行的准入与拒绝清单CONTRIBUTING.md 把 ADR 的抽象规则翻译成 PR 评审可直接套用的检查项5 条 Quality Requirements、Admission 上限、Displacement、Dual-listing同一工具在多个 Use Case 各占一席须独立挣得每席且是维护者决策、Override 条款维护者可对特定条目/场景显式超限但逐案生效、不可被投稿者引用以及 5 步 Review Process格式、分类、查重、活跃度、准入和 9 条 Automatic Rejection 条款。5.3 docs/audit-logs.md超越单次提交的决策登记册docs/audit-logs.md 是单个 commit 无法展示的维护者决策一览登记册与 ADR 的git history is the archive原则互补普通移除理由写在 prune sweep 的提交体里而结构性例外记在此处。目前已登记两类Naming Exceptions显示名偏离 PyPI 包名规则的 10 个条目如pytorch对应包名torch、jinja对应Jinja2Mature-stable Keeps5 个超出12 个月活动要求但按成熟、稳定、无继任者的编辑判断保留的条目ftfy、itsdangerous、jieba、jinja、sortedcontainers。这正对应 CONTEXT.md 中 Override 词条的定义维护者在 Audit 中做出、显式记录、逐案生效的超限决定且submitters cannot cite one。5.4 构建管线结构词汇与解析器的对应关系website/readme_parser.py 用 markdown-it-py 把 README.md 解析为结构化数据其类型定义与 ADR/CONTEXT 词汇一一对应ParsedGroup↔ Thematic Group、ParsedSection↔ Section、ParsedEntry.subcategory↔ Subcategory、ParsedEntry.also_see↔ Sub-item缩进的 awesome-* 链接不占名额、不计入 Cap、随父条目存亡。模块 docstring 还记录了几个对 README 编辑者很重要的经验事实## Projects之前的内容被忽略新增 Subcategory 不需要改解析器无前置链接的项目符号 缩进条目即可被识别构建输出的 Total entries 统计包含 Sub-item 而不仅是 Entry。这说明 ADR 的结构由列表既有结构定义在技术上是可自举的——结构词汇表与解析器、CONTRIBUTING 规则、审计流程形成了闭环。6. 小结一份可复用的列表瘦身决策模板ADR 0001 的价值不止于 awesome-python 自身它完整示范了内容型/索引型开源项目从目录转向短名单时的决策结构先用数据定义病态576 条、24x 流入、AI 类 41 条再给重构立一个可检验的单句目标Zen of Python 的 one obvious way规则按边界测试 → 单位Use Case→ 名额Cap→ 信号PyPI 下载量→ 满员入口Displacement→ 追溯清剪顺序定义并明确数字是临时值、留待清剪后复审备选方案与否决理由同文保留防止规则在后续评审中被还原代价显式入账缩水幅度、搜索流量、快速领域的更替机制避免重构后各方对结果各执一词词汇表CONTEXT.md、操作规范CONTRIBUTING.md、决策登记册audit-logs.md、构建管线readme_parser.py / llms.txt四件套保证决策不悬浮在文档层而是可执行、可审计、可被机器消费的。如果需要在 awesome-python 中提交或评审条目请以 CONTRIBUTING.md 为操作准绳、以 CONTEXT.md 为术语基准并留意 docs/audit-logs.md 中已登记的例外——那正是本 ADR 所说的判断保留裁量但裁量被记录的具体体现。【免费下载链接】awesome-pythonThe definitive list that answers I want to do X in Python, which tool should I use?项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考