Today, if you want to list all the Metadata of a distribution (see PEP 314)
that is not installed, you need to use the setup.py command line interface.

So, basically, you download it, and run:

$ python setup.py --name
Distribute
$ python setup.py --version
0.6.4

Where name and version are metadata fields. This is working fine but
as soon as the developers add more code in setup.py, this feature might
break or in worst cases might do unwanted things on the target system.

Moreover, when an OS packager wants to get the metadata of a distribution
he is re-packaging, he might encounter some problems to understand
the setup.py file he's working with.

So the rationale of this PEP is to provide a way to declare the metadata
in a static configuration file alongside setup.py that doesn't require
any third party code to run.

The first thing we want to introduce is a [metadata] section, in the
setup.cfg file, that may contain any field from the Metadata:

[metadata]
name = Distribute
version = 0.6.4

The setup.cfg file is used to avoid adding yet another configuration
file to work with in Distutils.

This file is already read by Distutils when a command is executed, and
if the metadata section is found, it will be used to fill the metadata
fields. If an option that corresponds to a Metadata field is given to
setup(), it will override the value that was possibly present in
setup.cfg.

Notice that setup.py is still used and can be required to define some
options that are not part of the Metadata fields. For instance, the
sdist command can use options like packages or scripts.

Every [metadata:condition] section will be used only if the condition
is met when the file is read. The background motivation for these
context-dependant sections is to be able to define requirements that varies
depending on the platform the distribution might be installed on.
(see PEP 314).

The micro-language behind this is the simplest possible: it compares only
strings, with the == and in operators (and their opposites), and
with the ability to combine expressions. It makes it also easy to understand
to non-pythoneers.

The pseudo-grammar is

EXPR [in|==|!=|not in] EXPR [or|and] ...

where EXPR belongs to any of those:

python_version = '%s.%s' % (sys.version_info[0], sys.version_info[1])

os_name = os.name

sys_platform = sys.platform

platform_version = platform.version()

platform_machine = platform.machine()

a free string, like 2.4, or win32

Notice that in is restricted to strings, meaning that it is not possible
to use other sequences like tuples or lists on the right side.

Distutils will provide a function that is able to generate the metadata
of a distribution, given a setup.cfg file, for the execution environment:

We are not providing < and > operators at this time, and
python_version is a regular string. This implies using or operators
when a section needs to be restricted to a couple of Python versions.
Although, if PEP 386 is accepted, python_version could be changed
internally into something comparable with strings, and
< and > operators introduced.

Last, if a distribution is unable to set all metadata fields in setup.cfg,
that's fine, the fields will be set to UNKNOWN when local_metadata is
called. Getting UNKNOWN values will mean that it might be necessary to
run the setup.py command line interface to get the whole set of metadata.