Tags de compatibilidade de plataforma

As tags de compatibilidade de plataforma permitem que ferramentas de construção marquem as distribuições como sendo compatíveis com plataformas específicas e permitem que os instaladores entendam quais distribuições são compatíveis com o sistema em que estão executando.

The following PEPs contributed to this spec:

1. PEP 425

2. PEP 513

3. PEP 571

4. PEP 599

5. PEP 600

Visão geral

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 compatibility with Python 2.7 (any Python 2.7 implementation) with no abi requirement, on any platform.

Use

The wheel built package format includes these tags in its filenames, of the form {distribution}-{version}(-{build tag})?-{python tag}-{abitag}-{platform tag}.whl. Other package formats may have their own conventions.

Any potential spaces in any tag should be replaced with _.

Detalhes

Python Tag

The Python tag indicates the implementation and 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 version is py_version_nodot. CPython gets away with no dot, but if one is needed the underscore _ is used instead. PyPy should probably use its own versions here pp18, pp19.

The version can be just the major version 2 or 3 py2, py3 for many pure-Python distributions.

Importantly, major-version-only tags like py2 and py3 are not shorthand for py20 and py30. Instead, these tags mean the packager intentionally released a cross-version-compatible distribution.

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.

The CPython stable ABI is abi3 as in the shared library suffix.

Implementations with a very unstable ABI may use the first 6 bytes (as 8 base64-encoded characters) of the SHA-256 hash of their 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 _.

• win32

• linux_i386

• linux_x86_64

manylinux

The scheme defined in PEP 425 was insufficient for public distribution of wheel files (and *nix wheel files in general) to Linux platforms, due to the large ecosystem of Linux platforms and subtle differences between them.

Em vez disso, a PEP 600 define o padrão manylinux, que representa um subconjunto comum de plataformas Linux, e permite a construção de wheels com a tag de plataforma manylinux que pode ser usada na maioria das distribuições Linux.

Houve várias iterações da especificação manylinux, cada uma representando o subconjunto comum de plataformas Linux em um determinado ponto no tempo:

• manylinux1 (PEP 513) oferece suporte às arquiteturas x86_64 e i686 e é baseado em uma plataforma Linux compatível de 2007.

• manylinux2010 (PEP 571) oferece suporte às arquiteturas x86_64 e i686 e atualiza a especificação anterior para se basear em uma plataforma Linux compatível a partir de 2010.

• manylinux2014 (PEP 599) adiciona suporte para várias arquiteturas adicionais (aarch64, armv7l, ppc64, ppc64le e s390x) e atualiza a plataforma base para uma plataforma Linux compatível de 2014.

manylinux_x_y (PEP 600) substitui todas as PEPs anteriores para definir um padrão à prova de futuro. Ele define x e y como as versões principais e secundárias do glibc suportadas (por exemplo, manylinux_2_24 deve funcionar em qualquer distro usando glibc 2.24+). Tags anteriores ainda são suportadas para compatibilidade com versões anteriores.

Em geral, as distribuições construídas para versões mais antigas da especificação são compatíveis com versões futuras (o que significa que as distribuições manylinux1 devem continuar a funcionar em sistemas modernos), mas não compatíveis com versões anteriores (significando que distribuições manylinux2010 não devem trabalhar em plataformas que existiam antes de 2010).

Os mantenedores do pacote devem tentar atingir a especificação mais compatível possível, com a ressalva de que o ambiente de compilação fornecido para manylinux1 e manylinux2010 atingiu o fim da vida, o que significa que essas imagens não receberão mais atualizações de segurança.

Suporte a compatibilidade de manylinux

Nota

• A especificação de manylinux2014 é relativamente nova e ainda não é amplamente reconhecida pelas ferramentas de instalação.

• A especificação de manylinux_x_y é relativamente nova e não é amplamente reconhecida pelas ferramentas de instalação.

A tabela a seguir mostra as versões mínimas de projetos relevantes para oferecer suporte aos vários padrões manylinux:

Ferramenta	manylinux1	manylinux2010	manylinux2014	manylinux_x_y
pip	>=8.1.0	>=19.0	>=19.3	>=20.3
auditwheel	>=1.0.0	>=2.0.0	>=3.0.0	>=3.3.0 1

1

Suporte somente para manylinux_2_24 foi adicionado em auditwheel 3.3.0

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 it will support. If the built distribution’s tag is in the list, then it can be installed.

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.

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. The index of the tag in the supported tags list breaks the tie, and the package with the C extension is installed in preference to the package without because that tag appears first in the list.

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

What tags are used by default?

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

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 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 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 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.

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 reference implementation at the time of writing guesses “none”. Ideally it would 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”.