> 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. _______________________________________________ Distutils-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/distutils-sig
