API

Public Interface

versiontag.cache_git_tag()[source]

Try to read the current version from git and, if read successfully, cache it into the version cache file. If the git folder doesn’t exist or if git isn’t installed, this is a no-op. I.E. it won’t blank out a pre-existing version cache file upon failure.

Returns:Project version string
versiontag.get_version(pypi=False)[source]

Get the project version string.

Returns the most-accurate-possible version string for the current project. This order of preference this is:

  1. The actual output of git describe --tags
  2. The contents of the version cache file
  3. The default version, r0.0.0
Parameters:pypi – Default False. When True, returns a PEP-440 compatible version string.
Returns:Project version string

Public Utility Functions

versiontag.convert_to_pypi_version(version)[source]

Convert a git tag version string into something compatible with PEP-440.

Parameters:version – The input version string, normally directly out of git describe.
Returns:PEP-440 version string

Usage:

>>> convert_to_pypi_version('r1.0.1')  # Normal Releases
1.0.1
>>> convert_to_pypi_version('r1.0.1-dev1')  # Dev Releases
1.0.1.dev1
>>> convert_to_pypi_version('r1.0.1-a1')  # Alpha Releases
1.0.1a1
>>> convert_to_pypi_version('r1.0.1-b4')  # Beta Releases
1.0.1b4
>>> convert_to_pypi_version('r1.0.1-rc2')  # RC Releases
1.0.1rc2
>>> convert_to_pypi_version('r1.0.1-12-geaea7b6')  # Post Releases
1.0.1.post12

Private Utility Functions

versiontag.__get_git_tag()[source]

Read the Git project version by running git describe --tags in the current-working-directory.

Returns:Project version string
versiontag.__get_cache_file()[source]

Get the path to the version cache file.

Returns:File path string
versiontag.__open_cache_file(mode)[source]

Open the version cache file in the given mode and return the file object.

Parameters:mode – Mode to open file. See Python file modes.
Returns:File object