Abstract

This PEP describes a new section and a new format for thesetup.cfg file,that allows describing the Metadata of a package without usingsetup.py.

Rejection Notice

As distutils2 is no longer going to be incorporated into the standardlibrary, this PEP was rejected by Alyssa Coghlan in late April, 2013.

A replacement PEP based onPEP 426 (metadata 2.0) will be created thatdefines the minimum amount of information needed to generate an sdistarchive given a source tarball or VCS checkout.

Rationale

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

So, basically, you download it, and run:

$ python setup.py --nameDistribute$ python setup.py --version0.6.4

Wherename andversion are metadata fields. This is working fine butas soon as the developers add more code insetup.py, this feature mightbreak or in worst cases might do unwanted things on the target system.

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

So the rationale of this PEP is to provide a way to declare the metadatain a static configuration file alongsidesetup.py that doesn’t requireany third party code to run.

Adding ametadata section insetup.cfg

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

[metadata]name=Distributeversion=0.6.4

Thesetup.cfg file is used to avoid adding yet another configurationfile to work with in Distutils.

This file is already read by Distutils when a command is executed, andif themetadata section is found, it will be used to fill the metadatafields. If an option that corresponds to a Metadata field is given tosetup(), it will override the value that was possibly present insetup.cfg.

Notice thatsetup.py is still used and can be required to define someoptions that are not part of the Metadata fields. For instance, thesdist command can use options likepackages orscripts.

Multi-lines values

Some Metadata fields can have multiple values. To keepsetup.cfg compatiblewithConfigParser and theRFC 822LONGHEADERFIELDS (see section 3.1.1),these are expressed with,-separated values:

requires=pywin32,bar>1.0,foo

When this variable is read, the values are parsed and transformed into a list:['pywin32','bar>1.0','foo'].

Context-dependant sections

Themetadata section will also be able to use context-dependant sections.

A context-dependant section is a section with a condition about the executionenvironment. Here’s some examples:

[metadata]name=Distributeversion=0.6.4[metadata:sys_platform=='win32']requires=pywin32,bar>1.0obsoletes=pywin31[metadata:os_machine=='i386']requires=foo[metadata:python_version=='2.4'orpython_version=='2.5']requires=bar[metadata:'linux'insys_platform]requires=baz

Every[metadata:condition] section will be used only if the conditionis met when the file is read. The background motivation for thesecontext-dependant sections is to be able to define requirements that variesdepending on the platform the distribution might be installed on.(seePEP 314).

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

The pseudo-grammar is

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

whereEXPR 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, like2.4, orwin32

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

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

>>>fromdistutils.utilimportlocal_metadata>>>local_metadata('setup.cfg')<DistributionMetadata instance>

This means that a vanilla Python will be able to read the metadata of apackage without running any third party code.

Notice that this feature is not restricted to themetadata namespace.Consequently, any other section can be extended with such context-dependantsections.

Impact on PKG-INFO generation and PEP 314

WhenPKG-INFO is generated by Distutils, every field that relies on acondition will have that condition written at the end of the line, after a; separator:

Metadata-Version:1.2Name:distributeVersion:0.6.4...Requires:pywin32,bar>1.0;sys_platform=='win32'Requires:foo;os_machine=='i386'Requires:bar;python_version=='2.4'orpython_version=='2.5'Requires:baz;'linux'insys_platformObsoletes=pywin31;sys_platform=='win32'...Classifier:DevelopmentStatus::5-Production/StableClassifier:IntendedAudience::DevelopersClassifier:License::OSIApproved::PythonSoftwareFoundationLicense

Notice that this file can be opened with theDistributionMetadata class.This class will be able to use the micro-language using the executionenvironment.

Let’s run in on aPython2.5i386Linux:

>>>fromdistutils.distimportDistributionMetadata>>>metadata=DistributionMetadata('PKG_INFO')>>>metadata.get_requires()['foo', 'bar', 'baz']

The execution environment can be overridden in case we want to get the metadatafor another environment:

>>>env={'python_version':'2.4',...'os_name':'nt',...'sys_platform':'win32',...'platform_version':'MVCC++ 6.0'...'platform_machine':'i386'}...>>>metadata=DistributionMetadata('PKG_INFO',environment=env)>>>metadata.get_requires()['bar > 1.0', 'foo', 'bar']

PEP 314 is changed accordingly, meaning that each field will be able tohave that extra condition marker.

Compatibility

This change is based on a new metadata1.2 format meaning thatDistutils will be able to distinguish old PKG-INFO files from new ones.

Thesetup.cfg file change will stayConfigParser-compatible andwill not break existingsetup.cfg files.

Limitations

We are not providing< and> operators at this time, andpython_version is a regular string. This implies usingor operatorswhen a section needs to be restricted to a couple of Python versions.Although, ifPEP 386 is accepted,python_version could be changedinternally into something comparable with strings, and< and> operators introduced.

Last, if a distribution is unable to set all metadata fields insetup.cfg,that’s fine, the fields will be set toUNKNOWN whenlocal_metadata iscalled. GettingUNKNOWN values will mean that it might be necessary torun thesetup.py command line interface to get the whole set of metadata.

Acknowledgments

The Distutils-SIG.

Copyright

This document has been placed in the public domain.