[Python-Dev] setuptools in the stdlib ( r45510 - python/trunk/Lib/pkgutil.py python/trunk/Lib/pydoc.py)

[Phillip J. Eby]

At 11:36 PM 4/19/2006 +0200, Fredrik Lundh wrote:
>Phillip J. Eby wrote:
>
> > >a technical document that, in full detail, describes the mechanisms 
> *used* by
> > >setuptools, including what files it creates, what the files contain, how
> > >they are used during import, how non-setuptools code can manipulate (or at
> > > least inpect) the data, etc, setuptools should *not* go into 2.5.
> >
> > And that is a mostly-specific, very fair, and completely reasonable
> > objection.  And I think a significant portion of it is answered by the
> > existing documentation, at least with respect to the runtime.  The
> > pkg_resources API module includes all of the discovery, dependency
> > resolution and introspection other facilities used by setuptools, and it
> > does not depend on the rest of setuptools, which is directed primarily at
> > building and installing eggs.  A number of users have written simple Python
> > scripts using the documented API in order to list installed packages and
> > that sort of thing.  The current API reference documentation is available
> > at http://peak.telecommunity.com/DevCenter/PkgResources .)
>
>What I want is a PEP that explains the things that are manipulated by
>this API.  What things are stored where, what do they contain, and how
>are they are used by the various tools ?
>
>The API in itself isn't very interesting; I'm interested in the underlying
>design.

But the API *documentation* is where you'll find:

* The external formats understood for version numbers and version requirements
* The escaping and comparison rules for project names and version numbers
* The external formats used for dependency listings
* The external formats used for declaring plugins
* The conceptual overview for the design, including terminology and the 
design concepts exposed by the objects and operations
* A link to the original design overview, which I wrote with a mind to it 
becoming part of a PEP someday:

    http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html

And probably many more things that I don't recall off the top of my head.

If what you want is an implementer's guide to which actual files contain 
what data in which of the above formats, I'll admit there isn't such a 
roadmap.  I could probably write one up by tomorrow, since it would mostly 
be a list of "here are the filenames, this is what format in the existing 
documentation is used for this file, and here's what the contents are used 
for, and here are some pointers to relevant parts of the user and API docs 
that you should read in order to understand what this is for".

However, if you don't read at least the API docs, you're definitely going 
to be missing most of the design picture.