first draft for PEP 390

pep-0390.txt

@@ -0,0 +1,164 @@
+PEP: 390
+Title: Static metadata for Distutils
+Version: $Revision: 70705 $
+Last-Modified: $Date: 2009-03-30 06:53:39 +0200 (Lun 30 mar 2009) $
+Author: Tarek Ziadé <tarek@ziade.org>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 10-October-2009
+Python-Version: 2.7 and 3.2
+Post-History:
+
+Abstract
+========
+
+This PEP describes a new section and a new format for the ``setup.cfg`` file,
+that allows describing the Metadata of a package without using ``setup.py``.
+
+Rationale
+=========
+
+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.
+
+
+Adding a ``metadata`` section in ``setup.cfg``
+==============================================
+
+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``.
+
+Context-dependant sections
+==========================
+
+The ``metadata`` section will also be able to use context-dependant sections.
+
+A context-dependant section is a section with a condition about the execution
+environment. Here's some examples::
+
+   [metadata]
+   name = Distribute
+   version = 0.6.4
+
+   [metadata:sys_platform == 'win32']
+   requires: pywin32
+   requires: bar > 1.0
+
+   [metadata:os_machine == 'i386']
+   requires: foo
+
+   [metadata:python_version == '2.4' or python_version == '2.5']
+   requires: bar
+
+   [metadata:'linux' in sys_platform]
+   requires: baz
+
+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
+- os_version = os.uname()[3]
+- os_machine = os.uname()[4]
+- a free string, like ``2.4``, or ``win32``
+
+Distutils will provide a function that is able to read the metadata
+of a distribution, given a ``setup.cfg`` file, for the execution environment::
+
+   >>> from distutils.util import local_metadata
+   >>> local_metadata('setup.cfg')
+   <DistributionMetadata instance>
+
+This means that a vanilla Python will be able to read the metadata of a
+package without running any third party code.
+
+Compatiblity
+============
+
+This change is fully backward compatible since it just adds a section in the
+``ConfigParser``-compatible ``setup.cfg`` file.
+
+Limitations
+===========
+
+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.
+
+Aknowledgments
+==============
+
+The Distutils-SIG.
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   coding: utf-8
+   End: