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.