Skip to main content

Reliable git-based versioning for Python packages

Project description

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 mainly supports git repositories, with a half-hearted attempt at svn support.

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.svn.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(
    ...,
    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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
katversion-0.9-py2.py3-none-any.whl (13.5 kB) Copy SHA256 hash SHA256 Wheel py2.py3
katversion-0.9.tar.gz (10.6 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page