setuptools-scm 使用教程

setuptools-scm 使用教程

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

1. 项目介绍

setuptools-scm 是一个用于管理 Python 包版本的工具，它通过从 Git 或 Mercurial 的元数据中提取版本信息，而不是在代码中硬编码版本号。这使得版本管理更加自动化和灵活。setuptools-scm 还提供了自动将 SCM（源代码管理）管理的文件添加到源代码分发包（sdist）中的功能，减少了手动维护 MANIFEST.in 文件的需求。

2. 项目快速启动

安装

首先，确保你已经安装了 setuptools-scm。你可以通过 pip 来安装：

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]

使用

在项目的 setup.py 文件中，确保你已经移除了硬编码的版本号，并使用 setuptools-scm 来动态获取版本号：

from setuptools import setup

setup(
    use_scm_version=True,
    setup_requires=['setuptools_scm'],
)

验证

你可以通过以下命令来验证版本号是否正确生成：

python -m setuptools_scm

3. 应用案例和最佳实践

案例1：自动化版本管理

在持续集成（CI）环境中，使用 setuptools-scm 可以自动生成版本号，避免手动更新版本号的繁琐工作。例如，在每次代码提交时，CI 系统可以自动生成新的版本号并发布到 PyPI。

案例2：多版本管理

在多分支开发环境中，setuptools-scm 可以根据不同的分支自动生成不同的版本号，方便开发者区分不同分支的版本。

最佳实践

• 动态版本号：始终使用 setuptools-scm 动态生成版本号，避免在代码中硬编码版本号。
• 配置文件：使用 pyproject.toml 文件来配置 setuptools-scm，确保配置的一致性和可维护性。
• CI/CD 集成：在 CI/CD 流程中集成 setuptools-scm，自动生成和发布版本号。

4. 典型生态项目

1. pip

pip 是 Python 的包管理工具，广泛用于安装和管理 Python 包。setuptools-scm 可以与 pip 无缝集成，自动管理包的版本号。

2. hatch

hatch 是一个现代化的 Python 项目管理工具，支持 setuptools-scm 来管理版本号。通过 hatch，你可以更方便地管理项目的依赖和版本。

3. tox

tox 是一个用于自动化测试的工具，支持 setuptools-scm 来动态生成测试环境的版本号，确保测试环境的版本一致性。

通过这些生态项目的集成，setuptools-scm 可以更好地服务于 Python 项目的开发和维护。

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