Python中的包管理与模块分发：setuptools与打包格式

1. 问题背景

在Python中，当我们需要共享代码时，通常会将项目打包成可分发的格式，以便其他人可以通过pip安装。这涉及包管理工具（如setuptools）和打包格式（如wheel、sdist）。面试中常问：“如何将一个Python项目打包成可分发的格式？wheel和sdist的区别是什么？”

2. 核心概念：模块、包与分发

• 模块：单个.py文件。
• 包：包含__init__.py的目录，可包含多个模块或子包。
• 分发：将包和元数据（如依赖、作者）打包成标准格式，便于安装。

3. 项目结构规范

一个可分发的项目通常按以下结构组织：

my_project/
├── setup.py           # 打包配置脚本
├── pyproject.toml     # 现代构建配置（可选但推荐）
├── README.md
├── LICENSE
└── my_package/        # 实际代码包
    ├── __init__.py
    └── module.py

4. 配置setuptools

setup.py是核心配置文件，通过setuptools.setup()定义元数据：

from setuptools import setup, find_packages

setup(
    name="my_package",          # 包名（pip install时用）
    version="0.1.0",
    author="Your Name",
    description="A sample package",
    packages=find_packages(),   # 自动发现包
    install_requires=[          # 依赖列表
        "requests>=2.25.1",
        "numpy"
    ],
    python_requires=">=3.6",    # Python版本要求
)

5. 生成分发包：sdist vs wheel

使用命令生成包：

# 生成sdist（源码包）和wheel（二进制包）
python setup.py sdist bdist_wheel

生成的文件在dist/目录下：

• sdist（.tar.gz）：包含源码、配置和元数据。安装时需本地编译，适合纯Python代码或需要自定义编译的场景。
• wheel（.whl）：预编译的二进制格式，安装更快，无需编译。尤其适合含C扩展的包（如numpy）。

6. wheel的优势

1. 安装速度快：无需执行setup.py中的编译步骤。
2. 避免兼容问题：提前编译好特定平台（如Linux/macOS/Windows）的版本。
3. 支持安装时检查依赖：通过元数据直接验证兼容性。

7. 现代配置：pyproject.toml

Python社区推荐使用pyproject.toml替代部分setup.py配置，例如：

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

[project]
name = "my_package"
version = "0.1.0"
dependencies = [
    "requests>=2.25.1",
    "numpy"
]

此文件统一了构建配置，并支持无需setup.py的纯元数据打包。

8. 本地测试与上传

• 本地安装测试：

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

• 上传到PyPI：
  1. 注册PyPI账户，配置API token。
  2. 使用twine工具上传：

  twine upload dist/*
  

9. 总结

• sdist适合源码分发，wheel适合快速安装。
• setuptools是传统打包工具，pyproject.toml是现代化趋势。
• 关键命令：sdist生成源码包，bdist_wheel生成wheel包，twine上传。