python pyproject.toml

聊聊Python的build这玩意儿其实不算新面孔早在Python打包工具链里就默默存在了很久只不过近几年才因为更好的规范性和可扩展性被推到台前。简单说它是Python官方推荐的打包流程前端工具——不是替代setuptools而是把那些繁琐的配置和构建选择封装成一套更统一的调用方式。1它是什么build这个工具本质上是PEP 517和PEP 518这两个提案的产物。以前Python打包基本依赖setup.py直接运行但那种方式把配置、构建和安装逻辑揉在一起不同项目用的构建后端不一样比如setuptools、flit、poetry调用方式也七零八落。build提供了一个标准化的入口无论项目用哪个后端只要它符合PEP 517规范就都能通过python -m build来生成发行包。你可能会觉得这和直接跑python setup.py sdist bdist_wheel有什么区别区别在于中间隔了一层抽象。build不关心你的构建后端是什么它只负责根据pyproject.toml里的声明去调用对应的后端。就像去餐厅吃饭你不需要知道后厨用的是什么锅只要告诉服务员你要什么菜就行。2他能做什么build的主要任务就是生成两种常见的分发格式源码分发包sdist和二进制包wheel。这个过程中它会做几件具体的事情读取pyproject.toml的[build-system]部分确定用哪个构建后端比如setuptools在临时干净的虚拟环境中安装构建依赖运行后端提供的build_wheel和build_sdist接口把产出的.tar.gz和.whl文件放到指定目录默认是dist/实际工作中你经常需要先构建项目再测试或分发。比如团队里有一个项目的依赖比较复杂build可以确保每次构建都在隔离环境中完成不会污染当前环境的依赖。这对于CI/CD流水线尤其重要——每次都在干净的沙箱里构建能避免本地环境遗留的包对产出造成影响。另外build在纯源码分发和wheel分发之间也做了很实用的区分。有些项目依赖C扩展在本地构建wheel可能需要编译器这时候build可以只生成sdist让最终用户在自己的平台上编译。而在打包纯Python项目时直接生成wheel会更快用户安装起来也方便。3怎么使用使用build其实很简单基本上是三步走先安装它pip install build然后在项目根目录有pyproject.toml的地方运行python -m build它会自动在当前目录寻找pyproject.toml构建完毕后把文件放到dist/目录下。如果只想构建其中一种格式也可以加参数python -m build --sdist只生成源码包python -m build --wheel只生成wheel包有个经常被忽略的细节build默认不会生成sdist如果你同时需要两种格式直接用不带参数的命令是最保险的。另外如果项目的构建后端需要安装额外的依赖才能运行build会自动处理用户不需要手动去装那些依赖。还有一个实用技巧如果你在做持续集成可以加上--no-isolation参数跳过临时环境直接在当前环境构建。但建议只在调试时用正式构建还是要用隔离模式避免环境差异导致的问题。4最佳实践说说我个人在项目中摸索出来的几个习惯第一pyproject.toml一定要配置好[build-system]部分。很多新手只配置了元数据却忘了声明构建后端。一个典型的配置长这样[build-system] requires [setuptools61.0, wheel] build-backend setuptools.build_meta这里requires是构建这个项目需要预先安装的依赖build-backend指定了调用的后端。如果用的是flit或poetry对应的后端名称会不一样。第二尽量在你的持续集成脚本里用build而不是直接调后端的命令。比如在GitHub Actions中-name:Build packagerun:|pip install build python -m build --wheel这样做的好处是将来如果换了构建后端只需要改pyproject.toml构建命令完全不需要动。第三做版本发布时多验证一下构建的产物的质量。比如在构建后可以立刻把生成的wheel安装到临时环境测试pipinstalldist/*.whl# 然后执行一些导入测试python-cfrom mypackage import __version__; print(__version__)这样能避免发布后才发现漏文件或版本号错误。第四如果项目的源码里包含非Python文件比如数据文件、模板记得在pyproject.toml里配置好include或使用MANIFEST.in。很多开发者在这上面栽过跟头构建出来的包少了配置文件。5和同类技术对比把build跟其他打包工具放在一起看更能体会它的定位差异。最直接的对比对象是python setup.py系列命令。那套老办法的问题是它把构建逻辑硬编码在setup.py里而且只能配合setuptools用。如果你的项目改用poetry管理依赖setup.py就没什么用了。而build是完全中立的调度器。跟poetry内置的构建功能poetry build相比poetry主要是依赖管理器附带打包功能它的构建逻辑是锁死的只能用自己的后端。而build可以和任何符合PEP 517规范的后端配合你可以在项目里用poetry管理依赖但在构建时依然可以用python -m build。跟flit自带的构建命令flit build类似build更专注于构建这个环节本身。很多时候你发现自己用poetry或flit只是为了它的构建功能其实完全可以只用一个简单的构建后端加build这样项目依赖更少也更灵活。还有一个轻量级的工具叫tqdm的打包方式不过那更偏向于微服务部署场景了。实际项目选型的时候可以这样考虑如果团队里已经用了poetry来管理依赖和版本号那么poetry build就已经够用了没必要额外再加build。如果项目配置简单用setuptools加上pyproject.toml就能搞定那build就是最轻量的选择。如果项目比较复杂# # 关于Python的pyproject.toml聊聊我的理解前段时间帮一个朋友整理他的Python项目他还在用setup.py项目里requirements.txt、setup.cfg、MANIFEST.in各种文件混在一起看着就头疼。我建议他试试pyproject.toml他问我这东西到底好在哪。其实这个问题挺有意思的因为pyproject.toml经历了好几个版本的演变不同阶段它在项目里的角色也不太一样。它到底是什么简单说pyproject.toml是一个用TOML格式写的配置文件放在项目根目录用来告诉Python世界这个项目该怎么构建、怎么打包、需要哪些依赖。TOML这门语言有点像INI但比INI多了层级结构读起来很直观——键值对、数组、表基本就这三板斧。这个文件最初来自PEP 5182016年目的是解决一个长期困扰大家的问题一个Python项目到底应该用什么工具来构建。以前没有统一标准有人用setuptools有人用flit有人写poetry每个工具都要自己的配置方式。pyproject.toml的出现相当于给了大家一个统一的入口不管底层用哪个构建工具配置都放在同一个地方。后来PEP 621又进一步规范了pyproject.toml的格式让项目元数据名字、版本、作者这些信息也有了统一的存放位置。现在最新版的pip、build这些工具都能直接识别pyproject.toml。它到底能做什么说到能力我觉得可以从三个层面来看。第一层也是最基础的替代setup.py和setup.cfg。虽然写一个简单的setup.py难不到哪里去但要维护一个包含复杂配置的setup.py那种感觉就像在写重复代码。我见过一个项目setup.py里用了一大堆条件判断来处理不同平台的依赖读起来简直像在读天书。pyproject.toml用声明式的配置方式把构建工具的配置放进了独立的条目下面清晰得多。第二层管理项目依赖。传统的做法是requirements.txt配上pip freeze但这种方式的问题是谁来确定这些依赖是项目本身需要的还是只是开发过程中临时装的pyproject.toml支持区分不同场景的依赖——运行需要的、测试需要的、文档需要的、开发工具链需要的。这个类比打包行李出门住酒店真正需要的底裤牙刷运行依赖和那些看着好玩但可能用不上的东西可选依赖放在不同的口袋里需要的时候才拿出来。第三层定义构建后端。这是pyproject.toml最核心的革新之处。以前你要用某个构建工具得手动装好然后调用它的命令行。现在只需要在pyproject.toml里声明一下“我用Setuptools作为构建后端”pip就会自动处理剩下的事情。这就好比你跟外卖平台说“我要吃宫保鸡丁”平台自己会去联系对应的餐厅、安排配送你不需要知道厨房里发生了什么。怎么上手用实际用起来并不复杂。假设新建一个项目叫my-tool。在项目根目录创建一个pyproject.toml文件里面至少要有一个[build-system]条目指定构建后端。选择用Setuptools的话可能还需要配套的setup.cfg或者也能集中到pyproject.toml里。不过现在越来越多的项目选择用Poetry或者Flit这两种工具都支持把几乎所有配置写在pyproject.toml里不需要额外配置文件。比如说用Poetry创建一个项目[build-system] requires [poetry-core] build-backend poetry.core.masonry.api [tool.poetry] name my-tool version 0.1.0 description 一个简单的示例项目 authors [你的名字 youexample.com] [tool.poetry.dependencies] python ^3.8 requests ^2.28.0 [tool.poetry.group.dev.dependencies] pytest ^7.0.0这里有几个有意思的地方。requires定义了构建时需要的包build-backend指定了实际干活的构建后端。[tool.poetry]开头的是Poetry自己的配置空间因为pyproject.toml也允许不同工具用tool.工具名来定义自己的配置。运行python -m build或者poetry build就能生成wheel包和sdist包了。如果用Poetry还能用poetry add requests自动更新pyproject.toml。一些值得注意的做法Pyproject.toml虽然灵活但用得不好也会制造麻烦。有几个经验可以参考。每个项目最好只用一种构建工具。不要把Poetry和Setuptools的配置混在一起写容易冲突。选定了就坚持下去除非有特别好的理由要切换。注意Python版本的兼容性。如果你的项目需要支持Python 3.6或更老的版本那么pyproject.toml可能会带来一些限制因为老版本的pip对它的支持不够完善。不过2023年的现在大部分用户已经用的是比较新的Python了。私有包索引需要配置清楚。如果公司内部有PyPI镜像或者用GitLab的包 registry需要在pyproject.toml里加上相关的配置。比如Poetry的方式是在[[tool.poetry.source]]里面配置。依赖版本范围要合理。初学者容易把依赖写死成1.2.3导致用户没法升级补丁版本。推荐用加的方式比如requests2.28.0,3.0.0。这背后的逻辑是希望用户能用上最新的安全修复但也不想看到一个不兼容的大版本更新时项目炸掉。和其他配置方式的对比最后聊聊pyproject.toml跟其他方案的比较。vs setup.py setup.cfg传统方式。setup.py实际上是一个可执行的Python脚本意味着你可以在里面写任意的Python代码来做构建相关的判断。这既是优势也是劣势——灵活性高但容易写出难以维护的配置。pyproject.toml牺牲了这种灵活性换来了可读性和工具的一致性。对于绝大部分项目来说收益大于损失。vs requirements.txtrequirements.txt本质上是一个裸的依赖列表没有版本控制的粒度也没有区分场景的能力。pyproject.toml的依赖管理更结构化。但值得注意的是requirements.txt并没有被取代。很多项目依然会生成一个requirements.txt文件只是它现在是从pyproject.toml锁定的版本中导出来的用于部署环境。角色变了从一个主配置文件变成了一个部署工件。vs Pipfile / PipenvPipenv是早期试图统一Python依赖管理的尝试用Pipfile和Pipfile.lock。但它的设计复杂度过高社区接受度一直不太高。pyproject.toml的设计思路更轻量更接近符合直觉的工作流。vs setup.py的区别setup.py是可以带逻辑的。比如根据操作系统不同选择不同的依赖这在pyproject.toml里需要用构建工具提供的机制来实现比如Setuptools的extras_require 平台标记。一般来说现在不太建议在构建流程里写太复杂的逻辑这样做的好处是构建的可复制性更强。说到底pyproject.toml不是一个银弹它解决的是Python项目长期以来在构建和依赖管理上缺少统一标准的问题。就像每个人家里都会有一个固定的地方放钥匙和钱包——pyproject.toml给了Python项目一个约定俗成的说明书的位置。比如有多个构建阶段或前后端混编那build的隔离构建环境能帮你省去很多脏活累活。说到底build解决的不是能不能构建的问题而是怎么构建得更好的问题。它让构建过程和特定工具解耦这在多人协作和维护长期项目时价值会越来越明显。