2009/7/1 Tarek Ziadé firstname.lastname@example.org:
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:
- 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.
- 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
- and under Fedora
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.