How to include VCS information in setuptools packages

Question

I'm (trying) to use setuptools to build a package. I was trying to use a version number major.minor.mercurial_revision but it complains that:

The version specified ('1.0.7ae7970a82c1') is an invalid version, this may
not work as expected with newer versions of setuptools, pip, and PyPI.
Please see PEP 440 for more details.`

Fine. So I look at PEP 440 which says basically says "don't do that":

As hashes cannot be ordered reliably such versions are not permitted in the
public version field. As with semantic versioning, the public  .devN  
suffix may be used to uniquely identify such releases for publication, 
while the original DVCS based label can be stored in the project metadata. 

I understand the logic here. But how can I include the hg revision in the project metadata? I can't find any (up-to-date) documentation for what the arguments to setup.py:setup() can include, but the distutils one I found here doesn't seem to provide a field for this.

Answer 1

What about just including it as an attribute in your Python code?

echo '__revision__ = $HG_HASH' > mypackage/revision.py

Once installed, you can:

from mypackage.revision import __revision__
print 'build from', __revision__

Or you could write it to a file, and include that in your source distribution via MANIFEST.in .

You could even include it directly in the arguments to setup() , which seems to simply ignore unknown keyword arguments:

setup(name='Distutils',
      version='1.0',
      description='Python Distribution Utilities',
      author='Greg Ward',
      author_email='gward@python.net',
      url='https://www.python.org/sigs/distutils-sig/',
      packages=['distutils', 'distutils.command'],
      revision='7ae7970a82c1',
     )

This doesn't get recorded anywhere, but it is always available by inspection if someone needs to know it for debugging information or something. Because this relies on setup() ignoring unknown arguments -- which I'm not sure is explicitly documented behavior -- I don't know that this idea is actually one I would recommend.

Answer 2

You can use a local version identifier to accomplish this.

Local version identifiers MUST comply with the following scheme:

<public version identifier>[+<local version label>]

In your case this would be <major>.<minor>+<mercurial_version> , which would result into 1.0+7ae7970a82c1