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

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-1.2.tar.gz (12.0 kB view details)

Uploaded Source

Built Distribution

katversion-1.2-py2.py3-none-any.whl (13.2 kB view details)

Uploaded Python 2 Python 3

File details

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

File metadata

  • Download URL: katversion-1.2.tar.gz
  • Upload date:
  • Size: 12.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.1 pkginfo/1.5.0.1 requests/2.24.0 requests-toolbelt/0.9.1 tqdm/4.48.0 CPython/3.8.10

File hashes

Hashes for katversion-1.2.tar.gz
Algorithm Hash digest
SHA256 87c5d49a9a448fdef4de8ab03b8ae83552d2f7577d8d7402ec2a0a7edd6964a2
MD5 1c7002584eed35108c0a04c6124f4962
BLAKE2b-256 8aca0b7afb0ec27ac1e554fff9fa3fa9ce584b1a7df3f8001a07dcc247973f53

See more details on using hashes here.

File details

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

File metadata

  • Download URL: katversion-1.2-py2.py3-none-any.whl
  • Upload date:
  • Size: 13.2 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/3.10.1 pkginfo/1.5.0.1 requests/2.24.0 requests-toolbelt/0.9.1 tqdm/4.48.0 CPython/3.8.10

File hashes

Hashes for katversion-1.2-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 67787c4bc8996415cd0d79d6d56e04b25fe678048763ee1d98494d4064c10469
MD5 81a18202d464ce814195280e3747a1ac
BLAKE2b-256 c2a8e0dffadc4f735363595bef94f5dda46ba3e9a8961c6c4cb0c63df5aec2e3

See more details on using hashes here.

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