Home | Download/Install | Documentation | Packages | Screenshots | News | Forum/Mailing-lists | Contact | GForge



Summary: how to use configure setuptools with setup.cfg and pydistutils Target:administrators and senior developers

What setup.cfg and pydistutils are useful for ?


When using setuptools command such as

python setup.py install bdist_egg -d ./sdist

will build the package and create an egg in the directory ./sdist. Without extra option the filename will simply be NamePackage-version-py2.5.egg where version and NamePackage are provided within the setup.py file.

Sometimes, you may want to add a tag to the filename by using the option tag_build .

All these options can written in a special file called setup.cfg in the same directory as setup.py. This file looks like

tag_build = .dev
tag_svn_revision = 1

In this example, the new filename will be NamePackage-version.dev_rXXXX-py2.5.egg.

Imagine now that you have tens of packages like in OpenAlea. Then, each time you change a tag, you need to change all setup.cfg files. There is an easier way, which consists in creating a file called .pydistutils.cfg in your home directory. Under Windows, this file must be called pydistutils.cfg (without the . in front of it) and you must declare the variable HOME to point to the directory where is placed this file.

Revision number

When using the alea_installer_gui application, or easy_install, or alea_install, there is a factory behin that checks the package's version so as to install only the latest version. If you want to full understand how this factory works, have a look at the setuptools how to specify your version's tag.

In brief, you can use the following code to compare two versions

>>> from pkg_resources import parse_version
>>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
>>> parse_version('2.1-rc2') < parse_version('2.1')
>>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
  • A version consists of an alternating series of release numbers and pre-release or post-release tags.
  • A release number is a series of digits punctuated by dots, such as 2.4 or 0.5.
  • Releases 2.1 and 2.1.0 are different ways to spell the same release number.
  • Leading zeros within a series of digits are also ignored, so 2.01 is the same as 2.1
  • A pre-release tag is a series of letters that are alphabetically before “final”.
  • A post-release tag is a series of letters that are alphabetically greater or equal to “final” or a dash (-)
  • You do not have to place a dot before the prerelease tag if it's immediately after a number, but it's okay to do so if you prefer. Thus, 2.4c1 and 2.4.c1 both represent release candidate 1 of version 2.4, and are treated as identical by setuptools.
  • There are three special prerelease tags that are treated as if they were the letter c: pre, preview, and rc

Here is an ordered list of versions from the most recent to the older one:
0.8.0-1             #(- post tag may be used for patches and revision)
0.8.0-g             #(post tag greater than final)
0.8.0               #(as if if was 0.8.0.final)
0.8.0.fc10          #(!!!!less than final)
0.8.0.rc            #(equivalent to character c but post release tag so greater than dev)
0.8.0.a             #(dev is special tag equivalent to @)
0.8.0.dev           #(dev is special tag equivalent to @)

How to proceed in OpenAlea ?

Let us suppose we deal with the release 0.8.0

The release

  • set all version to 0.8.0 don't set the '.dev' or revision tag.
  • Before the release: set all the requirements to something greater or equal to 0.8.0a. Don't forget the 'a', which means that all 0.8.0.dev will be ignored
  • upload all eggs with the tag 0.8.0 . If linux version, for instance linux, add .fc11 tag_build or .ubuntu9.10

later egg developments

  • increase the release version to 0.8.1
  • add tag_build .dev before (before .fc11 or .ubuntu tag if under linux)
  • upload

The new version 0.8.1.dev will be greater than previous release 0.8.0 but less than a future release 0.8.1 (without .dev)

documentation/tools/pydistutils.txt · Last modified: 2010/01/25 15:58 by admin   Back to top
INRIA GForge RSS feed Valid XHTML 1.0 Valid CSS Driven by DokuWiki