Command line¶

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.

class versionah.cmdline.NameParamType[source]¶

Name parameter handler.

Initialise a new ReMatchParamType object.

class versionah.cmdline.ReMatchParamType[source]¶

Regular expression based parameter matcher.

Initialise a new ReMatchParamType object.

convert(value, param, ctx)[source]¶

Check given name is valid.

Parameters

value (str) – Value given to flag
param (click.Argument) – Parameter being processed
ctx (click.Context) – Current command context

Returns

Valid value

Return type

str

class versionah.cmdline.VersionParamType[source]¶

Version parameter handler.

Initialise a new ReMatchParamType object.

class versionah.cmdline.CliVersion(components=(0, 1, 0), name='unknown', date=datetime.date(2019, 11, 7))[source]¶

Specialisation of models.Version for command line usage.

Initialise a new Version object.

Parameters

components (str) – Version components
name (str) – Package name
date (datetime.date) – Date associated with version

display(display_format)[source]¶

Display a version string.

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

static display_types()[source]¶

Supported representation types.

Returns: Method names for representation types
Return type: list[str]

static read(filename)[source]¶

Read a version file.

Parameters

filename (str) – Version file to read

Returns

New CliVersion object representing file

Return type

CliVersion

Raises

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

write(filename, file_type, *, shtool=False)[source]¶

Write a version file.

Parameters

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

versionah.cmdline.guess_type(filename)[source]¶

Guess output type from filename.

Parameters: filename (str) – File to operate on

versionah.cmdline.cli(*args, **kwargs)¶: Main command entry point.

versionah.cmdline.bump(*args, **kwargs)¶

Bump version in existing file.

Parameters

display_format (str) – Format to display output in
filename (tuple[str]) – File to operate on
file_type (tuple[str]) – File type to produce
shtool (bool) – Write shtool compatible files
bump (str) – Component to bump

versionah.cmdline.display(*args, **kwargs)¶

Display version in given file.

Parameters

display_format (str) – Format to display output in
filename (tuple[str]) – File to operate on

versionah.cmdline.set_version(*args, **kwargs)¶

Set version in given file.

Parameters

display_format (str) – Format to display output in
filename (tuple[str]) – File to operate on
file_type (tuple[str]) – File type to produce
shtool (bool) – Write shtool compatible files
name (str) – Project name used in output
version_str (str) – Initial version string

Examples¶

Reading version data from a file¶

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

Writing version date to a file¶

>>> v = CliVersion((0, 1, 0), 'test', datetime.date(2011, 2, 19))
>>> v.write('test_data.python', 'py')  # doctest: +SKIP
>>> v.write('test_data.hh', 'h')  # doctest: +SKIP
>>> v.write('test_data.m4', 'm4')  # doctest: +SKIP

Guess file type from name¶

>>> guess_type('main.c')
'c'
>>> guess_type('version.py')
'py'
>>> guess_type('no_suffix')
'text'
>>> guess_type('suffix.unknown')
'text'