[Python-checkins] peps: Add Daniel Holth's binary compatibility tag PEP

Sat Aug 11 15:53:54 CEST 2012

http://hg.python.org/peps/rev/2a7dc13e5c62
changeset: 4498:2a7dc13e5c62
user: Nick Coghlan <ncoghlan at gmail.com>
date: Sat Aug 11 23:53:43 2012 +1000
summary:
 Add Daniel Holth's binary compatibility tag PEP
files:
 pep-0425.txt | 240 +++++++++++++++++++++++++++++++++++++++
 1 files changed, 240 insertions(+), 0 deletions(-)

diff --git a/pep-0425.txt b/pep-0425.txt
new file mode 100644
--- /dev/null
+++ b/pep-0425.txt
@@ -0,0 +1,240 @@
+PEP: 425
+Title: Compatibility Tags for Built Distributions 
+Version: $Revision$
+Last-Modified: 07-Aug-2012
+Author: Daniel Holth <dholth at fastmail.fm>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 27-Jul-2012
+Python-Version: 3.4
+Post-History: 8-Aug-2012
+
+
+Abstract
+========
+
+This PEP specifies a tagging system to indicate with which versions of
+Python a built or binary distribution is compatible. A set of three
+tags indicate which Python implementation and language version, ABI,
+and platform a built distribution requires. The tags are terse because
+they will be included in filenames.
+
+
+PEP Editor's Note
+=================
+
+While the naming scheme described in this PEP will not be supported directly
+in the standard library until Python 3.4 at the earliest, draft
+implementations may be made available in third party projects.
+
+
+Rationale
+=========
+
+Today "python setup.py bdist" generates the same filename on PyPy
+and CPython, but an incompatible archive, making it inconvenient to
+share built distributions in the same folder or index. Instead, built
+distributions should have a file naming convention that includes enough
+information to decide whether or not a particular archive is compatible
+with a particular implementation.
+
+Previous efforts come from a time where CPython was the only important
+implementation and the ABI was the same as the Python language release.
+This specification improves upon the older schemes by including the Python
+implementation, language version, ABI, and platform as a set of tags.
+
+By comparing the tags it supports with the tags listed by the
+distribution, an installer can make an educated decision about whether
+to download a particular built distribution without having to read its
+full metadata.
+
+Overview
+========
+
+The tag format is {python tag}-{abi tag}-{platform tag}
+
+python tag
+ ‘py27’, ‘cp33’
+abi tag
+ ‘cp33dmu’, ‘none’
+platform tag
+ ‘linux_x86_64’, ‘any’
+
+For example, the tag py27-none-any indicates compatible with Python 2.7
+(any Python 2.7 implementation) with no abi requirement, on any platform.
+
+Details
+=======
+
+Python Tag
+----------
+
+The Python tag indicates both the implementation and the language version
+required by a distribution. Major implementations have abbreviated
+codes, initially:
+
+* py: Generic Python (does not require implementation-specific features)
+* cp: CPython
+* ip: IronPython
+* pp: PyPy
+* jy: Jython
+
+Other Python implementations should use `sys.implementation.name`.
+
+The language version is `py_version_nodot`, or just the major version
+`2` or `3` for many pure-Python distributions. CPython gets away with
+no dot, but if one is needed the underscore `_` is used instead.
+
+A single-source Python 2/3 compatible distribution can use the compound
+tag `py2.py3`. See `Compressed Tag Sets`, below.
+
+ABI Tag
+-------
+
+The ABI tag indicates which Python ABI is required by any included
+extension modules. For implementation-specific ABIs, the implementation
+is abbreviated in the same way as the Python Tag, e.g. `cp33d` would be
+the CPython 3.3 ABI with debugging.
+
+As a special case, the CPython stable ABI starts with `py`; `py32`
+is that ABI with only the operations available from Python 3.2 onward.
+
+Implementations with a very unstable ABI may use the first 6 bytes (as
+8 base64-encoded characters) of the SHA-256 hash of ther source code
+revision and compiler flags, etc, but will probably not have a great need
+to distribute binary distributions. Each implementation's community may
+decide how to best use the ABI tag.
+
+Platform Tag
+------------
+
+The platform tag is simply `distutils.util.get_platform()` with all
+hyphens `-` and periods `.` replaced with underscore `_`.
+
+Use
+===
+
+The tags are used by installers to decide which built distribution
+(if any) to download from a list of potential built distributions.
+Installers will have a list of (python, abi, plat) that the current
+Python installation can run sorted by order of preference. Each built
+distribution recieves a score based on its tag's position in the list,
+and the most-preferred distribution is the one that is installed.
+If no built distribution matches the list of supported tag tuples then
+the installer falls back to installing from the source distribution.
+Tags are only compared for equality; they are never greater or less than
+another tag, and a tag that 'startswith' another tag is not a subset of
+the shorter tag.
+
+For example, an installer running under CPython 3.3 on an imaginary MMIX
+system might prefer, in order::
+
+ 1. (cp33, cp33, mmix) # built for this specific version of Python
+ 2. (cp33, py32, mmix) # using the stable ABI as defined by Python 3.2
+ 3. (cp33, none, mmix) # using no ABI, but still depending on the specific
+ platform (e.g. through ctypes or os.system)
+ 4. (cp33, none, any) # pure-Python distribution for the current Python
+ 5. (py33, none, any) # pure-Python distribution for the current (generic)
+ Python
+ 6. (py32, none, any) # pure-Python distributions for older versions of
+ Python
+ 7. (py31, none, any) # ""
+ 8. (py30, none, any) # ""
+ 9. (py3, none, any) # ""
+
+A distribution that requires CPython 3.3 or CPython 2.7 and has an
+optional extension module could distribute built distributions tagged
+`cp33-cp3-mmix`, `cp33-none-any`, and `cp27-none-any`. (Our imaginary
+program is using 2to3, so the built distribution is not compatible across
+major releases.) `cp33-cp3-mmix` gets a score of 1, `cp33-none-any`
+gets a score of 3, and `cp27-none-any` is not in the list at all. Since
+`cp33-cp3-mmix` has the best score, that built distribution is installed.
+
+A user could instruct their installer to fall back to building from an
+sdist more or less often by configuring this list of tags.
+
+Compressed Tag Sets
+===================
+
+To allow for compact filenames of bdists that work with more than
+one compatibility tag triple, each tag in a filename can instead be a
+'.'-separated, sorted, set of tags. For example, pip, a pure-Python
+package that is written to run under Python 2 and 3 with the same source
+code, could distribute a bdist with the tag `py2.py3-none-any`.
+The full list of simple tags is::
+
+ for x in pytag.split('.'):
+ for y in abitag.split('.'):
+ for z in archtag.split('.'):
+ yield '-'.join((x, y, z))
+
+A bdist format that implements this scheme should include the expanded
+tags in bdist-specific metadata. This compression scheme can generate
+large numbers of unsupported tags and "impossible" tags that are supported
+by no Python implementation e.g. "cp33-cp31u-win64", so use it sparingly.
+
+FAQ
+===
+
+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.
+
+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.
+
+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
+ the current 4 most prominent implementations. 
+
+Does the compatibility tag go into METADATA or PKG-INFO?
+ No. The compatibility tag is part of the built distribution's
+ metadata. METADATA / PKG-INFO should be valid for an entire
+ distribution, not a single build of that distribution.
+
+Why didn't you mention my favorite Python implementation?
+ The abbreviated tags facilitate sharing compiled Python code in a
+ public index. Your Python implementation can use this specification
+ too, but with longer tags.
+ Recall that all "pure Python" built distributions just use 'py'.
+
+References
+==========
+
+.. [1] Egg Filename-Embedded Metadata
+ (http://peak.telecommunity.com/DevCenter/EggFormats#filename-embedded-metadata)
+
+.. [2] Creating Built Distributions
+ (http://docs.python.org/distutils/builtdist.html)
+
+.. [3] PEP 3147 -- PYC Repository Directories
+ (http://www.python.org/dev/peps/pep-3147/)
+
+Acknowledgements
+================
+
+The author thanks Paul Moore, Nick Coughlan, Mark Abramowitz, and
+Mr. Michele Lacchia for their valuable advice and help with this effort.
+
+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:
-- 
Repository URL: http://hg.python.org/peps
