打包 Python 库

从一堆脚本到可安装的库

放在一堆脚本文件夹里的代码，只能在一台机器上为一个人工作，直到有一天别人需要它，或者你需要在另一个环境里运行它。打包会把你的代码变成有名称、版本和声明依赖的库，任何人都可以用 pip install 安装。团队借此共享定价库而不必到处复制文件，研究笔记本和生产任务运行完全相同的代码，一个缺陷修复也能通过新的版本号送达每个人。

# Versions are numbers, not text: compare them as tuples
def parse_version(text):
    parts = [int(part) for part in text.split(".")]
    return tuple(parts + [0] * (3 - len(parts)))

print("1.10" > "1.9")                                # False  as text, "1" < "9" decides it: wrong
print(parse_version("1.10") > parse_version("1.9"))  # True   as numbers (1, 10, 0) is newer than (1, 9, 0)
print(parse_version("2"))                            # (2, 0, 0)

目录结构、pyproject.toml 与构建

常见的目录结构是：代码放在 src/yourlib/（带 __init__.py），测试放在 tests/，根目录放一个 pyproject.toml。这一个文件指定构建工具（[build-system] 表）并描述项目：name、version、说明、支持的 Python 版本和 dependencies。开发时用 pip install -e . 以可编辑模式安装该文件夹，修改立即生效；python -m build 会在 dist/ 中生成 wheel（.whl，可直接安装）和 sdist（源码归档）。版本号只放在一个地方，用户需要时通过 yourlib.__version__ 暴露。

# A minimal pyproject.toml, generated and then read back with tomllib to prove it is valid
import tomllib

def pyproject_toml(name, version, dependencies):
    lines = ["[build-system]", 'requires = ["setuptools>=68"]', 'build-backend = "setuptools.build_meta"', "",
             "[project]", f'name = "{name}"', f'version = "{version}"']
    if dependencies:
        lines += ["dependencies = ["] + [f'    "{d}",' for d in dependencies] + ["]"]
    else:
        lines.append("dependencies = []")
    return "\n".join(lines) + "\n"

text = pyproject_toml("qcpricing", "0.3.0", ["numpy>=1.26", "pandas>=2"])
data = tomllib.loads(text)
print(data["project"]["name"], data["project"]["version"])      # qcpricing 0.3.0
print(data["project"]["dependencies"])                          # ['numpy>=1.26', 'pandas>=2']

版本与版本说明符

大多数库遵循语义化版本：MAJOR.MINOR.PATCH。修复缺陷升级补丁号（1.4.2 到 1.4.3），向后兼容的新功能升级次版本号并把补丁号归零（1.5.0），破坏兼容的改动升级主版本号（2.0.0）。依赖用版本说明符声明：numpy>=1.26,<3 接受从 1.26 起到 3（不含）的任意 NumPy。在诚实的前提下尽量宽松：下限是你测试过的最老版本，只有对你确知会出问题的主版本才设上限。固定精确版本（==）应当放在应用的锁文件里，而不是别人会安装的库里。

# Bumping a version and checking a requirement, with versions compared as tuples
import operator

def parse_version(text):
    parts = [int(part) for part in text.split(".")]
    return tuple(parts + [0] * (3 - len(parts)))

def bump_version(version, part):
    major, minor, patch = parse_version(version)
    return {"major": f"{major + 1}.0.0", "minor": f"{major}.{minor + 1}.0", "patch": f"{major}.{minor}.{patch + 1}"}[part]

OPS = {">=": operator.ge, "<": operator.lt, "==": operator.eq}

def satisfies(version, specifier):
    for clause in specifier.split(","):
        symbol = next(op for op in (">=", "==", "<") if clause.startswith(op))
        if not OPS[symbol](parse_version(version), parse_version(clause[len(symbol):])):
            return False
    return True

print(bump_version("1.4.2", "minor"))                # 1.5.0
print(satisfies("1.26.4", ">=1.26,<3"), satisfies("3.0.0", ">=1.26,<3"))      # True False

# One place for the version: read it from the source instead of repeating it in several files
import re

init_py = """__version__ = "0.3.0"
from .pricing import price
"""
match = re.search(r'^__version__ = "([^"]+)"', init_py, re.MULTILINE)
version = match.group(1)
print(version)                                       # 0.3.0
print(tuple(int(part) for part in version.split(".")))      # (0, 3, 0)

• 打包让代码有名称、版本和声明的依赖，可用 pip install 安装；开发用 pip install -e .，构建用 python -m build。
• pyproject.toml 保存构建系统和 [project] 元数据；版本要按数字元组比较，绝不按文本比较。
• 使用语义化版本（MAJOR.MINOR.PATCH）和宽松的说明符（numpy>=1.26,<3）；绝不修改已发布的版本，并让机密远离软件包。

下一节：量化代码的 CI/CD，在每次修改时自动运行检查。

实验：评分内容

• 用 parse_version 按数字比较版本25 分
• 用 bump_version 发布下一个版本25 分
• 用 satisfies 检查版本要求25 分
• 用 pyproject_toml 描述软件包25 分