Version

Note

The documentation in this section is aimed at people wishing to contribute to versionah, and can be skipped if you are simply using the tool from the command line.

versionah.VALID_PACKAGE = '[A-Za-z][A-Za-z0-9]+(?:[_\\.-][A-Za-z0-9]+)*'

Regular expression to match a valid package name

versionah.VALID_VERSION = '\\d+\\.\\d+(?:\\.\\d+){,2}'

Regular expression to match a valid package version

versionah.VALID_DATE = '(?:\\d{4}-\\d{2}-\\d{2}|\\d{2}-(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-\\d{4})'

Regular expression to match a package date. ISO-8601, and %d-%b-%Y formatting for shtool compatibility

versionah.VERSION_COMPS = ('major', 'minor', 'micro', 'patch')

Supported version components

class versionah.Version(components=(0, 1, 0), name='unknown', date=datetime.today())

Initialise a new Version object.

Parameters:

• components (int or tuple of int) – Version components
• name (str) – Package name
• date (datetime.date) – Date associated with version

as_date()

Generate a ISO-8601 date string for release.

Return type:str Returns:Version’s release date as ISO-8601 date stamp

as_dict()

Generate a dictionary of version components.

Return type:dict Returns:Version as dictionary

as_dotted()

Generate a dotted version string.

Return type:str Returns:Standard dotted version string

as_hex()

Generate a hex version string.

Return type:str Returns:Version as hex string

as_libtool()

Generate a libtool version string.

Return type:str Returns:Version as libtool string

as_tuple()

Generate a tuple of version components.

Return type:int Returns:Version components as tuple

as_web()

Generate a web UA-style string for release.

Return type:str Returns:Version’s string in web UA-style

bump(bump_type)

Bump a version string.

Parameters:bump_type (str) – Component to bump

bump_major()

Bump major version component.

bump_micro()

Bump micro version component.

bump_minor()

Bump minor version component.

bump_patch()

Bump patch version component.

components

Generate component tuple to initial resolution.

Return type:tuple of int

components_full

Generate full length component tuple for version.

Return type:tuple of int

display(display_format)

Display a version string.

Parameters:display_format (str) – Format to display version string in Return type:str Returns:Formatted version string

static display_types()

Supported representation types.

Return type:list of str Returns:Method names for representation types

static read(filename)

Read a version file.

Parameters:

filename (str) – Version file to read

Return type:

Version

Returns:

New Version object representing file

Raises:

• exceptions.OSError – When filename doesn’t exist
• exceptions.ValueError – Unparsable version data

set(components)

Set version components.

Parameters:components (tuple of int) – Version components

write(filename, file_type, shtool=False)

Write a version file.

Parameters:

• filename (str) – Version file to write
• file_type (str) – File type to write
• shtool (bool) – Write shtool compatible files

Return type:

bool

Returns:

True on write success

Examples

Reading version data from a file

>>> Version.read('tests/data/test_a')
Version((0, 1, 0), 'test', datetime.date(2011, 2, 19))
>>> Version.read('tests/data/test_b')
Version((1, 0, 0), 'test', datetime.date(2011, 2, 19))
>>> Version.read('tests/data/test_c')
Version((2, 1, 3), 'test', datetime.date(2011, 2, 19))

Writing version date to a file

>>> v = Version((0, 1, 0), 'test', datetime.date(2011, 2, 19))
>>> v.write('test_data.python', 'py')  
>>> v.write('test_data.hh', 'h')  
>>> v.write('test_data.m4', 'm4')  

Bumping a version component

>>> v = Version((0, 1, 0), 'test', datetime.date(2011, 2, 19))
>>> v.bump('minor')
>>> v.components
(0, 2, 0)
>>> v.bump('major')
>>> v.components
(1, 0, 0)
>>> v.bump_major()
>>> v.components
(2, 0, 0)