natcap.versioner 0.5.0

PEP440-compliant Git and hg versioning

This package provides a consistent versioning scheme for projects of the Natural Capital Project (http://naturalcapitalproject.org). 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

• Installation

• Dependencies

• Usage In Your Project

  • Usage in setup.py

  • Usage in __init__.py

• Support

• Tests

• Development

• 0.5.0

• 0.4.2

• 0.4.1

• 0.4.0

• 0.3.3

• 0.3.2

• 0.3.1

• 0.3.0

• 0.2.4

• 0.2.3

• 0.2.2

• 0.2.1

• 0.2.0

• 0.1.4

• 0.1.3

• 0.1.2

• 0.1.1

• 0.1.0

Versioning Scheme

How a version string is formatted:

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

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

Examples:

• 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

Installation

Via pip: pip install natcap.versioner

Via setup.py: python setup.py install

Note

If you install natcap.versioner via pip or via setup.py, dependencies should install automatically.

Dependencies

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: setup.py and __init__.py.

Usage in setup.py

Adding these lines to your setup.py 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

setup(
    name='example_project',
    ...
    natcap_version='example_project/version.py',
    setup_requires=['natcap.versioner>=0.4.2']
)

Usage in __init__.py

Adding these lines to your package’s __init__.py 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')

Support

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.

Tests

To run the suite of tests:

$ nosetests test/*.py

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

Development

The natcap.versioner source tree is located at https://bitbucket.org/jdouglass/versioner

0.5.0

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

• Added testing via bitbucket pipelines.

0.4.2

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

0.4.1

• Removing the need to import natcap.versioner within setup.py.

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

• Removing pyyaml from setup.py’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.

0.4.0

• Removing dependency on pyyaml.

• Adding __version__ attribute to natcap.versioner.

0.3.3

• 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.

0.3.2

• 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.

0.3.1

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

• Minor stylistic changes for PEP8 and PEP257

0.3.0

• Adding support for git.

• Added tests for core versioning functionality.

0.2.4

• 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.

0.2.3

• 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.

0.2.2

• 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.

0.2.1

• 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.

0.2.0

• API Change: version is now parsed from setup.py 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.

0.1.4

• Attempting to get the utils module to import correctly.

0.1.3

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

0.1.2

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

0.1.1

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

0.1.0

• Initial public release.