【python】setuptools

setuptools 是 Python 的一个核心工具包，用于构建、打包和分发 Python 项目。它是 Python 生态系统中最重要的工具之一，主要用于定义项目的元数据（如名称、版本、依赖等）以及构建和安装过程。以下是关于 setuptools 的详细介绍：

---

1. setuptools 的主要功能

setuptools 提供了以下核心功能：

• 项目元数据管理：

  • 定义项目的名称、版本、作者、描述、依赖等信息。
  • 通过 setup() 函数配置这些信息。

• 包发现与安装：

  • 自动发现项目中的 Python 包和模块。
  • 支持安装项目及其依赖。

• 扩展模块支持：

  • 支持编译和安装 C/C++ 扩展模块。
  • 与 distutils 和 Cython 集成，方便构建复杂项目。

• 依赖管理：

  • 定义项目的运行时依赖（install_requires）。
  • 支持可选依赖（extras_require）。

• 开发模式：

  • 支持以开发模式安装项目（python setup.py develop 或 pip install -e .），允许在开发过程中直接修改代码而无需重新安装。

• 插件系统：

  • 提供丰富的插件支持，例如 pytest-runner 用于集成测试。

---

2. setuptools 的核心组件

• setup.py：

  • 项目的构建脚本，通常包含一个 setup() 函数，用于定义项目的元数据和构建配置。
  • 示例：

    from setuptools import setup
    
    setup(
        name="my_package",
        version="0.1",
        packages=["my_package"],
        install_requires=["numpy", "requests"],
    )
    

• setup.cfg：

  • 一个配置文件，用于定义项目的元数据和构建配置。与 setup.py 相比，setup.cfg 更静态且易于解析。
  • 示例：

    [metadata]
    name = my_package
    version = 0.1
    
    [options]
    packages = find:
    install_requires =
        numpy
        requests
    

• pyproject.toml：

  • 一个现代配置文件，用于定义构建系统和项目元数据。它是 PEP 517 和 PEP 518 的标准配置文件。
  • 示例：

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

---

3. setuptools 与 distutils 的关系

• distutils 是 Python 标准库中的一个模块，用于构建和分发 Python 包。它是 setuptools 的前身。
• setuptools 是对 distutils 的增强和扩展，提供了更多功能（如依赖管理、插件系统等）。
• 目前，distutils 已被弃用，推荐使用 setuptools。

---

4. setuptools 的安装

setuptools 通常随 Python 一起安装。如果没有安装，可以通过以下命令安装：

pip install setuptools

---

5. setuptools 的常见用法

(1) 定义项目元数据

在 setup.py 中定义项目的基本信息：

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1",
    author="John Doe",
    description="A sample Python package",
    packages=find_packages(),
    install_requires=["numpy", "requests"],
)

(2) 构建和安装项目

• 构建项目：

  python setup.py build
  

• 安装项目：

  python setup.py install
  

• 以开发模式安装：

  python setup.py develop
  

(3) 使用 pyproject.toml

在 pyproject.toml 中定义构建系统：

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

然后使用 pip 安装：

pip install .

---

6. setuptools 的局限性

• 复杂性：setuptools 的功能非常强大，但配置相对复杂，尤其是对于初学者。
• 弃用警告：随着 Python 打包生态的发展，setuptools 的某些功能（如 easy_install 和 setup.py install）已被弃用，推荐使用 pip 和 pyproject.toml。
• 性能问题：对于大型项目，setuptools 的包发现和构建过程可能较慢。

---

7. 现代替代方案

随着 Python 打包生态的发展，出现了许多替代工具，例如：

• poetry：一个现代化的依赖管理和打包工具。
• flit：专注于简单项目的打包工具。
• hatch：一个功能丰富的项目管理工具。

尽管有这些替代工具，setuptools 仍然是 Python 生态中最广泛使用的工具之一，尤其是在需要支持复杂构建过程（如 C/C++ 扩展）的项目中。

---

总结

setuptools 是 Python 打包和分发的核心工具，提供了丰富的功能来管理项目的元数据、依赖和构建过程。尽管它有一些局限性，但在大多数情况下，它仍然是构建和分发 Python 项目的首选工具。随着 pyproject.toml 的普及，setuptools 也在不断演进，以更好地适应现代 Python 打包生态。