setuptools_scm 使用教程

setuptools_scm 使用教程

setuptools_scmthe blessed package to manage your versions by scm tags项目地址:https://gitcode.com/gh_mirrors/se/setuptools_scm

1、项目介绍

setuptools_scm 是一个用于自动管理 Python 包版本的工具。它通过读取版本控制系统（如 Git 或 Mercurial）中的元数据来动态生成版本号，而不是在代码中硬编码版本号。这使得版本管理更加灵活和自动化，特别适合在持续集成和持续交付（CI/CD）环境中使用。

setuptools_scm 的主要功能包括：

• 自动从版本控制系统中提取版本号。
• 自动将版本控制系统管理的文件添加到源代码包中。
• 支持通过配置文件（如 pyproject.toml）进行自定义配置。

2、项目快速启动

安装

首先，使用 pip 安装 setuptools_scm：

pip install setuptools_scm

配置

在项目的 pyproject.toml 文件中添加以下配置：

[build-system]
requires = ["setuptools>=64", "setuptools_scm>=8"]
build-backend = "setuptools.build_meta"

[project]
# 动态设置版本号
dynamic = ["version"]

[tool.setuptools_scm]
# 可选配置，例如版本格式
version_scheme = "guess-next-dev"

使用

在 setup.py 文件中启用 setuptools_scm：

from setuptools import setup

setup(
    use_scm_version=True,
)

示例代码

假设你有一个简单的 Python 项目，目录结构如下：

my_project/
├── my_module.py
├── setup.py
└── pyproject.toml

在 setup.py 中添加以下内容：

from setuptools import setup, find_packages

setup(
    name="my_project",
    packages=find_packages(),
    use_scm_version=True,
    setup_requires=['setuptools_scm'],
)

在 pyproject.toml 中添加以下内容：

[build-system]
requires = ["setuptools>=64", "setuptools_scm>=8"]
build-backend = "setuptools.build_meta"

[project]
dynamic = ["version"]

[tool.setuptools_scm]
version_scheme = "guess-next-dev"

3、应用案例和最佳实践

应用案例

setuptools_scm 广泛应用于需要频繁发布版本的 Python 项目中，特别是在开源社区中。例如，许多流行的 Python 库（如 requests、pip 等）都使用 setuptools_scm 来管理版本号。

最佳实践

1. 版本号管理：使用 setuptools_scm 自动生成版本号，避免手动修改版本号带来的错误。
2. 配置文件：在 pyproject.toml 中配置 setuptools_scm，确保项目符合现代 Python 项目的最佳实践。
3. 持续集成：在 CI/CD 环境中使用 setuptools_scm，确保每次构建的版本号都是最新的。

4、典型生态项目

setuptools_scm 是 Python 生态系统中的一部分，与以下项目紧密相关：

• setuptools：setuptools_scm 依赖于 setuptools 来完成包的构建和发布。
• pip：pip 是 Python 的包管理工具，支持通过 setuptools_scm 自动生成版本号。
• tox：tox 是一个用于自动化测试的工具，可以与 setuptools_scm 结合使用，确保测试环境的一致性。

通过这些工具的结合使用，可以大大提高 Python 项目的开发效率和版本管理能力。

setuptools_scmthe blessed package to manage your versions by scm tags项目地址:https://gitcode.com/gh_mirrors/se/setuptools_scm