Python包发布与分发

将 Python 包发布到 PyPI，需理解包格式、构建流程与发布规范。

PyPI 发布流程

1. 注册账号

访问 https://pypi.org 注册账号，获取 API Token 用于认证。

2. 配置认证

# 创建 ~/.pypirc
[pypi]
username = __token__
password = pypi-xxx...  # API Token

3. 构建与上传

# 安装构建工具
pip install build twine

# 构建分发包
python -m build

# 上传到 PyPI
twine upload dist/*

测试发布可使用 https://test.pypi.org，避免污染正式仓库。

包格式对比

wheel（二进制分发）

my_package-1.0.0-py3-none-any.whl

特点：

• 预编译格式，安装速度快
• 不需要本地编译环境
• 跨平台支持（通过标签区分）

命名规则：

{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl

sdist（源码分发）

my_package-1.0.0.tar.gz

特点：

• 包含完整源码
• 需要本地编译
• 适合纯 Python 包

建议同时发布 wheel 和 sdist，pip 会优先选择 wheel。

setup.py 配置

基础配置

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="1.0.0",
    author="作者名",
    author_email="email@example.com",
    description="包的简短描述",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    url="https://github.com/user/my_package",
    packages=find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires=">=3.8",
    install_requires=[
        "requests>=2.25.0",
    ],
)

包含非代码文件

setup(
    # ...
    package_data={
        "my_package": ["data/*.json", "templates/*.html"],
    },
    include_package_data=True,
)

pyproject.toml 配置（推荐）

使用 setuptools

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "1.0.0"
description = "包的简短描述"
authors = [{name = "作者名", email = "email@example.com"}]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
]

[project.urls]
Homepage = "https://github.com/user/my_package"

使用 poetry

[tool.poetry]
name = "my_package"
version = "1.0.0"
description = "包的简短描述"
authors = ["作者名 <email@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

版本号规范

遵循语义化版本：MAJOR.MINOR.PATCH

1.0.0 -> 1.0.1  # PATCH: 修复bug
1.0.0 -> 1.1.0  # MINOR: 新功能，向后兼容
1.0.0 -> 2.0.0  # MAJOR: 不兼容的修改

预发布版本：1.0.0a1（alpha）、1.0.0b1（beta）、1.0.0rc1（release candidate）

要点总结

1. wheel 是预编译二进制包，安装快，优先发布
2. sdist 是源码包，适合纯 Python 项目
3. 建议使用 pyproject.toml 替代 setup.py
4. 版本号遵循语义化版本规范
5. 发布前使用 twine check 检查包格式