[Distutils] Distribute comments

[K. Richard Pixley]

I've just read through the Distribute doc for the first time and I have 
a few comments.

First, I just want to say that the state of python packaging is a sad 
morass.  It's not easy for someone to sort out 
distutils/setuptools/distribute to figure out how to get a package built 
and released on pypi.  Distutils is official and available, but the 
documentation is only slightly relevant with much time and space given 
to features that aren't clear, aren't relevant, or don't solve today's 
problems.  Setuptools is messy, confusing, ill documented, and difficult 
to use.  The Distribute documentation helps in this considerably but it 
could be better.

For instance...

I wish that the Distribute documentation didn't refer to itself as 
"setuptools".  This is confusing.  From where I'm sitting, Distribute is 
a fork.  It may have started life once upon a time in a distant past 
that I don't care about as a fork of setuptools but as of today, it's a 
separate package which just happens to provide a superset of the 
setuptools features along with a setuptools compatible replacement 
interface.  To say that one can use a Distribute script to install 
"setuptools" is a misnomer.  It suggests that the original setuptools is 
being installed rather than installing Distribute, (which just happens 
to provide functional replacements for setuptools).  That's not what I 
want.  I want Distribute and Distribute alone.  I'm willing to go to 
some effort to make sure that people who use my package never need to 
know about, read about, or even think about setuptools.

Toward that end, I wish that the documentation would explain how to 
import Distribute specifically, in a non-setuptools compatible way.  I 
don't need or want a setuptools compatible replacement.  I have a new 
package and I'm completely willing to make my package wholly dependent 
on Distribute rather than setuptools.  Even attempting to support 
setuptools at this point in history seems like a mistake to me.  If I'm 
going to include distribute_setup.py in my package, then it seems to me 
that I'm already committed to Distribute, not setuptools.  Leaving the 
illusion that an installer might be able to make setuptools work for my 
package seems misguided.  I'd like to eliminate that thought.

The section on "What Your Users Should Know" sounds like the sort of 
information which has traditionally been released in an INSTALL file 
with GNU software.  Is there a reusable, sample template which explains 
this information in a package agnostic sort of way that I can simply 
include in my package?

Thanks for reading.

--rich
<http://packages.python.org/distribute/setuptools.html#id25>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20101229/dc1e3603/attachment.html>