hgtools 1.1.3

Classes and setuptools plugin for Mercurial repositories

hgtools builds on the setuptools_hg plugin for setuptools. hgtools provides classes for inspecting and working with repositories in the Mercurial version control system.

hgtools provides a plugin for setuptools that enables setuptools to find files under the Mercurial version control system.

The classes provided by hgtools are designed to work natively with the Mercurial Python libraries (in process) or fall back to using the command-line program hg(1) if available. The command-line support is especially useful inside virtualenvs that don’t have access to a system-wide installed Mercurial lib (i.e. when the virtualenv was created with --no-site-packages).

Note

The setuptools feature

You can read about the setuptools plugin provided by hgtools in the setuptools documentation. It basically returns a list of files that are under Mercurial version control when running the setup function, e.g. if you create a source and binary distribution. It’s a simple yet effective way of not having to define package data (non-Python files) manually in MANIFEST templates (MANIFEST.in).

Usage

Here’s a simple example of a setup.py that uses hgtools:

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    version="0.1",
    packages=find_packages(),
    setup_requires=["hgtools"],
)

If you run the setup.py above, setuptools will automatically download hgtools to the directory where the setup.py is located at (and won’t install it anywhere else) to get all package data files from the Mercurial repository.

Auto Version Numbering

With the 0.4 release, hgtools adds support for automatically generating project version numbers from the mercurial repository in which the project is developed.

To use this feature, your project must follow the following assumptions:

• Mercurial tags are used to indicate released versions.

• Tag names are specified as the version only (i.e. 0.1 and not v0.1 or release-0.1)

• Released versions currently must conform to the StrictVersion in distutils. Any tags that don’t match this scheme will be ignored. Future releases may relax this restriction.

Thereafter, you may use the HGToolsManager.get_current_version to determine the version of your product. If the current revision is tagged with a valid version, that version will be used. Otherwise, the tags in the repo will be searched, the latest release will be found, and hgtools will infer the upcoming release version.

For example, if the repo contains the tags 0.1, 0.2, and 0.3 and the repo is not on any of those tags, get_current_version will return ‘0.3.1dev’ and get_current_version(increment=’0.1’) will return ‘0.4dev’.

A distutils hook has been created to hack setuptools to use this version information automatically. To use this functionality, just use the use_hg_version parameter to setup. For example:

from setuptools import setup, find_packages
setup(
    name="HelloWorld",
    use_hg_version=True,
    packages=find_packages(),
    setup_requires=["hgtools"],
)

If the value supplied to use_hg_version resolves to True, hgtools will use the mercurial version to determine the version of the package (based on get_current_version). If an sdist is created, hgtools will store the calculated version in the tag_build of the setup.cfg and will use that version when deploying remotely. Therefore, if you are using auto-versioning, you should not use setuptools tags explicitly.

See the jaraco.util setup.py for an example of this technique.

It’s also possible to send keyword parameters to use_hg_version to tweak how it generates version numbers. For example, if the default increment of 0.1 is not appropriate for your application, you may specify another:

use_hg_version = {'increment': '0.0.1'},

The above configuration will indicate to hgtools to guess the next version of the application to be 0.0.1 greater than the last tagged release.

Options

Set the HGTOOLS_FORCE_CMD environment variable before running setup.py if you want to enforce the use of the hg command (though it will then fall back to the native libraries if the command is not available or fails to run).

Changes

1.1.3

• Fix issue #7 - SubprocessManager now passes explicit environment to child process.

1.1.2

• Restored Python 2.5 compatibility.

1.1

• Added support for subrepos. The setuptools plugin will now traverse subrepos when finding files.

1.0.1

• Fix issue #6 where the force_hg_version flag was affecting installation of tagged packages not employing hgtools.

1.0

• Python 3 support

• Now supports revisions with multiple tags (chooses the first, which appears to be the latest).

• Removed support for deprecated use_hg_version_increment.

• Added HGRepoManager.existing_only to filter managers for only those which refer to an existing repo.

• Employed HGRepoManager.existing_only in plugins. Fixes #2.

• SubprocessManager no longer writes to /dev/null. Fixes #3.

0.6.7

• Auto-versioning will no longer use the parent tag if the working copy has modifications.

0.6.6

• Some minor refactoring - moved functions out of top-level hgtools module into hgtools.plugins.

0.6.5

• Test case and fix for error in SubprocessManager when ‘hg’ executable doesn’t exist.

0.6.4

• Fix for NameError created in 0.6.3.

0.6.3

• Deprecated use_hg_version_increment setup parameter in favor of parameters to use_hg_version.

0.6.2

• From drakonen: hgtools will now utilize the parent changeset tag for repositories that were just tagged (no need to update to that tag to release).

0.6.1

• Fixed issue #4: Tag-based autoversioning fails if hgrc defaults used for hg identify

0.6

• Refactored modules. Created managers, versioning, and py25compat modules.

0.5.2

• Yet another fix for #1. It appears that simply not activating the function is not sufficient. It may be activated by previously- installed packages, so it needs to be robust for non-hgtools packages.

0.5.1

• Fix for issue #1 - version_calc_plugin is activated for projects that never called for it.

• LibraryManagers no longer raise errors during the import step (instead, they just report as being invalid).

• SubprocessManager now raises a RuntimeError if the executed command does not complete with a success code.

0.5

• Fixed issue in file_finder_plugin where searching for an appropriate manager would fail if mercurial was not installed in the Python instance (ImportErrors weren’t trapped properly).

0.4.9

• Fixed issue where version calculation would fail if tags contained spaces.

0.4.8

• Auto versioning now provides a reasonable default when no version tags are yet present.

0.4.3-0.4.7

• Fixes for versions handling of hgtools itself.

0.4.2

• Fixed formatting errors in documentation.

0.4.1

• Reformatted package layout so that other modules can be included.

• Restored missing namedtuple_backport (provides Python 2.5 support).

0.4

• First release supporting automatic versioning using mercurial tags.