Code reference

Version class

class versiontools.Version

Version class suitable to be used in module’s __version__

Version class is a tuple and has the same logical components as sys.version_info.

static __new__(major, minor, micro=0, releaselevel='final', serial=0)

Construct a new version tuple.

There is some extra logic when initializing tuple elements. All variables except for releaselevel are silently converted to integers That is:

>>> Version("1.2.3.dev".split("."))
(1, 2, 3, "dev", 0)

Parameters:

• major (int or str) – Major version number
• minor (int or str) – Minor version number
• micro (int or str) – Micro version number, defaults to 0.
• releaselevel (str) –

  Release level name.

  There is a constraint on allowed values of releaselevel. Only the following values are permitted:

  • ‘dev’
  • ‘alpha’
  • ‘beta’
  • ‘candidate’
  • ‘final’
• serial – Serial number, usually zero, only used for alpha, beta and candidate versions where it must be greater than zero.

Raises ValueError:  

If releaselevel is incorrect, a version component is negative or serial is 0 and releaselevel is alpha, beta or candidate.

major

Major version number

minor

Minor version number

micro

Micro version number

releaselevel

Release level string

serial

Serial number

classmethod from_tuple(version_tuple)

Create version from 5-element tuple

Note

This method is identical to the constructor, just spelled in a way that is more obvious to use.

New in version 1.1.

classmethod from_tuple_and_hint(version_tuple, hint)

Create version from a 5-element tuple and VCS location hint.

Similar to from_tuple() but uses the hint object to locate the source tree if needed. A good candidate for hint object is the module that contains the version_tuple. In general anything that works with inspect.getsourcefile() is good.

New in version 1.4.

vcs

Return VCS integration object, if any.

Accessing this attribute for the first time will query VCS lookup (may be slower, will trigger imports of various VCS plugins).

The returned object, if not None, should have at least revno property. For details see your particular version control integration plugin.

Note

This attribute is not an element of the version tuple and thus does not break sorting.

New in version 1.0.4.

__str__()

Return a string representation of the version tuple.

The string is not a direct concatenation of all version components. Instead it’s a more natural ‘human friendly’ version where components with certain values are left out.

The following table shows how a version tuple gets converted to a version string.

__version__	Formatter version
(1, 2, 0, "final", 0)	"1.2"
(1, 2, 3, "final", 0)	"1.2.3"
(1, 3, 0, "alpha", 1)	"1.3a1"
(1, 3, 0, "beta", 1)	"1.3b1"
(1, 3, 0, "candidate", 1)	"1.3c1"
(1, 3, 0, "dev", 0)	"1.3.dev"

Now when release level is set to "dev" then interesting things start to happen. When possible, version control system is queried for revision or changeset identifier. This information gets used to create a more useful version string. The suffix gets appended to the base version string. So for example a full version string, when using Bazaar might look like this: "1.3.dev54" which indicates that the tree was at revision 54 at that time.

The following table describes what gets appended by each version control system.

VCS	Formatted version suffix
Bazaar	Revision number (revno), e.g. 54
Git	Head commit ID (sha1), e.g. "e40105c58a162de822b63d28b63f768a9763fbe3"
Mercurial	Tip revision number, e.g. 54

Note

This logic is implemented in versiontools.Version.__str__() and can be overridden by sub-classes. You can use project-specific logic if required. To do that replace __version__ with an instance of your sub-class.

Utility functions

Instead of using Version class directly you may want to use the simplified interface where you simply interpret an arbitrary five-element version tuple as a version to get the pretty and PEP 386-compliant version string. In that case you may be interested in this function:

versiontools.format_version(version, hint=None)

Pretty formatting for 5-element version tuple.

Parameters:

• version (A tuple with five elements, as the one provided to versiontools.Version.from_tuple(), or an existing instance of versiontools.Version.) – The version to format
• hint (either None, or a module.) – The hint object, if provided, helps versiontools to locate the directory which might host the project’s source code. The idea is to pass module.__version__ as the first argument and module as the hint. This way we can loookup where module came from, and look for version control system data in that directory. Technicallally passing hint will make us call from_tuple_and_hint() instead of from_tuple().

New in version 1.1.

Integration with setuptools

Setuptools has a framework where external packages, such as versiontools, can hook into setup.py metadata and commands. We use this feature to intercept special values of the version keyword argument to setup(). This argument handled by the following method:

versiontools.handle_version(dist, attr, value)

Handle version keyword as used by setuptools.

Note

This function is normally called by setuptools, it is advertised in the entry points of versiontools as setuptools extension. There is no need to call in manually.

New in version 1.3.

Integration with version control systems

The following version control integration plugins are bundled with versiontools. Additional plugins may be provided by third party modules but they are not documented here.

Bazaar

class versiontools.bzr_support.BzrIntegration(branch)

Bazaar integration for versiontools

classmethod from_source_tree(source_tree)

Initialize BzrIntegration by pointing at the source tree. Any file or directory inside the source tree may be used.

revno

Revision number of the branch

branch_nick

Nickname of the branch

New in version 1.0.4.

Git

class versiontools.git_support.GitIntegration(repo)

Git integration for versiontools

classmethod from_source_tree(source_tree)

Initialize GitIntegration by pointing at the source tree. Any file or directory inside the source tree may be used.

revno

Revision number of the branch

branch_nick

Nickname of the branch

New in version 1.0.4.

Hg (Mercurial)

class versiontools.hg_support.HgIntegration(repo)

Hg integration for versiontools

classmethod from_source_tree(source_tree)

Initialize HgIntegration by pointing at the source tree. Any file or directory inside the source tree may be used.

revno

Revision number of the branch

branch_nick

Nickname of the branch

New in version 1.0.4.