first draft for PEP 390
This commit is contained in:
Tarek Ziadé
parent
1c2ec30d5d
commit
8723863b3b
|
|
@ -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:
|
||||
Loading…
Reference in New Issue