setuptools_sky 0.1.7

Setup.py 用法

要使用 setuptools_sky 只需像这样修改项目的 setup.py 文件：

1. 添加'setuptools_sky'到setup_requires参数

2. 添加use_scm_version参数并将其设置为True

   例如：

   from setuptools import setup
   setup(
       ...,
       use_scm_version=True,
       setup_requires=['setuptools_sky'],
       ...,
   )

   get_version()的参数（见下文）可以作为字典传递给use_scm_version。例如：

   from setuptools import setup
   setup(
       ...,
       use_scm_version = {"root": "..", "relative_to": __file__},
       setup_requires=['setuptools_sky'],
       ...,
   )

3. 通过以下方式访问包中的版本号pkg_resources

   例如（PEP-0396）：

   from pkg_resources import get_distribution, DistributionNotFound
   try:
       __version__ = get_distribution(__name__).version
   except DistributionNotFound:
       # package is not installed
       pass

程序化使用

为了从比项目根目录更深的代码中使用setuptools_sky ，您可以使用：

from setuptools_sky import get_version
version = get_version(root='..', relative_to=__file__)

有关如何在 setup.py 中使用它，请参阅上面的setup.py 用法。

狮身人面像的用法

不鼓励使用 sphinx 本身的 setuptools_sky ，而是在可编辑/实际安装后使用pkg_resources ：

from pkg_resources import get_distribution
release = get_distribution('myproject').version
# for example take major/minor
version = '.'.join(release.split('.')[:2])

根本原因是，像 readthedocs 这样的服务有时会出于充分的理由更改工作目录，并且使用已安装的元数据可以防止在那里使用不必要的易失性数据。

值得注意的插件

setuptools_sky_git_archive为从属于 标记版本的 git 档案中获取版本提供了部分支持。不将其包含在 setuptools-scm 本身的唯一原因是 git/github 不支持足够的元数据用于未标记/后续提交，这会妨碍用户体验的一致性。

默认版本控制方案

在标准配置中 setuptools_sky 看看 3 件事：

1. 最新标签（带有版本号）

2. 到此标签的距离（例如，自最新标签以来的修订数）

3. workdir 状态（例如，自最新标签以来未提交的更改）

并大致使用以下逻辑来呈现版本：

no distance and clean：

{tag}

distance and clean：

{next_version}.dev{distance}+{scm letter}{revision hash}

no distance and not clean：

{tag}+dYYYMMMDD

distance and not clean：

{next_version}.dev{distance}+{scm letter}{revision hash}.dYYYMMMDD

下一个版本是通过将标签的最后一个数字分量加1来计算的。

对于 git 项目，该版本依赖于git describe ，因此您会看到{revision hash}前面附加了一个g。

用于获取版本号的内置机制

1. scm 本身 (git/hg)

2. .hg_archival文件（水银档案）

3. PKG-信息

配置参数

为了配置use_scm_version的工作方式，您可以提供带有选项的映射，而不是简单的布尔值。

当前支持的配置键是：

根：

cwd 用于查找 scm 根的相对路径，默认为.

版本方案：

配置本地版本号的构造方式。入口点名称或可调用对象

本地方案：

配置版本的本地组件如何构造入口点名称或可调用对象

写到：

声明一个文本文件或 python 文件，它被包含当前版本的文件替换。它的理想或在包中创建一个 version.py 文件

write_to_template ：

一个新式格式字符串，它以当前版本作为version格式化的关键字参数

相对：

可以从中解析根目录的文件。通常由不在存储库根目录中的脚本或模块调用，以通过提供__file__将 setuptools_sky 定向到存储库根目录。

解析：

一个将用于代替发现的 scm 来解析版本的函数，请谨慎使用，这是一个专家函数，您应该非常熟悉 setuptools_sky 内部结构才能使用它

要在其他 Python 代码中使用 setuptools_sky，您可以使用 get_version函数：

from setuptools_sky import get_version
my_version = get_version()

它可以选择接受use_scm_version参数的键作为关键字参数。

环境变量

setuptools_sky_PRETEND_VERSION ：

当定义并且不为空时，它用作版本号的主要来源，在这种情况下它将是一个未解析的字符串

扩展 setuptools_sky

setuptools_sky 附带了一些基于 setuptools 入口点的钩子来扩展其默认功能。

def myversion():
    from setuptools_sky.version import dirty_tag
    def clean_scheme(version):
        return dirty_tag(version) if version.dirty else '+clean'

    return {'local_scheme': clean_scheme}

行为守则

在 setuptools_sky 项目的代码库、问题跟踪器、聊天室和邮件列表中进行交互的每个人都应遵守 PyPA 行为准则。