Version Tools Documentation

See also

To get started quickly see Usage instructions

See also

See what’s new in Version 1.9.1


This document may be out of date, the bleeding edge version is always available at


This package is being actively maintained and published in the Python Package Index. You can install it if you have pip tool using just one line:

$ pip install versiontools


  • A piece of code that allows you to keep a single version definition inside your package or module. No more hacks in, no more duplicates in and somewhere else. Just one version per package.
  • Version objects can produce nice version strings for released files that are compliant with PEP 386. Releases, alphas, betas, development snaphots. All of those get good version strings out of the box.
  • Version objects understand the VCS used by your project. Git, Mercurial and Bazaar are supported out of the box. Custom systems can be added by 3rd party plugins.
  • Version object that compares as a tuple of values and sorts properly.
  • Zero-dependency install! If all you care about is handling setup() to get nice tarball names then you don’t need to depend on versiontools (no setup_requires, no install_requires!). You will need to bundle a small support module though.

__version__ to string conversion

This is pulled from the documentation of the string method on the Version class. In general you don’t need to explicitly use that class to benefit from this system. To learn more check the Usage instructions section.


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) ""

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 Short commit ID of the current branch e.g. "763fbe3"
Mercurial Tip revision number, e.g. 54


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.

Read the Docs v: release-1.9.1
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.