Skip to main content

PEP440-compliant Git and hg versioning

Project description

This package provides a consistent versioning scheme for projects of the Natural Capital Project ( The versioning string currently provided is PEP440-compliant, and is supported for both git and mercurial repositories. Mercurial source archives (created by the hg archive command) are also supported.

Versioning Scheme

How a version string is formatted:

If we are at a tag:
    version = {tag}
    version = {tag}.post{N}+r{nodeid|short}

If there are no tags:
    {tag} = 'null'


  • Version string = 3.4.5

    • Meaning: This version of this tool was built from the tag 3.4.5.

    • You can update to this revision by calling hg update -r 3.4.5

  • Version string = 3.4.5.post35+r788a29c99234

    • Meaning: This version of this tool was built from a revision where:

      • The latest tag was 3.4.5

      • The latest commit on this branch is 35 commits beyond the latest tag.

      • The latest commit has a shortened node ID of 788a29c99234

    • You can update to this revision by calling hg update -r 788a29c99234


Via pip: pip install natcap.versioner

Via python install


Note that natcap.versioner requires setuptools and six.

Usage In Your Project

To use this project, you’ll need to edit two files within your own project: and

Usage in

Adding these lines to your allows the DVCS information to be fetched from git or hg and recorded in the package metadata. Additionally, the version will be recorded to the file you indicate with the natcap_version keyword.

from setuptools import setup


Usage in

Adding these lines to your package’s file will allow the package version to be fetched from the package metadata.

# Let's assume your package name is still 'example_project'
import natcap.versioner
__version__ = natcap.versioner.get_version('example_project')


If something doesn’t work, it’s probably broken! Please submit an issue via the issue tracker, send James an email or stop by if you’re in the office and I’ll try to fix it!

You can also file an issue in our issue tracker.


To run the suite of tests:

$ nosetests test/*.py

Note that hg and git must be available as executables on the command-line.


The natcap.versioner source tree is located at


  • Added python 3.x support. Installation now requires six.

  • Added testing via bitbucket pipelines.


  • Correcting an issue when using the natcap_version distutils keyword where the distutils version attribute was being improperly set.


  • Removing the need to import natcap.versioner within

  • natcap.versioner now uses its own functionality to generate its version string.

  • Removing pyyaml from’s install_requires. This will prevent pyyaml from being installed, despite the fact that pyyaml is no longer used by natcap.versioner.

  • Git, Hg, and Hg archive repositories can now be referred to by a subdirectory within the repo itself.


  • Removing dependency on pyyaml.

  • Adding __version__ attribute to natcap.versioner.


  • Tests now have full coverage of the package.

  • Git repositories without branches are now correctly handled.

  • Errors encountered in calls to hg and git command-line applications will cause subprocess.CalledProcessError to be raised.


  • Setting setuptools zip_safe=True. After a review of the module, it appears that no functionality within natcap.versioner requires access to resources within the package via the filesystem.


  • Restoring support for installation as egg (0.3.0 lacked this).

  • Minor stylistic changes for PEP8 and PEP257


  • Adding support for git.

  • Added tests for core versioning functionality.


  • Allowing get_version() to allow fallback to SCM only when allowed by user input. Defaults to only allowing fallback in non-frozen environments (e.g. a source tree). natcap.versioner.VersionNotFound will be raised if the version string cannot be loaded normally or SCM is disallowed.

  • If a version string cannot be parsed by vcs_version(), natcap.versioner.VersionNotFound will optionally be raised.


  • Turning setuptools zip_safe flag to False. When this and natcap.invest have their zip_safe flags all as False, the packages happily install side-by-side as individual eggs.


  • Fixes an issue where a development version is returned when the user is at a tag. The version is now correctly reported as just the tag.


  • Version files are now properly imported. This fixes an issue with users unable to fetch version strings from within frozen environments that are outside of a source tree.


  • API Change: version is now parsed from using natcap.versioner.parse_version().

  • Allowing the version to be correctly fetched from PKG-INFO from egg/distribution metadata even when the package has not already been built.


  • Attempting to get the utils module to import correctly.


  • Allowing version string to be written to a package file.


  • Default version scheme is dvcs-based post-release now. but can also do a pre-release.


  • Fixes installation issues where certain files needed for were missing from the source distribution.


  • Initial public release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

natcap.versioner-0.5.0.tar.gz (12.1 kB view hashes)

Uploaded source

Built Distributions

natcap.versioner-0.5.0-py3-none-any.whl (14.4 kB view hashes)

Uploaded 3 5

natcap.versioner-0.5.0-py2-none-any.whl (14.4 kB view hashes)

Uploaded 2 7

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page