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

[Phillip J. Eby]

At 08:38 AM 4/19/2006 +0200, Fredrik Lundh wrote:
>I'm -1 on adding tools to the core that changes the structure of an installed
>Python system, without a full PEP process.  If nobody can point to (or 
>produce)
>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 in-
>spect) 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 .)

I do think that "changes the structure of an installed Python system" is 
rather vague, though.  Python supports .pth files, for example, so is 
writing to a .pth file "changing the structure of an installed Python 
system"?  Python supports installing modules in directories on PYTHONPATH 
or specifying zip files on it, so are these operations "changing structure"?

I ask not to argue, but to make sure I know what else it is that you want 
documented, so I can be specific about what is and isn't documented.  My 
vague guess at the moment is that the only things that setuptools does 
which could be considered "changing the structure of an installed Python 
system" are:

1. If installing to a PYTHONPATH directory (instead of site-packages), it 
adds a special 'site.py' file so that .pth files are processed in 
PYTHONPATH directories.  (Python does not normally process .pth files on 
PYTHONPATH, but this is necessary to support dynamic installation of 
packages without modifying PYTHONPATH itself.  'site' is hooked instead of 
'sitecustomize' to avoid interfering with a user-defined 'sitecustomize'.)

2. If installing a package in "compatibility mode" (aka 
--single-version-externally-managed, or if --root was specified), it adds 
an .egg-info directory to hold setuptools-specific metadata.  This will be 
named something like 'FooBar-1.0.egg-info', and placed in the target 
directory alongside the installed package.  So if the package were 
installed as Lib/foobar, the egg-info would be stored in 
Lib/FooBar-1.0.egg-info/.