Metadata-Version: 2.0
Name: katversion
Version: 0.9
Summary: Reliable git-based versioning for Python packages
Home-page: https://github.com/ska-sa/katversion
Author: The MeerKAT CAM Team
Author-email: cam@ska.ac.za
License: BSD
Keywords: versioning meerkat ska
Platform: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Software Development :: Libraries :: Python Modules

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 <https://www.python.org/dev/peps/pep-0440/>`_.
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):

.. code:: python

        from setuptools import setup

        setup(
            ...,
            setup_requires=['katversion'],
            use_katversion=True,
            ...
        )

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

.. code:: python

        # 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


