setuptools 是 Python 的一个核心库，它极大地简化了 Python 项目的打包、分发和安装过程，你可以把它想象成 Python 世界的“构建和安装工具箱”。

什么是 setuptools？为什么需要它？

1. 打包：它允许你将你的 Python 项目（代码、数据、配置等）打包成一个标准的分发格式，最常见的是 wheel (.whl) 文件和 source distribution (.tar.gz) 文件。
2. 分发：打包后的文件可以上传到 Python Package Index (PyPI)，这样全世界其他开发者都可以通过 pip 轻松地安装你的项目。
3. 依赖管理：通过 setup.py 文件，你可以清晰地声明你的项目依赖哪些其他库，setuptools 会确保在安装你的项目时,这些依赖库也被自动安装。
4. 入口点：它允许你创建命令行工具，当你的包被安装后，用户可以在终端直接运行你定义的命令（pip install flask 后可以使用 flask 命令）。
5. 与 pip 的关系：pip 是安装包的工具，而 setuptools 是打包和创建安装元数据的工具。pip 在安装一个从 PyPI 下载的包时，通常依赖于 setuptools 来解包和执行安装脚本。

如何安装 setuptools

通常情况下，setuptools 会作为 pip 的一部分被自动安装，你可以通过以下命令来确保你的环境中拥有最新版本的 setuptools。

使用 pip 安装 (推荐)

这是最标准、最推荐的方法。

# 使用 pip 安装 setuptools
pip install setuptools

如果你想升级到最新版本：

# 升级 setuptools 到最新版本
pip install --upgrade setuptools

下载安装 (离线或特定版本)

如果你在没有网络的环境中，或者需要安装一个非常特定的旧版本,可以从官网下载安装包。

1. 访问 setuptools 官方发布页面。
2. 下载适合你 Python 版本的 .whl 或 .tar.gz 文件。
3. 使用 pip 进行本地安装：

# 假设你下载的文件是 setuptools-68.2.2-py3-none-any.whl
pip install setuptools-68.2.2-py3-none-any.whl

使用 ensurepip (创建新虚拟环境时)

当你创建一个新的 Python 虚拟环境时，venv 模块会自动为你安装 pip 和 setuptools，这是最干净、最隔离的方式。

# 创建一个名为 my_project_env 的新虚拟环境
python -m venv my_project_env
# 激活虚拟环境 (Windows)
my_project_env\Scripts\activate
# 激活虚拟环境 (macOS/Linux)
source my_project_env/bin/activate
# 激活后，setuptools 已经自动安装好了

如何使用 setuptools 创建一个可安装的包

使用 setuptools 的核心是编写一个 setup.py 文件,下面我们通过一个完整的例子来演示。

项目结构

假设我们有一个简单的项目,结构如下：

my_project/
├── my_package/
│   ├── __init__.py
│   └── utils.py
├── README.md
└── setup.py

• my_package/ 是我们的包名。
• __init__.py 使 my_package 成为一个 Python 包。
• utils.py 包含一些我们想分发的代码。
• setup.py 是项目的配置文件。

编写包代码

my_package/utils.py

def greet(name):
    """一个简单的问候函数"""
    return f"Hello, {name}! Welcome to the world of setuptools."
def add(a, b):
    """一个简单的加法函数"""
    return a + b

my_package/__init__.py

# 从 utils 模块导入函数，让它们可以直接从包中调用
from .utils import greet, add
__version__ = "0.1.0" # 定义包的版本号

编写 setup.py 文件

这是最关键的一步。setup.py 文件告诉 setuptools 如何打包你的项目。

setup.py

import setuptools
# 从包的 __init__.py 文件中读取版本号等信息
# 这样可以避免在 setup.py 和 __init__.py 中重复定义版本
version = {}
with open("my_package/__init__.py") as fp:
    exec(fp.read(), version)
# 调用 setup 函数
setuptools.setup(
    name="my-awesome-package", # 你包在 PyPI 上的名字
    version=version['__version__'], # 从 __init__.py 获取版本
    author="Your Name", # 你的名字
    author_email="your.email@example.com", # 你的邮箱
    description="A small example package", # 简短描述
    long_description=open("README.md").read(), # 详细描述，通常从 README.md 读取
    long_description_content_type="text/markdown", # 描述的格式
    url="https://github.com/yourusername/my_project", # 项目主页的 URL
    packages=setuptools.find_packages(), # 自动查找所有包
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License", # 开源许可证
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6', # 最低支持的 Python 版本
    install_requires=[
        # 列出你的项目依赖
        # "requests>=2.20.0",
        # "numpy"
    ],
    entry_points={
        'console_scripts': [
            'my-greet-tool=my_package.utils:greet', # 创建一个命令行工具
        ],
    },
)

构建和安装你的包

在你的项目根目录（即 setup.py 所在的目录）下打开终端,执行以下命令：

1. 安装构建工具 setuptools 本身需要一些工具来构建 wheel 和 source distributions。

   pip install wheel build

2. 构建包 运行 python -m build 命令，这会根据 setup.py 的配置生成两个文件：

   • dist/my_awesome_package-0.1.0-py3-none-any.whl (Wheel 文件,推荐使用)
   • dist/my_awesome_package-0.1.0.tar.gz (Source Distribution 文件)

   # 在项目根目录下执行
   python -m build

3. 安装包 使用 pip 安装刚刚生成的 .whl 文件。

   # pip 会自动找到 dist 目录下的 wheel 文件
   pip install dist/my_awesome_package-0.1.0-py3-none-any.whl

验证安装

安装成功后，你可以在 Python 代码或命令行中测试你的包。

在 Python 中测试：

>>> import my_package
>>> my_package.greet("Alice")
'Hello, Alice! Welcome to the world of setuptools.'
>>> my_package.add(5, 3)
8
>>> my_package.__version__
'0.1.0'

在命令行中测试（如果你定义了 entry_points）：

# my-greet-tool 是你在 setup.py 中定义的命令名
my-greet-tool "Bob"
# 输出: Hello, Bob! Welcome to the world of setuptools.

常见问题

Q1: ModuleNotFoundError: No module named 'setuptools' A: 这表示你的 Python 环境中没有安装 setuptools，请按照上面的“安装 setuptools”部分，使用 pip install setuptools 来安装。

Q2: Error: Could not find a suitable distribution for setuptools A: 这通常发生在 pip 自身需要升级，或者网络有问题，尝试升级 pip：

python -m pip install --upgrade pip

Q3: setup.py 和 pyproject.toml 有什么区别？ A: setup.py 是传统的配置方式。pyproject.toml 是更新的、更标准化的配置方式（PEP 518 引入）。pyproject.toml 将构建系统的配置（需要哪些工具来构建）和项目的元数据（作者、依赖等）分离开，更清晰，现代项目推荐使用 pyproject.toml，但 setup.py 仍然被广泛支持和使用。setuptools 可以同时支持这两种方式。

掌握 setuptools 是从 Python 初学者走向开发者的一个重要里程碑，它让你能够将自己的成果分享给社区,也为管理复杂项目依赖提供了坚实的基础。