[Distutils] .egg-info metadata

[Daniel Holth]

> I've been chatting to Chris McDonough a bit as well, and one
> potentially useful thing would be to clearly document the
> setuptools/distribute metadata precisely as it is generated today.
> Currently these formats are entirely implicit in the implementation of
> the code that reads and writes them, as far as I can tell anyway. The
> distribute docs seem to do a decent job of explaining setup.py and the
> various setuptools specific arguments, but *not* what the file formats
> will look like inside the metadata directory when installed.
>
> The main advantages of this would be to make it clear:
> 1. What can setuptools metadata describe, that v1.2 of the official
> metadata standard cannot?
> 2. Does v1.3 allow everything that setuptools can currently describe
> (either directly, or as an extension)?
> 3. Does v1.3 allow some things to be expressed more clearly than they
> can be with setuptools?

The big new feature with Metadata 1.2 and up that has no
representation in setuptools is the environment markers specification,
which for common cases like 'require x when Python version is y'
allows the generated requirements file to be the same no matter which
version of Python was used to produce the dist:

Requires-Dist: argparse; python_version < '2.7'

would be a common example. The only thing I don't like about it is
that I cannot remember whether to use _ or . to separate the words.
Metadata 1.3 restores extras from setuptools by adding 'extra' as a
variable in environment markers.

In setuptools:

requires.txt:
normal
requirements
not-in-a-section

[extra_name]
extra_requirement

Nothing prevents an installer from generating requires.txt from
Metadata 1.3, but you can't go the other way due to the environment
markers.


entry_points.txt is the plugin mechanism. I am leaving this unchanged
in my implementation; I'm not motivated to put them into PKG-INFO and
there's no benefit. Each section is a kind of entry point, and each
entry is

key = module.name:callable

Split on the colon :, import the first part, return the second part.
console_scripts is the most widely used by far, but thousands of
packages provide other kinds of entry points. I wish pypi was smart
enough to index this file.

entry_points.txt:
[console_scripts]
wininst2wheel = wheel.wininst2wheel:main
egg2wheel = wheel.egg2wheel:main
wheel = wheel.__main__:main

[distutils.commands]
bdist_wheel = wheel.bdist_wheel:bdist_wheel


top_level.txt is just a list of top-level packages defined by the
dist, one per line. Is this still used?

namespace_packages.txt - same format as top_level.txt. Is used.

SOURCES.txt - list of source files, one per line. Not used.

not-zip-safe: present if package should not be zipped up. empty.

dependency_links.txt: url's of the package's dependencies. Speak up if
you use this; it is very surprising, and has a much better replacement
with pip --index options and requirements files.


Provides works the same way in setuptools, it is in PKG-INFO.