Define single and useful __version__ of a project.
See also
To get started quickly see Usage
See also
See what’s new in Version 1.8.2
Note
This document may be out of date, the bleeding edge version is always available at http://versiontools.rtfd.org/
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 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) | "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.