Abstract

This PEP specifies a tagging system to indicate with which versions ofPython a built or binary distribution is compatible. A set of threetags indicate which Python implementation and language version, ABI,and platform a built distribution requires. The tags are terse becausethey will be included in filenames.

PEP Acceptance

This PEP was accepted by Alyssa Coghlan on 17th February, 2013.

Rationale

Today “python setup.py bdist” generates the same filename on PyPyand CPython, but an incompatible archive, making it inconvenient toshare built distributions in the same folder or index. Instead, builtdistributions should have a file naming convention that includes enoughinformation to decide whether or not a particular archive is compatiblewith a particular implementation.

Previous efforts come from a time where CPython was the only importantimplementation and the ABI was the same as the Python language release.This specification improves upon the older schemes by including the Pythonimplementation, language version, ABI, and platform as a set of tags.

By comparing the tags it supports with the tags listed by thedistribution, an installer can make an educated decision about whetherto download a particular built distribution without having to read itsfull metadata.

Overview

The tag format is {python tag}-{abi tag}-{platform tag}

python tag

‘py27’, ‘cp33’

abi tag

‘cp32dmu’, ‘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.

Use

Thewheel built package format includes these tags in its filenames,of the form{distribution}-{version}(-{buildtag})?-{pythontag}-{abitag}-{platformtag}.whl. Other package formats may have their ownconventions.

Details

Use

The tags are used by installers to decide which built distribution(if any) to download from a list of potential built distributions.The installer maintains a list of (pyver, abi, arch) tuples that itwill support. If the built distribution’s tag isin the list, thenit can be installed.

It is recommended that installers try to choose the most feature completebuilt distribution available (the one most specific to the installationenvironment) by default before falling back to pure Python versionspublished for older Python releases. Installers are also recommended toprovide a way to configure and re-order the list of allowed compatibilitytags; for example, a user might accept only the*-none-any tags to onlydownload built packages that advertise themselves as being pure Python.

Another desirable installer feature might be to include “re-compile fromsource if possible” as more preferable than some of the compatible butlegacy pre-built options.

This example list is for an installer running under CPython 3.3 on alinux_x86_64 system. It is in order from most-preferred (a distributionwith a compiled extension module, built for the current version ofPython) to least-preferred (a pure-Python distribution built with anolder 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 Cextensions, such as by including a native executable invoked asa subprocess.

Sometimes there will be more than one supported built distribution for aparticular version of a package. For example, a packager could releasea package taggedcp33-abi3-linux_x86_64 that contains an optional Cextension and the same distribution taggedpy3-none-any that does not.The index of the tag in the supported tags list breaks the tie, and thepackage with the C extension is installed in preference to the packagewithout because that tag appears first in the list.

Compressed Tag Sets

To allow for compact filenames of bdists that work with more thanone compatibility tag triple, each tag in a filename can instead be a‘.’-separated, sorted, set of tags. For example, pip, a pure-Pythonpackage that is written to run under Python 2 and 3 with the same sourcecode, could distribute a bdist with the tagpy2.py3-none-any.The full list of simple tags is:

forxinpytag.split('.'):foryinabitag.split('.'):forzinarchtag.split('.'):yield'-'.join((x,y,z))

A bdist format that implements this scheme should include the expandedtags in bdist-specific metadata. This compression scheme can generatelarge numbers of unsupported tags and “impossible” tags that are supportedby no Python implementation e.g. “cp33-cp31u-win64”, so use it sparingly.

FAQ

What tags are used by default?

Tools should use the most-preferred architecture dependent tage.g.cp33-cp33m-win32 or the most-preferred pure python tage.g.py33-none-any by default. If the packager overrides thedefault it indicates that they intended to provide cross-Pythoncompatibility.

What tag do I use if my distribution uses a feature exclusive to the newest version of Python?

Compatibility tags aid installers in selecting themost compatiblebuild of asingle version of a distribution. For example, whenthere is no Python 3.3 compatible build ofbeaglevote-1.2.0(it uses a Python 3.4 exclusive feature) it may still use thepy3-none-any tag instead of thepy34-none-any tag. A Python3.3 user must combine other qualifiers, such as a requirement for theolder releasebeaglevote-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. Thisshould continue for some time. Other implementations may use _ asa delimiter, 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 separatecomponents of the filename, and for better compatibility with thewidest range of filesystem limitations for filenames (includingbeing usable in URL paths without quoting).

Why not use special character <X> rather than “.” or “-“?

Either because that character is inconvenient or potentially confusingin some contexts (for example, “+” must be quoted in URLs, “~” isused to denote the user’s home directory in POSIX), or because theadvantages weren’t sufficiently compelling to justify changing theexisting reference implementation for the wheel format defined in PEP427 (for example, using “,” rather than “.” to separate componentsin a compressed tag).

Who will maintain the registry of abbreviated implementations?

New two-letter abbreviations can be requested on the python-devmailing list. As a rule of thumb, abbreviations are reserved forthe 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’smetadata. METADATA / PKG-INFO should be valid for an entiredistribution, 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 apublic index. Your Python implementation can use this specificationtoo, but with longer tags.Recall that all “pure Python” built distributions just use ‘py’.

Why is the ABI tag (the second tag) sometimes “none” in the reference implementation?

Since Python 2 does not have an easy way to get to the SOABI(the concept comes from newer versions of Python 3) the referenceimplementation at the time of writing guesses “none”. Ideally itwould detect “py27(d|m|u)” analogous to newer versions of Python,but in the meantime “none” is a good enough way to say “don’t know”.

References

[1] Egg Filename-Embedded Metadata (http://peak.telecommunity.com/DevCenter/EggFormats#filename-embedded-metadata)

[2] Creating Built Distributions (https://docs.python.org/3.4/distutils/builtdist.html)

Acknowledgements

The author thanks Paul Moore, Alyssa Coghlan, Marc Abramowitz, andMr. Michele Lacchia for their valuable help and advice.

Copyright

This document has been placed in the public domain.