Code reference¶

versiontools¶

Define single and useful __version__ of a project.

class versiontools.Version¶

Smart version class.

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

In addition to the tuple elements there is a special vcs attribute that has all of the data exported by the version control system.

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.

classmethod from_expression(pkg_expression)¶

Create a version from a python module name.

The argument must describe a module to import. The module must declare a variable that holds the actual version. The version cannot be a plain string and instead must be a tuple of five elements as described by the Version class.

The variable that holds the version should be called __version__. If it is called something else the actual name has to be specified explicitly in pkg_expression by appending a colon (:) and the name of the variable (for example package:version).

New in version 1.9.

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

versiontools.format_version(version, hint=None)¶

Pretty formatting for 5-element version tuple.

Instead of using Version class directly you may want to use this 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.

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 lookup where module came from, and look for version control system data in that directory. Technically passing hint will make us call from_tuple_and_hint() instead of from_tuple().

New in version 1.1.

versiontools.setuptools_hooks¶

Plugins for setuptools that add versintools features.

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.setuptools_hooks.version(dist, attr, value)¶

Handle the version keyword to setuptools.setup()

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.

versiontools.versiontools_support¶

A small standalone module that allows any package to use versiontools.

Typically you should copy this file verbatim into your source distribution.

Historically versiontools was depending on a exotic feature of setuptools to work. Setuptools has so-called setup-time dependencies, that is modules that need to be downloaded and imported/interrogated for setup.py to run successfully. Versiontools supports this by installing a handler for the ‘version’ keyword of the setup() function.

This approach was always a little annoying as this setuptools feature is rather odd and very few other packages made any use of it. In the future the standard tools for python packaging (especially in python3 world) this feature may be removed or have equivalent thus rendering versiontools completely broken.

Currently the biggest practical issue is the apparent inability to prevent setuptools from downloading packages designated as setup_requires. This is discussed in this pip issue: https://github.com/pypa/pip/issues/410

To counter this issue I’ve redesigned versiontools to be a little smarter. The old mode stays as-is for compatibility. The new mode works differently, without the need for using setup_requires in your setup() call. Instead it requires each package that uses versiontools to ship a verbatim copy of this module and to import it in their setup.py script. This module helps setuptools find package version in the standard PKG-INFO file that is created for all source distributions. Remember that you only need this mode when you don’t want to add a dependency on versiontools. This will still allow you to use versiontools (in a limited way) in your setup.py file.

Technically this module defines an improved version of one of distutils.dist.DistributionMetadata class and monkey-patches distutils to use it. To retain backward compatibility the new feature is only active when a special version string is passed to the setup() call.

class versiontools.versiontools_support.VersiontoolsEnchancedDistributionMetadata(path=None)¶

A subclass of distutils.dist.DistributionMetadata that uses versiontools

Typically you would not instantiate this class directly. It is constructed by distutils.dist.Distribution.__init__() method. Since there is no other way to do it, this module monkey-patches distutils to override the original version of DistributionMetadata

get_version()¶

Get distribution version.

This method is enhanced compared to original distutils implementation. If the version string is set to a special value then instead of using the actual value the real version is obtained by querying versiontools.

If versiontools package is not installed then the version is obtained from the standard section of the PKG-INFO file. This file is automatically created by any source distribution. This method is less useful as it cannot take advantage of version control information that is automatically loaded by versiontools. It has the advantage of not requiring versiontools installation and that it does not depend on setup_requires feature of setuptools.

versiontools.bzr_support¶

Bazaar support for versiontools

Note

To work with Bazaar repositories you will need bzrlib. You can install it with pip or from the bzr package on Ubuntu.

Warning

On Windows the typical Bazaar installation bundles both the python interpreter and a host of libraries and those libraries are not accessible by the typically-installed python interpreter. If you wish to use Bazaar on windows we would recommend to install Bazaar directly from pypi.

class versiontools.bzr_support.BzrIntegration(branch)¶

Bazaar integration for versiontools

branch_nick¶

Nickname of the branch

New in version 1.0.4.

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

class versiontools.bzr_support.BzrShellIntegration(revno, branch_nick)¶

Bazaar (shell version) integration for versiontools

New in version 1.10.

branch_nick¶: Nickname of the branch

classmethod from_source_tree(source_tree)¶: Initialize BzrShellIntegration by pointing at the source tree. Any file or directory inside the source tree may be used.

revno¶: Revision number of the branch

versiontools.git_support¶

Git support for versiontools

Note

To work with Git repositories you will need GitPython. Version 0.1.6 is sufficient to run the code. You can install it with pip. Alternatively, if you have git(1) in your PATH you don’t need any additional python modules.

class versiontools.git_support.GitIntegration(repo)¶

Git integration for versiontools

branch_nick¶

Nickname of the branch

New in version 1.0.4.

commit_id¶: The full commit id

commit_id_abbrev¶: The abbreviated, 7 character commit id

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¶: Same as commit_id_abbrev

class versiontools.git_support.GitShellIntegration(commit_id, branch_nick=None)¶

Git (shell version) integration for versiontools

branch_nick¶

Nickname of the branch

New in version 1.0.4.

commit_id¶: The full commit id

commit_id_abbrev¶: The abbreviated, 7 character commit id

classmethod from_source_tree(source_tree)¶: Initialize GitShellIntegration by pointing at the source tree. Any file or directory inside the source tree may be used.

revno¶: Same as commit_id_abbrev

versiontools.hg_support¶

Mercurial (Hg) support for versiontools.

Note

To work with Mercurial repositories you will need Mercurial. You can install it with pip or from the mercurial package on Ubuntu.

class versiontools.hg_support.HgIntegration(repo)¶

Hg integration for versiontools

branch_nick¶

Nickname of the branch

New in version 1.0.4.

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