[Python-Dev] PEP 376

[Paul Moore]

2009/7/1 Tarek Ziadé <ziade.tarek at gmail.com>:
> Right it's unclear, I'll work on this part.
>
> To resume :
>
> - Phase 1 : introduction of the egg-info file in distutils
>
> Philipp introduced the creation of a file named xxx.egg-info file in 2006
> (see http://bugs.python.org/issue1459476)  alongside
> distutils-installed package, that contains
> the metadata of the distribution.
>
> - Phase 2:  two new formats in the setuptools project
>
> Then he created two new formats in the setuptools project:
>
> 1. an .egg-info directory containing a PKG-INFO file, which is similar
> to the previous .egg-info file. This happened
>   because other files were added in that directory.
>
> 2. an .egg directory, possibly zipped, that is a self-contained
> version of the distribution, containing the metadata and all other
> files.
>
> Setuptools uses 2. by default. There's an option when you use
> setuptools to force 1. (–single-version-externally-managed *or*
> --root).
>
> - Phase 3: adopting a unified standard.
>
> It occurs that having a .egg-info directory (1.) is way better than a
> single file because it's a place-holder for other files.
> It is also adopted by the community when it comes to install
> setuptools-based package.:
>
> - This is what "pip" uses to install packages in a more flat manner.
> - It's also the policy under debian
> (http://wiki.debian.org/DebianPython/NewPolicy)
> - and under Fedora
> (http://fedoraproject.org/wiki/Packaging/Python/Eggs#Providing_Eggs_using_Setuptools)
>
> The .egg directory (2.) is more controversial because it a
> self-contained directory that doesn't install packages
> so it makes two different ways to work with distributions for packagers.
>
> So I have proposed in the PEP to adopt the standalone .egg-info
> directory as the new distutils unified standard.
>
> This means that all the third-party tools out there already conform to
> that standard, and that packages installed
> in other formats will not benefit from the new APIs. which means that
> people that want to work with distributions installed as .egg
> directories will have to use setuptools APIs.
> Which makes sense.

Ah, that makes a *lot* more sense. So, in a "compatibility" section,
you could point out that the proposed standard is compatible with
setuptools "single version externally managed" format, and that the
setuptools multi-version format (the egg file/directory) is a
non-standard format designed to allow multiple versions to be
installed at once - something out of scope for this PEP.

With that explanation, people like me who glaze over at the
complexities of setuptools scenarios should be able to see what's
going on.

Thanks for clarifying.

>> General rule - don't document (and commit yourself to) any internal
>> details that the user can't access from the public API. It just makes
>> backward compatibility harder to maintain.
>
> The purpose is to provide this documentation to third-party projects that want
> to implement a packaging system on the top of these classes.

Hmm, but you don't explain how they should do that. I certainly
wouldn't know how to. As the public API is pkgutil.get_distribution
(and the like) which isn't a class so cannot be subclassed, it's not
clear how a 3rd party could hook in a subclass of
(Zipped)Distribution. And as there's nothing in the public API that
consumes these classes, creating them by hand is of no use, either.

> Maybe this should be removed from the PEP and but into another
> document targeted to developers ?

No. If it's needed by developers, it should be defined in the PEP, not
elsewhere. But it should be defined in a way that developers can use -
not just for the sake of defining it. Unless there is a concrete use
case (which should be stated as an example in the PEP) then *not*
documenting the classes is of more help to developers, as they don't
have to follow a definition that isn't used.

Paul.