README.rst

katversion

The katversion package provides proper versioning for Python packages as dictated by their (git) source repositories. The resulting version string is baked into the installed package's __init__.py file for guaranteed traceability when imported (no dependency on what pkg_resources thinks!).

Version String Format

katversion generates a version string for your SCM package that complies with PEP 440. It only supports git repositories.

The format of our version string is:

- 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'

Typical Usage

Add this to setup.py (handles installed packages):

from setuptools import setup

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

Add this to mypackage/__init__.py, including the comment lines (handles local packages):

# 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

In addition, a command-line script for checking the version:

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