Python-setuptools-基本使用

Setuptools 官方文档

介绍

setuptools 是 Python 使用最为广泛的用于构建, 分发, 安装 Python 包的库, 其扩展了标准库 distutils 以提供更多功能.

安装

1
pip install --upgrade setuptools[core]

一般搭配 build 库一起使用, 其提供一种现代化的方式 (用 pyproject.toml) 来构建 source distribution 和二进制分发包 (wheel) 等格式, 代替传统的 setup.py 文件.

1
pip install build

示例

假设有个 python 项目:

1
2
3
4
5
6
my_package/
│
├── my_package/
│   └── __init__.py
│
└── pyproject.toml

pyproject.toml 文件的内容为:

1
2
3
[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

运行:

1
python -m build

则会生成 dist/ 目录和 wheel 包.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
tree
.
├── dist
│   ├── my_package-0.0.0-py3-none-any.whl
│   └── my_package-0.0.0.tar.gz
├── my_package
│   ├── hello.py
│   └── __init__.py
├── my_package.egg-info
│   ├── dependency_links.txt
│   ├── PKG-INFO
│   ├── SOURCES.txt
│   └── top_level.txt
└── pyproject.toml

4 directories, 9 files

基本使用

需要 pyproject.toml 文件以及包含 build-system section:

1
2
3
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
  • requires 指明打包前需要安装什么包
  • build-backend 指明用什么来打包

描述包的 metadata 需要用 [project] section:

1
2
3
4
5
6
7
[project]
name = "mypackage"
version = "0.0.1"
dependencies = [
    "requires",
    'importlib-metadata; python_version<"3.10"'
]

name 和 version 信息会体现在打包的 .whl 文件名上:

(这里指定 name 为 hello, version 为 0.0.1)

注意这里的 dependencies 和 [build-system] section 中的 requires 有所不同, 这里不会打包到 .whl 文件中, 而是方便包被安装时下载一些库.

(这里在 dependencies 中指定 ranger)

同样在 pyproject.toml 所在的目录下运行:

1
python -m build

即可.

Package discovery

即告诉 setuptools 在哪里找要打包的代码, 用 tool table, 默认是:

1
2
3
# ...
[tool.setuptools.packages]
find = {}  # Scan the project directory with the default parameters

其会扫描整个项目目录.

也可以自定义查找路径:

1
2
3
4
5
6
7
[tool.setuptools.packages.find]
# All the following settings are optional:
where = ["src"]  # ["."] by default
include = ["mypackage*"]  # ["*"] by default
exclude = ["mypackage.tests*"]  # empty by default
namespaces = false  # true by default

  • where 指定在 src 目录下查找
  • include 指定要查找的包名
  • exclude 指定要排除的包名
  • namespaces 允许多个分发包共享同一个包的名称空间

比如:

src 目录下有两个包 another_package 和 my_package, 默认情况下:

1
python -m build

打包的结果为:

若修改为:

1
2
3
4
[tool.setuptools.packages.find]
where = ["src"]
include = ["my*"]
namespaces = false

则打包结果为:

Entry point

可以指定包的命令行可执行程序:

1
2
[project.scripts]
cli-name = "mypkg.mymodule:some_func"

表明可以用 cli-name 来调用 mypkg.mymodule 下的 some_func 函数.

比如:

1
2
[project.scripts]
helloo = "my_package.hello:say_hello"

Including Data Files

默认情况下, 数据文件不会被打包, 可以在 MANIFEST.in 文件中指定 data files 列表.

其语法如:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 包含特定的文件
include README.md
include LICENSE

# 包含 data 目录中的所有文件
recursive-include data *

# 排除 tests 目录中的所有文件
recursive-exclude tests *

# 包含所有 .txt 文件
global-include *.txt

# 排除所有临时文件
global-exclude *.tmp

# 排除特定的目录
prune build/
prune dist/

# 包含特定目录
graft docs/
Python
Python-setuptools-基本使用
http://example.com/2024/11/01/Python-setuptools-基本使用/
作者
Jie
发布于
2024年11月1日
许可协议