241 lines
8.6 KiB
Plaintext
241 lines
8.6 KiB
Plaintext
PEP: 425
|
||
Title: Compatibility Tags for Built Distributions
|
||
Version: $Revision$
|
||
Last-Modified: 07-Aug-2012
|
||
Author: Daniel Holth <dholth@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 Coghlan, 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:
|