Author: tarek.ziade
Date: Mon Oct 12 16:59:50 2009
New Revision: 75382
Log:
updated after some feedback from distutils-SIG and MAL
Modified:
peps/trunk/pep-0390.txt
Modified: peps/trunk/pep-0390.txt
==============================================================================
--- peps/trunk/pep-0390.txt (original)
+++ peps/trunk/pep-0390.txt Mon Oct 12 16:59:50 2009
@@ -31,7 +31,7 @@
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
+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
@@ -46,7 +46,7 @@
Adding a ``metadata`` section in ``setup.cfg``
==============================================
-The first thing we want to introduce is a ``[metadata]`` section, in the
+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]
@@ -62,6 +62,24 @@
``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``.
+
+
+Multi-lines values
+==================
+
+Some Metadata fields can have multiple values. To keep ``setup.cfg`` compatible
+with ``ConfigParser`` and the RFC 822 ``LONG HEADER FIELDS`` (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
==========================
@@ -75,8 +93,8 @@
version = 0.6.4
[metadata:sys_platform == 'win32']
- requires = pywin32
- requires = bar > 1.0
+ requires = pywin32, bar > 1.0
+ obsoletes = pywin31
[metadata:os_machine == 'i386']
requires = foo
@@ -90,12 +108,12 @@
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.
+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
+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 ::
@@ -107,11 +125,14 @@
- python_version = '%s.%s' % (sys.version_info[0], sys.version_info[1])
- os_name = os.name
- sys_platform = sys.platform
-- os_version = os.uname()[3]
-- os_machine = os.uname()[4]
+- platform_version = platform.version()
+- platform_machine = platform.machine()
- a free string, like ``2.4``, or ``win32``
-Distutils will provide a function that is able to read the metadata
+Notice that ``in`` is restricted to strings, meaning that it is not possible
+to use other sequences like tuples or lists on the left 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::
>>> from distutils.util import local_metadata
@@ -121,11 +142,66 @@
This means that a vanilla Python will be able to read the metadata of a
package without running any third party code.
+Notice that this feature is not restricted to the ``metadata`` namespace.
+Consequently, any other section can be extended with such context-dependant
+sections.
+
+Impact on PKG-INFO generation and PEP 314
+=========================================
+
+When ``PKG-INFO`` is generated by Distutils, every field that relies on a
+condition will have that condition written at the end of the line, after a `;`
+separator::
+
+ Metadata-Version: 1.2
+ Name: distribute
+ Version: 0.6.4
+ ...
+ Requires: pywin32, bar > 1.0; sys_platform == 'win32'
+ Requires: foo; os_machine == 'i386'
+ Requires: bar; python_version == '2.4' or python_version == '2.5'
+ Requires: baz; 'linux' in sys_platform
+ Obsoletes = pywin31; sys_platform == 'win32'
+ ...
+ Classifier: Development Status :: 5 - Production/Stable
+ Classifier: Intended Audience :: Developers
+ Classifier: License :: OSI Approved :: Python Software Foundation License
+
+Notice that this file can be opened with the ``DistributionMetadata`` class.
+This class will be able to use the micro-language using the execution
+environment.
+
+Let's run in on a ``Python 2.5 i386 Linux``::
+
+ >>> from distutils.dist import DistributionMetadata
+ >>> metadata = DistributionMetadata('PKG_INFO')
+ >>> metadata.get_requires()
+ ['foo', 'bar', 'baz']
+
+The execution environment can be overriden in case we want to get the meyadata
+for 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 to
+have that extra condition marker.
+
Compatiblity
============
-This change is fully backward compatible since it just adds a section in the
-``ConfigParser``-compatible ``setup.cfg`` file.
+This change is is based on a new metadata ``1.2`` format meaning that
+Distutils will be able to distinguish old PKG-INFO files from new ones.
+
+The ``setup.cfg`` file change will stay ``ConfigParser``-compatible and
+will not break existing ``setup.cfg`` files.
Limitations
===========
@@ -134,12 +210,12 @@
``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
+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
+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.
Acknowledgments