[Python-checkins] peps: update faq, recommended example list

[daniel.holth]

http://hg.python.org/peps/rev/071b013f0e2c
changeset:   4744:071b013f0e2c
user:        Daniel Holth <dholth at fastmail.fm>
date:        Sat Feb 16 22:55:23 2013 -0500
summary:
  update faq, recommended example list

files:
  pep-0425.txt |  90 ++++++++++++++++++++++++++-------------
  1 files changed, 60 insertions(+), 30 deletions(-)


diff --git a/pep-0425.txt b/pep-0425.txt
--- a/pep-0425.txt
+++ b/pep-0425.txt
@@ -139,32 +139,44 @@
 will support.  If the built distribution's tag is `in` the list, then
 it can be installed.
 
-For example, an installer running under CPython 3.3 on a linux_x86_64
-system might support::
-
- 1. cp33-cp33m-linux_x86_64
- 2. cp33-abi3-linux_x86_64
- 3. cp33-none-linux_x86_64
- 4. cp33-none-any
- 5. cp3-none-any
- 6. cp32-none-any
- 7. cp31-none-any
- 8. cp30-none-any
- 9. py33-none-any
- 10. py3-none-any
- 11. py32-none-any
- 12. py31-none-any
- 13. py30-none-any
-
-The list is in order from most-preferred (a distribution with a
-compiled extension module, built for the current version of Python)
-to least-preferred (a pure-Python distribution built with an older
-version of Python).  A user could instruct their installer to fall back
-to building from an sdist more or less often by configuring this list of
-tags; for example, a user could include only the `*-none-any` tags to only
+It is recommended that installers try to choose the most feature complete
+built distribution available (the one most specific to the installation
+environment) by default before falling back to pure Python versions
+published for older Python releases. Installers are also recommended to
+provide a way to configure and re-order the list of allowed compatibility
+tags; for example, a user might accept only the `*-none-any` tags to only
 download built packages that advertise themselves as being pure Python.
 
-Rarely there will be more than one supported built distribution for a
+Another desirable installer feature might be to include "re-compile from
+source if possible" as more preferable than some of the compatible but
+legacy pre-built options.
+
+This example list is for an installer running under CPython 3.3 on a
+linux_x86_64 system. It is in order from most-preferred (a distribution
+with a compiled extension module, built for the current version of
+Python) to least-preferred (a pure-Python distribution built with an
+older version of Python)::
+
+1.  cp33-cp33m-linux_x86_64
+2.  cp33-abi3-linux_x86_64
+3.  cp3-abi3-linux_x86_64
+4.  cp33-none-linux_x86_64*
+5.  cp3-none-linux_x86_64*
+6.  py33-none-linux_x86_64*
+7.  py3-none-linux_x86_64*
+8.  cp33-none-any
+9.  cp3-none-any
+10.  py33-none-any
+11.  py3-none-any
+12.  py32-none-any
+13.  py31-none-any
+14.  py30-none-any
+
+* Built distributions may be platform specific for reasons other than C
+  extensions, such as by including a native executable invoked as
+  a subprocess.
+
+Sometimes there will be more than one supported built distribution for a
 particular version of a package.  For example, a packager could release
 a package tagged `cp33-abi3-linux_x86_64` that contains an optional C
 extension and the same distribution tagged `py3-none-any` that does not.
@@ -202,18 +214,36 @@
     default it indicates that they intended to provide cross-Python
     compatibility.
 
-Can I have a tag `py32+` to indicate a minimum Python minor release?
-    No.  Inspect the Trove classifiers to determine this level of
-    cross-release compatibility.  Similar to the announcements "beaglevote
-    versions 3.2 and above no longer supports Python 1.52", you will
-    have to manually keep track of the maximum (PEP-386) release that
-    still supports your version of Python.
+What tag do I use if my distribution uses a feature exclusive to the newest version of Python?
+    Compatibility tags aid installers in selecting the *most compatible*
+    build of a *single version* of a distribution. For example, when
+    there is no Python 3.3 compatible build of ``beaglevote-1.2.0``
+    (it uses a Python 3.4 exclusive feature) it may still use the
+    ``py3-none-any`` tag instead of the ``py34-none-any`` tag. A Python
+    3.3 user must combine other qualifiers, such as a requirement for the
+    older release ``beaglevote-1.1.0`` that does not use the new feature,
+    to get a compatible build.
 
 Why isn't there a `.` in the Python version number?
     CPython has lasted 20+ years without a 3-digit major release. This
     should continue for some time.  Other implementations may use _ as
     a delimeter, since both - and . delimit the surrounding filename.
 
+Why normalise hyphens and other non-alphanumeric characters to underscores?
+    To avoid conflicting with the "." and "-" characters that separate
+    components of the filename, and for better compatibility with the
+    widest range of filesystem limitations for filenames (including
+    being usable in URL paths without quoting).
+
+Why not use special character <X> rather than "." or "-"?
+    Either because that character is inconvenient or potentially confusing
+    in some contexts (for example, "+" must be quoted in URLs, "~" is
+    used to denote the user's home directory in POSIX), or because the
+    advantages weren't sufficiently compelling to justify changing the
+    existing reference implementation for the wheel format defined in PEP
+    427 (for example, using "," rather than "." to separate components
+    in a compressed tag).
+
 Who will maintain the registry of abbreviated implementations?
     New two-letter abbreviations can be requested on the python-dev
     mailing list.  As a rule of thumb, abbreviations are reserved for

-- 
Repository URL: http://hg.python.org/peps