katversion 1.2

版本字符串格式

katversion 为您的SCM软件包生成符合 PEP 440 规范的版本字符串。它仅支持git仓库。

我们版本字符串的格式是

- for RELEASE builds:
    <major>.<minor>
    e.g.
    0.1
    2.4

- for DEVELOPMENT builds:
    <major>.<minor>.dev<num_commits>+<branch_name>.g<short_git_sha>[.dirty]
    e.g.
    0.2.dev34+new.shiny.feature.gfa973da
    2.5.dev7+master.gb91ffa6.dirty

- for UNKNOWN builds:
    0.0+unknown.[<scm_type>.]<timestamp>
    e.g.
    0.0+unknown.git.201402031023
    0.0+unknown.201602081715

where <major>.<minor> is derived from the latest version tag and
<num_commits> is the total number of commits on the development branch.

The <major>.<minor> substring for development builds will be that of the
NEXT (minor) release, in order to allow proper Python version ordering.

To add a version tag use the `git tag` command, e.g.

    $ git tag -a 1.2 -m 'Release version 1.2'

典型用法

将其添加到 setup.py 中（处理已安装的包）

from setuptools import setup

setup(
    ...,
    # version=1.0,  # remove the version parameter as it will be overridden
    setup_requires=['katversion'],
    use_katversion=True,
    ...
)

将其添加到 mypackage/__init__.py 中，包括注释行（处理本地包）

# BEGIN VERSION CHECK
# Get package version when locally imported from repo or via -e develop install
try:
    import katversion as _katversion
except ImportError:  # pragma: no cover
    import time as _time
    __version__ = "0.0+unknown.{}".format(_time.strftime('%Y%m%d%H%M'))
else:  # pragma: no cover
    __version__ = _katversion.get_version(__path__[0])
# END VERSION CHECK

此外，还有一个用于检查版本的命令行脚本

# From inside your SCM subdirectory, run the following command
# which will print the result to stdout:
$ kat-get-version.py