Version Utility

xobox.utils.version.get_version(*args, **kwargs)

Derives a PEP 440 compliant version number from VERSION, assuming VERSION is a quintuple consisting of these elements:

(major, minor, patch, stage, suffix)

major, minor, patch and suffix are integer values, whereas stage is a string, containing one of these key words:

• final means this version is a release. In this case, suffix will be ignored.
• candidate means this version is a release candidate. In this case, suffix must be greater than zero and indicate the ordinal numbering of the release candidate.
• beta means this version is a beta release. In this case, suffix must be greater than zero and indicate the ordinal numbering of the beta release.
• alpha means this version is either an alpha release, or a development version. For the first case, suffix must be greater than zero and indicate the ordinal numbering of the alpha release. For the latter case, suffix must be set to zero.

The version quintuple may be passed as (only) positional argument, or as value of the version keyword argument. If no version quintuple is provided by argument, xobox.VERSION is used instead.

Note

The keyword argument overrides any positional argument. If two version quintuples are passed, one by positional and one by keyword argument, the one passed by keyword argument will win.

Parameters:

• args – positional arguments, of which only the first one (if present) will be taken as version quintuple
• kwargs – keyword arguments, of which only the value of version (if present) will be taken as version quintuple

Returns:

PEP 440 compliant version string

xobox.utils.version.get_development_status(*args, **kwargs)

Derive the development status compliant to PEP 301 Trove Classifiers from VERSION, assuming VERSION is a quintuple consisting of these elements:

(major, minor, patch, stage, suffix)

major, minor, patch and suffix are integer values, whereas stage is a string, containing one of these key words:

• final means this version is a release. In this case, suffix will be ignored.
• candidate means this version is a release candidate. In this case, suffix must be greater than zero and indicate the ordinal numbering of the release candidate.
• beta means this version is a beta release. In this case, suffix must be greater than zero and indicate the ordinal numbering of the beta release.
• alpha means this version is either an alpha release, or a development version. For the first case, suffix must be greater than zero and indicate the ordinal numbering of the alpha release. For the latter case, suffix must be set to zero.

The version quintuple may be passed as (only) positional argument, or as value of the version keyword argument. If no version quintuple is provided by argument, xobox.VERSION is used instead.

Note

The keyword argument overrides any positional argument. If two version quintuples are passed, one by positional and one by keyword argument, the one passed by keyword argument will win.

Parameters:

• args – positional arguments, of which only the first one (if present) will be taken as version quintuple
• kwargs – keyword arguments, of which only the value of version (if present) will be taken as version quintuple

Returns:

Trove classifier string

xobox.utils.version.get_git_changeset(path=None)

Returns a numeric identifier of the latest Git changeset.

Since the Git revision hash does not fulfil the requirements of PEP 440, the UTC timestamp in YYYYMMDDHHMMSS format is used instead. This value is not guaranteed to be unique, however the likeliness of collisions is small enough to be acceptable for the purpose of building version numbers.

Parameters:path (str) – Path to the Git repository to detect the latest commit timestamp from. If not indicated, the parent path of the xobox package is used. Returns:a string of the format GIT-timestamp with timestamp being either a 14 digit integer, or the string “unknown” in cases where the changeset timestamp could not be detected.