Metadata-Version: 1.2
Name: katversion
Version: 1.0
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
Description: 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 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):
        
        .. code:: python
        
                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):
        
        .. 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
        
Keywords: versioning meerkat ska
Platform: OS Independent
Classifier: Development Status :: 5 - Production/Stable
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: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=2.6, !=3.0.*, !=3.1.*, !=3.2.*, <4
