[Distutils] automating __version__' ing issues

[Alexander Michael]

On 5/13/07, Alexander Schmolck <a.schmolck at gmx.net> wrote:
> Hi,
>
> I'm still trying to figure out how to handle versioning, including development
> release versioning in a simple but automated fashion. Basically assuming svn
> had some hypothetical, $Version$ tag, which would either list the user-chosen
> version name, plus, if there have been changes since that has been last
> assigned, a the project-wide svn-release number (e.g. "1.1" or "1.1.dev43"),
> I'd just put that in setup.py, the project's __version__ = ... string in
> __init__.py and ideally even the docs. No such thing exists, however and so
> far I've been doing it by hand, which is clearly suboptimal, especially since
> I'm also currently writing a howto for scikits authors (
> <http://projects.scipy.org/scipy/scikits>, very rough at the moment) were I'd
> like to give best practices.
>
> Basically, if svn had a $Revision$ keyword that worked, I'd just use that in
> setup.py and the package's __init__ (and possibly the README). Now
> numpy.distutils.utils contains some code to create a __svn_version__.py file
> which can then be used in conjunction with a version.py file, in which one
> specifies the official version number + a release flag (true or false) to get
> either "1.1" or "1.1.dev43". I've started to detail this at
> <http://projects.scipy.org/scipy/scikits#version.py>, but it seems rather
> clumsy and also has the disadvantage that one needs to use numpy.distutils in
> addtition to setuptools, further complicating things (numpy.distutils is also
> not that well documented IMO, and I haven't got the approach to work as I
> would want).
>
> So I was wondering if there wasn't maybbe a nicer way to achieve this, using
> just setuptools. I've had a look at
>
> <http://peak.telecommunity.com/DevCenter/setuptools#id31>
>
> but from that it's e.g. not clear to me how one would obtain the right
> __version__ string in ``project/__init__.py``. I think I might just have
> missed the right info in the docs, but I'd really appreciate it if someone
> could walk me through the steps how I can specify at one place that I want to
> create a proper release with version X or a development release with version
> X.devY and have this info available everywhere it's needed.

SVN does support keywords, but you need to turn-on keyword
interpolation (see the SVN documentation describing properties for how
to do this), but I don't think you'll need this functionality.
Development release suffixes can be added with setuptools
(<http://peak.telecommunity.com/DevCenter/setuptools#managing-continuous-releases-using-subversion>).
 When using this technique, the setup.py version string must be the
*next* version (the one under development that is typically your SVN
Trunk). Here's the rub-- it must be in setup.py and you probably want
to give your package access to it so that it can be reported. It
appears that the current idiom for solving this dilemma is to but a
release.py or version.py file in your package, which is sucked up into
the setup.py file with execfile (see
<http://kid-templating.org/trac/browser/trunk/setup.py> for an
example). You then manually maintain the version number in one place
(the release.py file).

Also note that it appears the current trend is to keep __init__.py
files empty (required if you ever want to create a setuptools
namespace package) and create an api.py file with convenient exports.
This is done to avoid running into issues with circular references. I
would be tempted to but version information my __init__.py file (and
only version information), but this will breakdown if the package ever
grows to become a namespace package. Perhaps avoiding this
simplification, however, is over future-proofing.