[Python-checkins] r76274 - peps/trunk/pep-0345.txt

[tarek.ziade]

Author: tarek.ziade
Date: Sun Nov 15 00:55:17 2009
New Revision: 76274

Log:
added the environment markers

Modified:
   peps/trunk/pep-0345.txt

Modified: peps/trunk/pep-0345.txt
==============================================================================
--- peps/trunk/pep-0345.txt	(original)
+++ peps/trunk/pep-0345.txt	Sun Nov 15 00:55:17 2009
@@ -444,11 +444,69 @@
 
 XXX command-line interface needs work, obviously
 
+Environment markers
+===================
+
+An **environment marker** is a marker that can be added at the end of a
+field after a semi-colon (';'), to add a condition about the execution
+environment.
+
+Here are some example of fields using such markers::
+
+   Requires-Dist: pywin32, bar > 1.0; sys.platform == 'win32'
+   Obsoletes-Dist: pywin31; sys.platform == 'win32'
+   Requires-Dist: foo; os.machine == 'i386'
+   Requires-Dist: bar; python_version == '2.4' or python_version == '2.5'
+   Requires-External: libxslt; 'linux' in sys.platform
+
+These markers are using a micro-language that can be interpreted using a 
+function ``interpret_marker`` provided in the ``distutils.util`` module
+in the stdlib::
+
+    >>> from distutils.util import
+    >>> interpret_marker("sys.platform == 'win32'")
+    True
+
+Depending if the execution environment meets the requirements, the function 
+will return True or False.
+
+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.
+
+The fields that benefit from this marker are:
+
+- Requires-Python
+- Requires-External
+- Requires-Dist
+- Provides-Dist
+- Obsoletes-Dist
+- Classifier
+
 Summary of Differences From PEP 314
 ===================================
 
 * Metadata-Version is now 1.2.
 
+* Added the environment markers.
+
 * Added fields:
 
   - Maintainer
@@ -494,6 +552,9 @@
 Fred Drake, Anthony Baxter and Matthias Klose have all contributed to
 the ideas presented in this PEP.
 
+Tres Seaver, Jim Fulton, Marc-André Lemburg, Tarek Ziadé and other people at 
+the Distutils-SIG have contributed to the new updated version.
+
 
 ..
    Local Variables: