Python包的编译、构建与打包指南

Python包的编译、构建与打包是将你的代码转换为可分发的格式，以便其他人可以轻松安装和使用你的项目。以下是完整的流程说明：

1. 准备工作

项目结构

一个标准的Python项目通常具有以下结构：

my_package/
├── my_package/          # 主包目录
│   ├── __init__.py     # 包初始化文件
│   └── module.py       # 模块文件
├── tests/              # 测试目录
├── docs/               # 文档目录
├── setup.py            # 构建配置文件
├── pyproject.toml      # 现代构建配置(可选)
└── README.md           # 项目说明

2. 构建工具
现代Python打包主要使用以下工具：
setuptools (传统方式)

# setup.py 示例
from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1.0",
    packages=find_packages(),
    install_requires=[
        'requests>=2.25.1',
        'numpy>=1.20.0',
    ],
    python_requires='>=3.6',
)

pyproject.toml (现代方式)

# pyproject.toml 示例
[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "0.1.0"
authors = [
    {name="Your Name", email="your@email.com"},
]
description = "A short description of your package"
readme = "README.md"
requires-python = ">=3.6"
dependencies = [
    "requests>=2.25.1",
    "numpy>=1.20.0",
]

[project.optional-dependencies]
dev = ["pytest>=6.0.0", "black>=21.0"]

3. 构建包
安装构建工具

pip install build

构建包

python -m build

这会生成两个文件在dist/目录：
• .tar.gz源码包
• .whl wheel包
4. 打包扩展模块
如果你的包包含C/C++扩展：
setup.py配置扩展

from setuptools import Extension, setup

module = Extension(
    'my_package.mymodule',
    sources=['my_package/mymodule.c'],
    include_dirs=['/path/to/include'],
    libraries=['m'],  # 链接数学库
)

setup(
    # ...其他参数...
    ext_modules=[module],
)

使用Cython

from setuptools import setup
from Cython.Build import cythonize

setup(
    # ...其他参数...
    ext_modules=cythonize("my_package/*.pyx"),
)

5. 发布包

本地安装测试

pip install dist/my_package-0.1.0-py3-none-any.whl

发布到PyPI
1. 创建PyPI账号
2. 安装twine

pip install twine

上传包

twine upload dist/*

6. 高级主题
版本管理
推荐使用bumpversion或手动更新__version__变量
多平台构建
使用CI/CD工具如GitHub Actions构建多平台wheel
打包数据文件
在setup.py中：

package_data={
    'my_package': ['data/*.json'],
},

入口点(命令行工具)

entry_points={
    'console_scripts': [
        'mycli=my_package.cli:main',
    ],
},

7. 现代工具链
• Poetry: 全功能依赖管理和打包工具
• Flit: 简单项目的轻量级打包工具
• Hatch: 新一代项目管理工具
Poetry示例

# pyproject.toml
[tool.poetry]
name = "my_package"
version = "0.1.0"
description = "My package description"
authors = ["Your Name <your@email.com>"]

[tool.poetry.dependencies]
python = "^3.6"
requests = "^2.25.1"

[tool.poetry.dev-dependencies]
pytest = "^6.0.0"

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

构建命令：

poetry build

总结
Python打包生态系统正在向pyproject.toml标准化发展。对于新项目，建议：
1. 使用pyproject.toml作为主要配置文件
2. 选择setuptools、Poetry或Flit作为构建后端
3. 使用python -m build构建包
4. 使用twine上传到PyPI
记得在发布前充分测试你的包，包括在不同环境和平台上测试安装和使用。