[Distutils] Problem upgrading docutils with setuptools

[Phillip J. Eby]

At 02:53 PM 1/25/2006 +0100, Maciek Starzyk wrote:
>Then upgrade to docutils 0.4.
>Note that setup says "roman" module is already there. It was installed
>as a part of docutils 0.3.9. At the moment when setup checks for
>module roman - docutils 0.3.9 egg is still on the PYTHONPATH and therefore
>"roman" is not installed.

A simple fix is to do "easy_install -m docutils" before the upgrade, as 
this will remove the existing version from the .pth file.


>  But later on docutils 0.3.9 egg is removed from
>PYTHONPATH and docutils 0.4 fails:
>
>EasyInstall docs say:
> > installing a package automatically replaces
> > any previous version in the easy-install.pth file
>
>So maybe this replacing should be done earlier - ensuring that the
>previous version's code
>is not in path - before actually running setup ?
>
>Or is it a bug in docutils' setup.py ?

Well, docutils' setup.py is clearly trying to support Python versions older 
than 2.3, or else it would not be checking for textwrap and 
optparse.  Setuptools only supports 2.3 and higher.  So those modules 
shouldn't be an issue.

If docutils were intended to use setuptools, then it would not make sense 
to check for 'roman', either, since an external dependency should be just 
that, a dependency.  So in that case I would consider it a bug in their 
setup.py.  However, since they clearly are trying to support 2.2 and maybe 
older versions as well, it's hard to call it that.  Rather, I'd have to say 
it's a limitation of setuptools' ability to be backward-compatible with 
highly-customized setup scripts.

Unfortunately, there is no way to remove the existing version from sys.path 
before the setup script runs, as before setup() is called, there's no way 
to know precisely which project needs to be removed.  EasyInstall accepts 
URLs and directory names as well as project names, so it's not guaranteed 
that it will know what project it's building.  EasyInstall also doesn't 
change sys.path at all under normal circumstances; it only changes the .pth 
file so that sys.path will be changed the next time Python is started.

If I were to propose a change to docutils' setup.py, I would suggest that 
roman.py should either be bundled as part of the docutils package (i.e. 
always installed, but inside the docutils package directory), or else be 
treated as an external dependency (never installed by the setup script 
directly, only by the user or by setuptools' dependency handling).  Either 
of these approaches is a robust way to deal with the issue.

Checking for modules' presence at installation time, however, isn't a good 
practice at all; I found it to be fragile and error-prone for PEAK (which 
used to rely on zope.interface, among other things) before setuptools even 
existed.