1. 什么是 setuptools？ (理解概念)
2. 安装 setuptools 本身 (确保工具可用)
3. 如何使用 setuptools 安装第三方包 (最常见的用法)
4. 如何使用 setuptools 创建和安装自己的项目 (进阶用法)
5. 常见问题与最佳实践

什么是 setuptools？

setuptools 是一个用于打包 Python 代码库的工具，它让你能够：

• 构建：将你的 Python 项目打包成标准的分发格式，.whl (Wheel) 或 .tar.gz (Source Distribution)。
• 安装：将打包好的项目安装到你的 Python 环境中，使其可以被其他项目导入和使用。
• 分发：将你的项目上传到 Python Package Index (PyPI)，方便其他人通过 pip 安装。

setuptools 的核心配置文件是 setup.py，通过这个文件，你可以定义项目的元数据（如名称、版本、作者）和依赖关系等。

安装 setuptools 本身

在绝大多数情况下,你不需要手动安装 setuptools，当你安装 Python 时，setuptools 通常会和 pip 一起被自动安装。

你可以通过以下命令检查是否已安装：

pip show setuptools

如果已安装,你会看到类似下面的输出：

Name: setuptools
Version: 68.2.2
Summary: Easily download, build, install, uninstall, and manage Python packages
Home-page: https://github.com/pypa/setuptools
Author: Python Packaging Authority
Author-email: distutils-sig@python.org
License: MIT
Location: /usr/local/lib/python3.9/site-packages  # (你的路径可能不同)
Requires:
Required-by: pip, wheel

如果你发现没有安装，或者需要升级到最新版本，请使用 pip：

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

重要提示：强烈建议使用 pip 来管理 setuptools，而不是 easy_install（setuptools 自带的一个旧工具），因为 pip 是目前社区的标准。

如何使用 setuptools 安装第三方包

这是 setuptools 最常见的使用场景，我们并不直接运行 setup.py 来安装，而是通过 pip 来完成。pip 在背后会调用 setuptools 的功能。

假设你想安装一个名为 requests 的库：

从 PyPI 安装（最常用）

这是最标准、最推荐的方式。pip 会自动从 PyPI 上查找并下载最新的稳定版本。

pip install requests

从源码安装

如果你下载了一个项目的源码（通常是一个包含 setup.py 文件的压缩包），你可以进入该目录，然后使用 pip 进行安装。

# 1. 下载源码包并解压，例如解压到 my_project 目录
# 2. 进入解压后的目录
cd path/to/my_project
# 3. 使用 pip 从本地源码安装
pip install .

• pip install . 会告诉 pip 在当前目录寻找 setup.py 文件并执行它来安装项目。
• 如果你想安装开发模式下的包（这样你对源码的修改会立即生效），使用：

  pip install -e .

  (-e 代表 editable，即可编辑模式)

如何使用 setuptools 创建和安装自己的项目

当你开发自己的 Python 项目并希望打包它时，setuptools 就派上用场了，你需要创建一个 setup.py 文件。

步骤 1：创建项目结构

一个简单的项目结构如下：

my_awesome_project/
├── my_awesome_package/
│   ├── __init__.py
│   └── core.py
└── setup.py

• my_awesome_package/ 是你的 Python 包。
• __init__.py 文件告诉 Python 这个目录是一个包。
• core.py 是你的代码文件。
• setup.py 是 setuptools 的配置文件。

步骤 2：编写 setup.py 文件

在 my_awesome_project 目录下创建 setup.py 文件，内容如下：

# setup.py
from setuptools import setup, find_packages
# 从 README.md 文件中读取长描述，这是一个好习惯
with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()
setup(
    name="my-awesome-project",  # 项目在 PyPI 上的名称
    version="0.1.0",           # 版本号
    author="Your Name",        # 作者
    author_email="your.email@example.com",  # 作者邮箱
    description="A small example package",  # 简短描述
    long_description=long_description,      # 长描述
    long_description_content_type="text/markdown",  # 指明长描述格式为 Markdown
    url="https://github.com/yourusername/my-awesome-project",  # 项目主页
    packages=find_packages(),  # 自动查找所有包 (会找到 'my_awesome_package')
    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-command=my_awesome_package.core:main_function',
        ],
    },
)

步骤 3：构建你的包

在项目根目录（my_awesome_project）下，运行以下命令来生成分发文件：

# 生成源码分发包 (.tar.gz)
python setup.py sdist
# 生成二进制分发包 (.whl)，推荐使用
python setup.py bdist_wheel

执行后,会生成一个 dist/ 目录，里面包含了打包好的文件。

步骤 4：安装你自己的包

现在你可以像安装第三方包一样安装你自己的项目了。

# 安装 dist 目录下的包
pip install dist/my-awesome-project-0.1.0.tar.gz
# 或者，如果你没有生成 .tar.gz 文件，可以直接安装源码
pip install .

安装成功后,你就可以在 Python 中导入并使用你的包了：

import my_awesome_package
from my_awesome_package.core import main_function

常见问题与最佳实践

问题 1：ModuleNotFoundError: No module named 'setuptools'

原因：你在某个环境中（比如虚拟环境或 Docker 容器）运行 python setup.py，但该环境没有安装 setuptools。

解决：先用 pip 安装它。

pip install setuptools

问题 2：ERROR: Can't find a setup.py file

原因：你在一个不包含 setup.py 文件的目录下运行了 pip install .。

解决：确保你在正确的项目目录下运行该命令。

问题 3：setup.py vs pyproject.toml

现代趋势：setup.py 仍然是广泛使用的标准，但社区正在转向一种更现代的配置方式：pyproject.toml 文件。pyproject.toml 是一个 TOML 格式的配置文件，可以更清晰地分离构建系统依赖（如 setuptools）和项目元数据。

对于新项目,可以考虑使用 Poetry 或 Hatch 等现代构建工具，它们都基于 pyproject.toml，但对于大多数项目，setup.py + pip 的组合依然非常强大和可靠。

最佳实践

1. 始终使用虚拟环境：在开发任何项目时，都应使用 venv 或 conda 等工具创建虚拟环境，以避免包版本冲突。

   python -m venv my_project_env
   source my_project_env/bin/activate  # Linux/macOS
   # my_project_env\Scripts\activate  # Windows

2. 使用 pip 而非 python setup.py install：pip install . 是安装本地项目的标准方式，它能更好地处理依赖关系。
3. 使用 find_packages()：在 setup.py 中，除非有特殊需求，否则总是使用 find_packages() 来自动发现所有包，而不是手动列出包名。
4. 提供清晰的元数据：一个好的 setup.py 应包含 name, version, author, description, license 等关键信息。
5. 声明依赖：在 install_requires 中明确列出你的项目依赖，这能确保用户安装你的包时，所有必需的库也会被自动安装。