Packaging Python Projects

0. Abstract

翻译文档 Packaging Python Projects, 教你打包 Python 包.

1. A Simple Project

首先创建一个文件目录:

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
└── tests/

YOUR_USERNAME_HERE 是为了上传至 PyPI 时不至于和其它学习者上传的包冲突而给包命名的, 换上自己的用户名就好. example.py 的内容为:

def add_one(number):
	return number + 1

2. Choosing a Build Backend

pip 和 build 等工具并不是真的将你的源代码转化成可发行的包(like a wheel); 这项工作由一个 build backend 完成. 就是前端和后端嘛. 常用的后端有: Hatchling, Setuptools, Flit, PDM.

pyproject.toml 文件告诉前端(pip或build)用什么后端, 四种 backend 的配置分别如下(选一个就好):

# Hatchling
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
# setuptools
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
# Flit
[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"
# PDM
[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"

3. Configuring Metadata

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
    { name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/pypa/sampleproject"
Issues = "https://github.com/pypa/sampleproject/issues"

4. Generating Distribution Archives

先安装 build:

python3 -m pip install --upgrade build

在 pyproject.toml 所在的目录下执行:

python3 -m build

就会在当前目录下生成一个文件夹, 其内容如下:

dist/
├── example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
└── example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz

包的构建就完成了. 好简单. 上传至 PyPI 的事就不说了.

4.1 直接 pip 构建安装

除了 python3 -m build, 你也可以在 pyproject.toml 所在的目录下执行:

pip install .  # 其实就是 pip install packaging_tutorial

就会在当前目录下生成一个文件夹, 其内容如下:

build/
├── bdist.linux-x86_64/
└── lib/
    └── example_package_satan/
        ├── __init__.py
        └── example.py

同时将包安装到 python 系统中.