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

Project details


Download files

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

Source Distribution

katversion-0.9.tar.gz (10.6 kB view details)

Uploaded Source

Built Distribution

katversion-0.9-py2.py3-none-any.whl (13.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file katversion-0.9.tar.gz.

File metadata

  • Download URL: katversion-0.9.tar.gz
  • Upload date:
  • Size: 10.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for katversion-0.9.tar.gz
Algorithm Hash digest
SHA256 7b8fed38556d3d9c17a719ad1ccfdd266e914dfc39a74acec9cc62981d6d02cc
MD5 8d59685e6a3674c77e959d022a24aad4
BLAKE2b-256 d579e1c95c61311c25e3a3a35cef0aed6b6b154113818b8ae81bfc458b19eacd

See more details on using hashes here.

Provenance

File details

Details for the file katversion-0.9-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for katversion-0.9-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 23fdc676a1f34e38bb64a0d5c6c285173f68966c977fa5b3390c02d8c2ff2117
MD5 57bb8fd4c8f992c743b0045e23f2d8a7
BLAKE2b-256 25ca8522a5b9dbff71554364fea50f4b495b10305297278f5d8cf83f3d77c605

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page