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__