Helpers for versioning software

PEP-386 compliant versioning

PEP 386 defines a standard format for version strings. This module contains a function for creating strings in that format.

kitchen.versioning.version_tuple_to_string(version_info)

Return a PEP 386 version string from a PEP 386 style version tuple

Parameters

version_info – Nested set of tuples that describes the version. See below for an example.

Returns

a version string

This function implements just enough of PEP 386 to satisfy our needs. PEP 386 defines a standard format for version strings and refers to a function that will be merged into the python standard library that transforms a tuple of version information into a standard version string. This function is an implementation of that function. Once that function becomes available in the python standard library we will start using it and deprecate this function.

version_info takes the form that PEP 386’s NormalizedVersion.from_parts() uses:

((Major, Minor, [Micros]), [(Alpha/Beta/rc marker, version)],
    [(post/dev marker, version)])

Ex: ((1, 0, 0), ('a', 2), ('dev', 3456))

It generates a PEP 386 compliant version string:

N.N[.N]+[{a|b|c|rc}N[.N]+][.postN][.devN]

Ex: 1.0.0a2.dev3456

Warning

This function does next to no error checking. It’s up to the person defining the version tuple to make sure that the values make sense. If the PEP 386 compliant version parser doesn’t get released soon we’ll look at making this function check that the version tuple makes sense before transforming it into a string.

It’s recommended that you use this function to keep a __version_info__ tuple and __version__ string in your modules. Why do we need both a tuple and a string? The string is often useful for putting into human readable locations like release announcements, version strings in tarballs, etc. Meanwhile the tuple is very easy for a computer to compare. For example, kitchen sets up its version information like this:

from kitchen.versioning import version_tuple_to_string
__version_info__ = ((0, 2, 1),)
__version__ = version_tuple_to_string(__version_info__)

Other programs that depend on a kitchen version between 0.2.1 and 0.3.0 can find whether the present version is okay with code like this:

from kitchen import __version_info__, __version__
if __version_info__ < ((0, 2, 1),) or __version_info__ >= ((0, 3, 0),):
    print 'kitchen is present but not at the right version.'
    print 'We need at least version 0.2.1 and less than 0.3.0'
    print 'Currently found: kitchen-%s' % __version__