拓冰网站定制 
Poetry 多 README 文件支持实战readme 列表配置、源码实现与构建产物验证【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry在 Poetry 项目中一个包往往只对应一个 README 文件但当你需要同时维护「用户使用说明」与「变更日志」、或希望把不同语言的说明文档分开管理时单一readme字段就力不从心。Poetry 为此提供了多个 README 文件的支持通过tool.poetry.readme列表声明一组文档构建时将它们合并进发行版的元数据与产物中。本文以仓库中的with_multiple_readme_files测试夹具为锚点完整讲解多 README 的配置写法、底层源码实现、poetry check校验以及构建后 sdist/wheel 中的实际验证方法帮助你在真实项目中放心使用这一能力。一、为什么要支持多个 README 文件PyPI 与大多数打包工具只接受单个「长描述」即元数据中的Description字段等价于 setuptools 的long_description。但真实项目经常遇到这类诉求README 与 CHANGELOG 分开维护README 面向使用方保持稳定CHANGELOG 随版本频繁更新多语言文档README 按语言拆分为多个文件文档目录化组织把 README 拆进docs/目录按主题管理。Poetry 的解法不是让用户自己拼字符串而是允许在tool.poetry段用列表声明多个 README 路径构建时按顺序拼接。仓库中的测试夹具 tests/fixtures/with_multiple_readme_files 就是这一特性的最小演示README-1.rst内容为Single Python标题占位README-2.rst内容为Changelog两者通过pyproject.toml中的列表声明组合为一个包的文档。二、配置方式两种表段两种语义Poetry 中与 README 相关的配置出现在两个地方语义不同需要注意区分。1.[project]表段单个 READMEPEP 621 标准字段标准project表段下readme只能是一个字符串路径或内联内容[project] name my-package version 0.1 readme README.md局限project.readme本身不支持列表。若希望在该标准字段下使用多个文件必须把readme声明为动态字段再在tool.poetry段提供实际列表详见 docs/pyproject.md[project] name my-package # ... dynamic [readme] [tool.poetry] # ... readme [docs/README1.md, docs/README2.md]2.[tool.poetry]表段字符串或列表tool.poetry.readme可以是一个路径字符串也可以是一组路径的列表。官方文档明确建议如果不需要多文件优先使用project.readme只有多 README 场景才使用tool.poetry段的列表形式见 docs/pyproject.md。列表写法如下[tool.poetry] name my-package version 0.1 readme [README-1.rst, README-2.rst]仓库夹具 tests/fixtures/with_multiple_readme_files/pyproject.toml 即采用这种形式并配合poetry-core作为构建后端[tool.poetry] name my-package version 0.1 description Some description. authors [ Your Name youexample.com ] license MIT readme [ README-1.rst, README-2.rst ] [tool.poetry.dependencies] python ^3.7 [build-system] requires [poetry-core] build-backend poetry.core.masonry.api路径基准README 路径隐含地相对于pyproject.toml所在目录解析因此可以放心写docs/README1.md这类子目录路径。三、源码级解析readme 列表是如何被处理与回写的1. 序列化回写src/poetry/factory.py从源码结构看Factory在把包对象还原为pyproject.toml内容时会遍历package.readmes列表将其转换为相对root_dir的 POSIX 路径并写回content[readme]readmes [] for readme in package.readmes: readme_posix_path readme.as_posix() with contextlib.suppress(ValueError): if package.root_dir: readme_posix_path readme.relative_to(package.root_dir).as_posix() readmes.append(readme_posix_path) if readmes: content[readme] readmes对应实现见 src/poetry/factory.py。这段逻辑说明无论用户在配置里写的是相对路径还是绝对路径Poetry 都会统一归一化为相对pyproject.toml的路径再回写保证配置的可移植性。2. 存在性校验poetry check命令poetry check会实际校验 README 文件是否存在。_validate_readme方法把字符串形式的单一 README 统一包装成列表后逐一检查见 src/poetry/console/commands/check.pydef _validate_readme(self, readme: str | list[str], poetry_file: Path) - list[str]: Check existence of referenced readme files readmes [readme] if isinstance(readme, str) else readme for name in readmes: # ... 检查文件存在性缺失则记录错误校验逻辑同时覆盖[tool.poetry]段的readme与[project]段的readme支持字符串或{file: ...}字典形式。因此配置多 README 后先跑一次poetry check能第一时间发现路径写错或文件缺失的问题。3. 新项目默认生成src/poetry/layouts/layout.pypoetry new在创建项目时会根据--readme选项默认md生成对应的 README 文件并写入pyproject.toml的readme字段见 src/poetry/layouts/layout.py。这意味着多 README 通常是在项目演进过程中手动改造配置而非新建时直接生成。四、构建行为验证多个 README 是否真的进入发行包配置完成后最关心的问题是多个 README 会不会真正进入构建产物仓库的测试用例给出了明确答案。tests/console/commands/test_build.py中的test_build_with_multiple_readme_files见 tests/console/commands/test_build.py完整演示了验证流程复制with_multiple_readme_files夹具到临时目录用Factory().create_poetry(...)加载项目并执行build命令断言dist/下同时生成 sdistmy_package-0.1.tar.gz与 wheelmy_package-0.1-*.whl打开 sdist 压缩包断言其中同时包含两个文件with tarfile.open(sdist_file) as tf: sdist_content tf.getnames() assert my_package-0.1/README-1.rst in sdist_content assert my_package-0.1/README-2.rst in sdist_content同时tests/masonry/builders/test_editable_builder.py 中也有对应的with_multiple_readme_files夹具用于验证可编辑安装editable install场景下多个 README 的处理。你可以复现的验证步骤在任意本地 Poetry 项目中# 1. 在 pyproject.toml 中声明多个 README # readme [README-1.rst, README-2.rst] # 2. 校验配置与文件存在性 poetry check # 3. 构建发行包 poetry build # 4. 查看 sdist 内容确认两个 README 都已打包 tar -tzf dist/my_package-0.1.tar.gz五、合并规则与元数据细节1. 元数据拼接多个 README 的内容会被用来填充发行版元数据的Description字段对应 PyPI 上的长描述等价于 setuptools 的long_description。官方文档明确当指定多个文件时它们按声明顺序用换行符拼接见 docs/pyproject.md。因此列表顺序就是最终文档的呈现顺序请把「主说明」放在前面、「附录/变更记录」放在后面。2. 格式与发布建议README 文件可以是任意格式Markdown、reStructuredText 等但若打算发布到 PyPI建议遵循 PyPI-friendly README 的推荐写法如果希望在 sdist 之外、把 README 同时用于 wheel 的元数据展示多文件拼接后的整体内容都会进入Description字段测试夹具中的README-1.rst与README-2.rst分别使用 reStructuredText 标题语法说明不同文件可以采用同一格式混合使用。3. 大小写敏感的跨平台注意事项官方文档特别提醒见 docs/pyproject.md路径是否大小写敏感遵循平台默认行为但建议保持大小写一致。例如在 macOS/Windows 上可以写readme rEaDmE.mD匹配README.md但 Linux 用户克隆仓库后执行poetry install会因大小写敏感而失败。多 README 场景下务必确保配置中的路径与磁盘上的实际文件名大小写完全一致。六、最佳实践小结结合配置文档与仓库实现使用 Poetry 多 README 功能时建议遵循以下要点单文件优先用[project]只有一个 README 时写在project.readme只有需要多文件时才启用dynamic [readme]配合tool.poetry.readme列表路径相对pyproject.toml所有路径按隐含规则相对项目根目录解析用docs/子目录组织多份文档更清晰顺序即展示顺序多个文件按列表顺序以换行拼接成最终Description重要内容放前面提交前跑poetry check利用其 README 存在性校验避免打包后才发现文件缺失构建后核验产物用poetry buildtar -tzf检查 sdist 内是否同时包含全部 README参考 tests/console/commands/test_build.py 中的断言方式注意大小写与格式保持路径大小写一致以保证 Linux 上可安装并在发布前确认长描述渲染效果。通过readme列表Poetry 让「一份文档」的模型平滑扩展为「一组文档」既保持了 PEP 621 标准的兼容性又为多语言、多主题的文档组织提供了原生支持。本文涉及的夹具 README-1.rst、README-2.rst 与 pyproject.toml 可直接作为最小可运行示例配合 docs/pyproject.md 与 docs/basic-usage.md 一起阅读即可完整掌握这一能力。【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Poetry 多 README 文件支持实战：readme 列表配置、源码实现与构建产物验证
Poetry 多 README 文件支持实战readme 列表配置、源码实现与构建产物验证【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry在 Poetry 项目中一个包往往只对应一个 README 文件但当你需要同时维护「用户使用说明」与「变更日志」、或希望把不同语言的说明文档分开管理时单一readme字段就力不从心。Poetry 为此提供了多个 README 文件的支持通过tool.poetry.readme列表声明一组文档构建时将它们合并进发行版的元数据与产物中。本文以仓库中的with_multiple_readme_files测试夹具为锚点完整讲解多 README 的配置写法、底层源码实现、poetry check校验以及构建后 sdist/wheel 中的实际验证方法帮助你在真实项目中放心使用这一能力。一、为什么要支持多个 README 文件PyPI 与大多数打包工具只接受单个「长描述」即元数据中的Description字段等价于 setuptools 的long_description。但真实项目经常遇到这类诉求README 与 CHANGELOG 分开维护README 面向使用方保持稳定CHANGELOG 随版本频繁更新多语言文档README 按语言拆分为多个文件文档目录化组织把 README 拆进docs/目录按主题管理。Poetry 的解法不是让用户自己拼字符串而是允许在tool.poetry段用列表声明多个 README 路径构建时按顺序拼接。仓库中的测试夹具 tests/fixtures/with_multiple_readme_files 就是这一特性的最小演示README-1.rst内容为Single Python标题占位README-2.rst内容为Changelog两者通过pyproject.toml中的列表声明组合为一个包的文档。二、配置方式两种表段两种语义Poetry 中与 README 相关的配置出现在两个地方语义不同需要注意区分。1.[project]表段单个 READMEPEP 621 标准字段标准project表段下readme只能是一个字符串路径或内联内容[project] name my-package version 0.1 readme README.md局限project.readme本身不支持列表。若希望在该标准字段下使用多个文件必须把readme声明为动态字段再在tool.poetry段提供实际列表详见 docs/pyproject.md[project] name my-package # ... dynamic [readme] [tool.poetry] # ... readme [docs/README1.md, docs/README2.md]2.[tool.poetry]表段字符串或列表tool.poetry.readme可以是一个路径字符串也可以是一组路径的列表。官方文档明确建议如果不需要多文件优先使用project.readme只有多 README 场景才使用tool.poetry段的列表形式见 docs/pyproject.md。列表写法如下[tool.poetry] name my-package version 0.1 readme [README-1.rst, README-2.rst]仓库夹具 tests/fixtures/with_multiple_readme_files/pyproject.toml 即采用这种形式并配合poetry-core作为构建后端[tool.poetry] name my-package version 0.1 description Some description. authors [ Your Name youexample.com ] license MIT readme [ README-1.rst, README-2.rst ] [tool.poetry.dependencies] python ^3.7 [build-system] requires [poetry-core] build-backend poetry.core.masonry.api路径基准README 路径隐含地相对于pyproject.toml所在目录解析因此可以放心写docs/README1.md这类子目录路径。三、源码级解析readme 列表是如何被处理与回写的1. 序列化回写src/poetry/factory.py从源码结构看Factory在把包对象还原为pyproject.toml内容时会遍历package.readmes列表将其转换为相对root_dir的 POSIX 路径并写回content[readme]readmes [] for readme in package.readmes: readme_posix_path readme.as_posix() with contextlib.suppress(ValueError): if package.root_dir: readme_posix_path readme.relative_to(package.root_dir).as_posix() readmes.append(readme_posix_path) if readmes: content[readme] readmes对应实现见 src/poetry/factory.py。这段逻辑说明无论用户在配置里写的是相对路径还是绝对路径Poetry 都会统一归一化为相对pyproject.toml的路径再回写保证配置的可移植性。2. 存在性校验poetry check命令poetry check会实际校验 README 文件是否存在。_validate_readme方法把字符串形式的单一 README 统一包装成列表后逐一检查见 src/poetry/console/commands/check.pydef _validate_readme(self, readme: str | list[str], poetry_file: Path) - list[str]: Check existence of referenced readme files readmes [readme] if isinstance(readme, str) else readme for name in readmes: # ... 检查文件存在性缺失则记录错误校验逻辑同时覆盖[tool.poetry]段的readme与[project]段的readme支持字符串或{file: ...}字典形式。因此配置多 README 后先跑一次poetry check能第一时间发现路径写错或文件缺失的问题。3. 新项目默认生成src/poetry/layouts/layout.pypoetry new在创建项目时会根据--readme选项默认md生成对应的 README 文件并写入pyproject.toml的readme字段见 src/poetry/layouts/layout.py。这意味着多 README 通常是在项目演进过程中手动改造配置而非新建时直接生成。四、构建行为验证多个 README 是否真的进入发行包配置完成后最关心的问题是多个 README 会不会真正进入构建产物仓库的测试用例给出了明确答案。tests/console/commands/test_build.py中的test_build_with_multiple_readme_files见 tests/console/commands/test_build.py完整演示了验证流程复制with_multiple_readme_files夹具到临时目录用Factory().create_poetry(...)加载项目并执行build命令断言dist/下同时生成 sdistmy_package-0.1.tar.gz与 wheelmy_package-0.1-*.whl打开 sdist 压缩包断言其中同时包含两个文件with tarfile.open(sdist_file) as tf: sdist_content tf.getnames() assert my_package-0.1/README-1.rst in sdist_content assert my_package-0.1/README-2.rst in sdist_content同时tests/masonry/builders/test_editable_builder.py 中也有对应的with_multiple_readme_files夹具用于验证可编辑安装editable install场景下多个 README 的处理。你可以复现的验证步骤在任意本地 Poetry 项目中# 1. 在 pyproject.toml 中声明多个 README # readme [README-1.rst, README-2.rst] # 2. 校验配置与文件存在性 poetry check # 3. 构建发行包 poetry build # 4. 查看 sdist 内容确认两个 README 都已打包 tar -tzf dist/my_package-0.1.tar.gz五、合并规则与元数据细节1. 元数据拼接多个 README 的内容会被用来填充发行版元数据的Description字段对应 PyPI 上的长描述等价于 setuptools 的long_description。官方文档明确当指定多个文件时它们按声明顺序用换行符拼接见 docs/pyproject.md。因此列表顺序就是最终文档的呈现顺序请把「主说明」放在前面、「附录/变更记录」放在后面。2. 格式与发布建议README 文件可以是任意格式Markdown、reStructuredText 等但若打算发布到 PyPI建议遵循 PyPI-friendly README 的推荐写法如果希望在 sdist 之外、把 README 同时用于 wheel 的元数据展示多文件拼接后的整体内容都会进入Description字段测试夹具中的README-1.rst与README-2.rst分别使用 reStructuredText 标题语法说明不同文件可以采用同一格式混合使用。3. 大小写敏感的跨平台注意事项官方文档特别提醒见 docs/pyproject.md路径是否大小写敏感遵循平台默认行为但建议保持大小写一致。例如在 macOS/Windows 上可以写readme rEaDmE.mD匹配README.md但 Linux 用户克隆仓库后执行poetry install会因大小写敏感而失败。多 README 场景下务必确保配置中的路径与磁盘上的实际文件名大小写完全一致。六、最佳实践小结结合配置文档与仓库实现使用 Poetry 多 README 功能时建议遵循以下要点单文件优先用[project]只有一个 README 时写在project.readme只有需要多文件时才启用dynamic [readme]配合tool.poetry.readme列表路径相对pyproject.toml所有路径按隐含规则相对项目根目录解析用docs/子目录组织多份文档更清晰顺序即展示顺序多个文件按列表顺序以换行拼接成最终Description重要内容放前面提交前跑poetry check利用其 README 存在性校验避免打包后才发现文件缺失构建后核验产物用poetry buildtar -tzf检查 sdist 内是否同时包含全部 README参考 tests/console/commands/test_build.py 中的断言方式注意大小写与格式保持路径大小写一致以保证 Linux 上可安装并在发布前确认长描述渲染效果。通过readme列表Poetry 让「一份文档」的模型平滑扩展为「一组文档」既保持了 PEP 621 标准的兼容性又为多语言、多主题的文档组织提供了原生支持。本文涉及的夹具 README-1.rst、README-2.rst 与 pyproject.toml 可直接作为最小可运行示例配合 docs/pyproject.md 与 docs/basic-usage.md 一起阅读即可完整掌握这一能力。【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考