Python 新规范 pyproject.toml 完全解析

news2025/2/4 12:45:50

多谢：thank

Python从PEP 518开始引入的使用pyproject.toml管理项目元数据的方案。

该规范目前已经在很多开源项目中得以支持：

Django 这个 Python 生态的顶级项目在 5 个月之前开始使用 pyproject.toml
Pytest 这个 Python 生态测试框架的领头羊在 4 个月之前开始使用 pyproject.toml
SciPy 这机器学习的库也在 3 周前切到了 pyproject.toml
poetry包管理可以直拉生成toml文件

pyproject.toml 实践

工程结构

PyPI 的旧时代的因为规范太松散了，每个项目的结构都五花八门。现在好了，pyproject.toml 它在 Python 项目的结构上都有一个推荐风式了。假设我们软件包的名字是 npts ，那么整个项目的目录结构在推荐的风格下看起来应该像这样。

假设我们软件包的名字是 npts ，那么整个项目的目录结构在推荐的风格下看起来应该像这样。

tree ./ ./ 
├── LICENSE 
├── README.md 
├── pyproject.toml 
├── src 
│ └── npts # src 下面是包名，包下面是业务代码 
│      ├── __init__.py 
|      └── core.py 
└── tests 3 directories, 5 files

3 directories, 5 files

简单地在 src/npts/core.py 加一个函数，模拟我们的业务逻辑。

# -*- coding: utf8 -*- 
def hello(name: str = "world"): 
    return f"hello {name} ."

pyproject.toml

[project] 
name = "npts"
version = "0.0.1" 

[build-system] 
requires = ["hatchling"] 
build-backend = "hatchling.build"

安装 build 依赖并用 build 来打包

# 安装依赖
python3 -m pip install --upgrade build

# 打包
python3 -m build
# ...
#... ... Successfully built npts-0.0.1.tar.gz and npts-0.0.1-py2.py3-none-any.whl

编译过程中，会产生如下的输出信息：

该命令执行完后，会在dist目录中生成如下红框内的文件：

其中，tar.gz文件是源发行版a source distribution ，而.whl文件是构建发行版a built distribution。

把打包好的软件包上传到 PyPI

twine upload dist/npts-0.0.1-py3-none-any.whl
或 
poetry -m publish #上传发布

安装包

pip3 install npts

pyproject.toml 完整参数说明

[tool.poetry] # 是最基本的section，然后它由多个 sections 组成

name #package 名字，必填
version #package 版本号  ，必填
description #package 描述  ，必填
license #package 许可证，可选
authors #package 作者，必填
maintainers #package 维护者，可选
readme #package readme 文件，可选
README.rst 或 README.md
homepage #package 项目网站的 URL，可选
repository #package 指向项目 repository 的 URL，可选
documentation #package 项目文档的 URL，可选

keywords #与 package 相关的关键字列表(最多5个)，可选

[dependencies] and [dev-dependencies]
# 默认情况下，poetry 会从 Pypi 库中查找依赖项，只需要写名称、版本就行了

[tool.poetry.dependencies]
python = "^3.9" # 重点：必须声明与包兼容的python版本 python = "^3.9" 
requests = "^2.26.0"

[[tool.poetry.source]] # 使用私有存储库
name = 'private'
url = 'http://example.com/simple'

[extras] #支持可选依赖项
...

[tool.poetry.dependencies] # 这些软件包是强制性的
mandatory = "^1.0"
psycopg2 = { version = "^2.7", optional = true }    # 可选依赖项列表，可自行选择安装哪些
mysqlclient = { version = "^1.3", optional = true }
 
[tool.poetry.extras] 
mysql = ["mysqlclient"]
pgsql = ["psycopg2"]