awesome-python 如何按 README 格式约束修改条目并避免解析陷阱【免费下载链接】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-pythonawesome-python 的全部目录内容都存在于仓库根目录的 README.md 一个文件里AGENTS.md 称它是 single source of truth站点由website/从它渲染生成。当你需要修改条目新增、删除、改描述、改归类时格式约束实际上有两层——CONTRIBUTING.md 中的 Entry Format Reference以及 website/readme_parser.py 实际执行的解析规则。两层必须同时对齐条目看起来写对了却可能没被解析或者你改动了解析器根本不看的位置。本文给出按约束写条目 → 避开已知解析陷阱 → 用测试验证的完整路径。适用前提所有命令在仓库根目录执行工具链依赖 uvMakefile 中所有目标都通过uv run调用pyproject.toml 声明requires-python 3.14。1. 准备环境make installinstall目标执行uv sync --locked同步锁定版本的依赖构建组包含httpx、jinja2、markdown-it-py测试组包含pytest见 pyproject.toml 的 dependency-groups。2. 条目格式约束命名与五种标准形式命名CONTRIBUTING.md 要求以PyPI 包名作为显示名方便开发者直接复制去pip install并到 PyPI 的 JSON API 确认包的正式名称项目不在 PyPI 时改用 GitHub 仓库名。同时要求尽可能使用 GitHub 仓库 URL——链接到 GitHub 仓库的项目在 awesome-python.com 上排名更高。五种标准形式- [pypi-name](https://github.com/owner/repo) - Description ending with period.标准库模块描述前缀固定为(Python standard library)- [module](https://docs.python.org/3/library/module.html) - (Python standard library) Description.Fork末尾带原项目名的括号说明- [new-name](https://github.com/owner/new-name) - Description (original-name fork).带关联 awesome list 的条目嵌套子项只有链接、没有描述- [project](https://github.com/owner/project) - Description. - [awesome-project](https://github.com/someone/awesome-project)子分类subcategory一个不带前导链接的 bullet下面缩进真正的条目- Subcategory Name - project - Description.上面代码块中的owner/repo、url等为占位符替换为你实际要提交的项目仓库与链接。条目排序同一 use case 内部obvious choices 在前按 PyPI 月下载量从高到低排列challengers 随后同一顺序标准库模块排在整个 use case 最前多个时按字母序没有下载信号的条目agent skill packs、PyPI 之外分发的项目在本层内按字母序排最后。CONTRIBUTING 强调条目文本中没有标记——位置本身就是标记所以一个 use case 的最后几条可能就是 challengers。提交粒度AGENTS.md 要求增删条目时一条 entry 一个 commit例外批量清理prune sweep可以一个 section 一个 commitcommit body 列出每处删除及原因格式、措辞或归类调整可以合并提交。3. 解析器如何读取 README先搞清哪些内容会被解析修改前必须知道解析区域的结构依据 website/readme_parser.py 的parse_readme及其文档字符串## Projects之前的内容全部被忽略。解析区域从文本恰好为Projects的 H1/H2 标题开始到下一个Resources或Contributing标题结束。因此文件顶部的介绍、Sponsors、## Categories目录都不影响条目解析。纯加粗段落是 Thematic Group 标记。Projects 区域内一个内容只有**Group Name**的段落如**AI ML**会结束当前分组并开启新的分组每个标记之下的 H3 标题成为该分组的 category。加粗后跟随其他文字如**Note:** ...不是分组标记。任何分组标记之前出现的 category 归入Other组。Category 描述只在该 section 的第一个段落是单一em块时提取即_Libraries for X._这样的一整行斜体否则描述为空。条目行内联内容以链接开头的 list item 是条目描述取自第一个链接之后的全部内容前导分隔符连字符-、en dash、em dash被剥除。只有链接、没有描述的条目是合法的。子分类标签内联内容在第一个链接之前还有文字的 list item如- MySQL - awesome-mysql被当作子分类标签其缩进子列表才是条目列表。readme_parser 文档字符串明确说明新增子分类不需要改解析器。条目下嵌套的、只有链接的子项被收集为该条目的also_see文档字符串同时提醒构建输出的 Total entries 数字把这类缩进子项也计入不只计条目本身。4. 改条目最容易踩的解析陷阱以下每条都有文档或测试支撑改条目时逐条对照链接前有文字会吞掉整行。想加一个条目却写成- MySQL - awesome-mysql解析器会把整行当成子分类标签条目本身丢失。website/tests/test_readme_parser.py 的test_text_before_link_is_subcategory断言了这一点缩进子列表中的条目被解析而awesome-mysql不出现在条目名里。链接语法写坏。- [name(url)这类漏掉](https://link.gitcode.com/i/1a40b7c17d005fbc9da311037b4fc612) 的test_build_fails_when_group_and_category_slug_collide表明Widgets分组下再出现## Widgets分类时构建抛出ValueErrorslug collision。slug 由slugify生成小写、去非字母数字、空格转连字符所以AI ML与AI-ML 会撞同一个 slug。空 category 让测试失败。test_entry_counts_nonzero要求每个 category 的entry_count 0。把条目拆到新分类后原分类至少要剩一条。描述渲染是转义后的 HTML。描述中的script会渲染成lt;scriptgt;test_description_html_escapes_xss。你不需要自己转义但要知道页面呈现结果与 README 原文不完全一致。URL 必须 http/https。test_all_entries_have_valid_urls要求每个条目和每个also_see的 URL 以http://或https://开头。## Categories后的独立散文会泄漏进 llms.txt。这是 readme_parser 模块文档字符串明确记录的已知行为该区域不要加额外的解释性文字。5. 验证用测试套件确认条目被正确解析改完后在仓库根目录运行完整测试make test对应 Makefile 的uv run pytest website/tests/ -v。其中TestParseRealReadme直接解析真实的 README.md以下断言就是判断条目到位的判据分组数 ≥ 11、category 数 ≥ 69test_at_least_11_groups、test_at_least_69_categoriesContributing不出现在解析出的分类名中每个 category 的entry_count 0每个条目的name非空每个条目与also_see的 URL 均为合法 http/https不存在以[开头却无链接节点的 list item即没有坏链接行。只想验证解析层时可以把 Makefile 的 test 目标收窄到单个测试文件uv run pytest website/tests/test_readme_parser.py -v要查看渲染结果用构建目标make build它执行uv run python website/build.py产物输出到website/output/。make preview在构建基础上监听README.md、website/templates、website/static、website/data的变化自动重建并通过python -m http.server -b 127.0.0.1 -d website/output/ 8000在本地127.0.0.1:8000预览。6. 边界与限制结构变更仅限 maintainer新增 section 或 subcategory 由 maintainer 决定条目 PR cannot create the subcategory it needsCONTRIBUTING.md新建 section/subcategory 并填充属于自动拒绝项之一一个 PR 提交多个项目同样是。Resources 区域不受条目格式约束CLAUDE.md 说明 Resources section not project entries: out of audit scope, and the website never parses them。格式通过不等于被采纳CONTRIBUTING 另有五项质量要求近 12 个月有提交、生产可用、文档清晰、仓库至少 1 个月、服务于 Python 开发者每个 use case 硬上限 5 条用满后唯一入口是 Displacement——指名你的项目替换哪一条并论证做得更好一进一出。make test全部通过意味着新条目被解析器正确识别、无坏链接行、无空分类再执行make build在website/output/看到对应分类页面即完成一次可核对的条目修改。【免费下载链接】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 如何按 README 格式约束修改条目并避免解析陷阱
awesome-python 如何按 README 格式约束修改条目并避免解析陷阱【免费下载链接】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-pythonawesome-python 的全部目录内容都存在于仓库根目录的 README.md 一个文件里AGENTS.md 称它是 single source of truth站点由website/从它渲染生成。当你需要修改条目新增、删除、改描述、改归类时格式约束实际上有两层——CONTRIBUTING.md 中的 Entry Format Reference以及 website/readme_parser.py 实际执行的解析规则。两层必须同时对齐条目看起来写对了却可能没被解析或者你改动了解析器根本不看的位置。本文给出按约束写条目 → 避开已知解析陷阱 → 用测试验证的完整路径。适用前提所有命令在仓库根目录执行工具链依赖 uvMakefile 中所有目标都通过uv run调用pyproject.toml 声明requires-python 3.14。1. 准备环境make installinstall目标执行uv sync --locked同步锁定版本的依赖构建组包含httpx、jinja2、markdown-it-py测试组包含pytest见 pyproject.toml 的 dependency-groups。2. 条目格式约束命名与五种标准形式命名CONTRIBUTING.md 要求以PyPI 包名作为显示名方便开发者直接复制去pip install并到 PyPI 的 JSON API 确认包的正式名称项目不在 PyPI 时改用 GitHub 仓库名。同时要求尽可能使用 GitHub 仓库 URL——链接到 GitHub 仓库的项目在 awesome-python.com 上排名更高。五种标准形式- [pypi-name](https://github.com/owner/repo) - Description ending with period.标准库模块描述前缀固定为(Python standard library)- [module](https://docs.python.org/3/library/module.html) - (Python standard library) Description.Fork末尾带原项目名的括号说明- [new-name](https://github.com/owner/new-name) - Description (original-name fork).带关联 awesome list 的条目嵌套子项只有链接、没有描述- [project](https://github.com/owner/project) - Description. - [awesome-project](https://github.com/someone/awesome-project)子分类subcategory一个不带前导链接的 bullet下面缩进真正的条目- Subcategory Name - project - Description.上面代码块中的owner/repo、url等为占位符替换为你实际要提交的项目仓库与链接。条目排序同一 use case 内部obvious choices 在前按 PyPI 月下载量从高到低排列challengers 随后同一顺序标准库模块排在整个 use case 最前多个时按字母序没有下载信号的条目agent skill packs、PyPI 之外分发的项目在本层内按字母序排最后。CONTRIBUTING 强调条目文本中没有标记——位置本身就是标记所以一个 use case 的最后几条可能就是 challengers。提交粒度AGENTS.md 要求增删条目时一条 entry 一个 commit例外批量清理prune sweep可以一个 section 一个 commitcommit body 列出每处删除及原因格式、措辞或归类调整可以合并提交。3. 解析器如何读取 README先搞清哪些内容会被解析修改前必须知道解析区域的结构依据 website/readme_parser.py 的parse_readme及其文档字符串## Projects之前的内容全部被忽略。解析区域从文本恰好为Projects的 H1/H2 标题开始到下一个Resources或Contributing标题结束。因此文件顶部的介绍、Sponsors、## Categories目录都不影响条目解析。纯加粗段落是 Thematic Group 标记。Projects 区域内一个内容只有**Group Name**的段落如**AI ML**会结束当前分组并开启新的分组每个标记之下的 H3 标题成为该分组的 category。加粗后跟随其他文字如**Note:** ...不是分组标记。任何分组标记之前出现的 category 归入Other组。Category 描述只在该 section 的第一个段落是单一em块时提取即_Libraries for X._这样的一整行斜体否则描述为空。条目行内联内容以链接开头的 list item 是条目描述取自第一个链接之后的全部内容前导分隔符连字符-、en dash、em dash被剥除。只有链接、没有描述的条目是合法的。子分类标签内联内容在第一个链接之前还有文字的 list item如- MySQL - awesome-mysql被当作子分类标签其缩进子列表才是条目列表。readme_parser 文档字符串明确说明新增子分类不需要改解析器。条目下嵌套的、只有链接的子项被收集为该条目的also_see文档字符串同时提醒构建输出的 Total entries 数字把这类缩进子项也计入不只计条目本身。4. 改条目最容易踩的解析陷阱以下每条都有文档或测试支撑改条目时逐条对照链接前有文字会吞掉整行。想加一个条目却写成- MySQL - awesome-mysql解析器会把整行当成子分类标签条目本身丢失。website/tests/test_readme_parser.py 的test_text_before_link_is_subcategory断言了这一点缩进子列表中的条目被解析而awesome-mysql不出现在条目名里。链接语法写坏。- [name(url)这类漏掉](https://link.gitcode.com/i/1a40b7c17d005fbc9da311037b4fc612) 的test_build_fails_when_group_and_category_slug_collide表明Widgets分组下再出现## Widgets分类时构建抛出ValueErrorslug collision。slug 由slugify生成小写、去非字母数字、空格转连字符所以AI ML与AI-ML 会撞同一个 slug。空 category 让测试失败。test_entry_counts_nonzero要求每个 category 的entry_count 0。把条目拆到新分类后原分类至少要剩一条。描述渲染是转义后的 HTML。描述中的script会渲染成lt;scriptgt;test_description_html_escapes_xss。你不需要自己转义但要知道页面呈现结果与 README 原文不完全一致。URL 必须 http/https。test_all_entries_have_valid_urls要求每个条目和每个also_see的 URL 以http://或https://开头。## Categories后的独立散文会泄漏进 llms.txt。这是 readme_parser 模块文档字符串明确记录的已知行为该区域不要加额外的解释性文字。5. 验证用测试套件确认条目被正确解析改完后在仓库根目录运行完整测试make test对应 Makefile 的uv run pytest website/tests/ -v。其中TestParseRealReadme直接解析真实的 README.md以下断言就是判断条目到位的判据分组数 ≥ 11、category 数 ≥ 69test_at_least_11_groups、test_at_least_69_categoriesContributing不出现在解析出的分类名中每个 category 的entry_count 0每个条目的name非空每个条目与also_see的 URL 均为合法 http/https不存在以[开头却无链接节点的 list item即没有坏链接行。只想验证解析层时可以把 Makefile 的 test 目标收窄到单个测试文件uv run pytest website/tests/test_readme_parser.py -v要查看渲染结果用构建目标make build它执行uv run python website/build.py产物输出到website/output/。make preview在构建基础上监听README.md、website/templates、website/static、website/data的变化自动重建并通过python -m http.server -b 127.0.0.1 -d website/output/ 8000在本地127.0.0.1:8000预览。6. 边界与限制结构变更仅限 maintainer新增 section 或 subcategory 由 maintainer 决定条目 PR cannot create the subcategory it needsCONTRIBUTING.md新建 section/subcategory 并填充属于自动拒绝项之一一个 PR 提交多个项目同样是。Resources 区域不受条目格式约束CLAUDE.md 说明 Resources section not project entries: out of audit scope, and the website never parses them。格式通过不等于被采纳CONTRIBUTING 另有五项质量要求近 12 个月有提交、生产可用、文档清晰、仓库至少 1 个月、服务于 Python 开发者每个 use case 硬上限 5 条用满后唯一入口是 Displacement——指名你的项目替换哪一条并论证做得更好一进一出。make test全部通过意味着新条目被解析器正确识别、无坏链接行、无空分类再执行make build在website/output/看到对应分类页面即完成一次可核对的条目修改。【免费下载链接】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），仅供参考