プラットフォームの互換性タグ

プラットフォーム相互互換性タグは、特定のプラットフォームと互換であるとビルドツールが配布物に印を付けることができるようにし、インストーラが自身が動作しているシステムと互換であるのはどの配布物であるかを理解できるようにします。

この仕様に貢献する PEP 群を以下に示す:

1. PEP 425

2. PEP 513

3. PEP 571

4. PEP 599

5. PEP 600

概要

タグの書式は、 {python tag}-{abi tag}-{platform tag} です。

python タグ

'py27' ・ 'cp33'

abi タグ

'cp33dmu' ・ 'none'

プラットフォームタグ

'linux_x86_64' ・ 'any'

例えば、py27-none-any というタグは、abi に対する要求なしに任意のプラットフォームで Python 2.7 (任意の Python 2.7 実装) との互換性を持つことを意味します。

使い方

wheel ビルド済みパッケージのフォーマットは、ファイル名の中にこのようなタグを {distribution}-{version}(-{build tag})?-{python tag}-{abitag}-{platform tag}.whl の形で包含しています。他のパッケージフォーマットにはそれぞれ独自の慣習があるかもしれません。

どのようなタグであれ、その中に潜在的に含まれる空白文字は _ で置換されるべきです。

詳細

Python タグ

Python タグは、配布物が必要とする実装やバージョンを示します。主要な実装には短縮系のコードがあって、当初は:

• py: 一般的な Python (実装に特有な機能を要求しません)

• cp: CPython

• ip: IronPython

• pp: PyPy

• jy: Jython

ほかの Python 実装には sys.implementation.name を用いるべきです。

バージョンは py_version_nodot です。 CPython は no dot にせずに済ませますが、必要な場合には代わりにアンダースコア文字 _ が使用されます。 PyPy は、おそらく、ここに pp18 や pp19 といったそれ自身のバージョンを使います。

多くの純 Python 配布物では、バージョンは 2 や 3 や py2 ・ py3 といったメジャーバージョンだけにしておくことができます。

重要なことは、 py2 や py3 のような major-version-only タグは py20 や py30 の短縮形であるわけではないということです。そうではなくて、これらのタグは、パッケージ作成者がいくつものバージョンに互換性を持つ配布物を意図的にリリースしたのです。

単一ソースで Python 2/3 に互換性を持つ配布物は、合成タグ py2.py3 を用いることができます。 後述の タグの圧縮された組み合わせ を参照してください。

ABI タグ

ABI タグは、いずれかの拡張モジュールによってどのような Python ABI が要求されているのかを示します。実装依存の ABI 群については、実装 (の名前) は、たとえば cp33d がデバッグオプション付きの CPython 3.3 ABI のことを指すように、 Python タグと同様のやり方で短縮したものを使います。

CPython の安定版 ABI のことは、共有ライブラリの拡張子と同様に abi3 と書きます。

非常に不安定な ABI を持つ実装は、そのソースコードのリビジョンやコンパイラフラグその他の SHA-256 ハッシュ値の最初の６バイトを (BASE64にエンコードされた８文字として) 用いても構いませんが、おそらくはバイナリ配布物を配布することには大きな需要はないでしょう。それぞれの実装のコミュニティで ABI タグをどのように用いるのが最適かを決定すればよいでしょう。

プラットフォームタグ

プラットフォームタグは、すべてのハイフン - とピリオド . をアンダースコア _ で単純に置き換えた sysconfig.get_platform() です。 distutils が Python 3.12 で削除されるまでは、これは distutils.util.get_platform() でした。

• win32

• linux_i386

• linux_x86_64

manylinux

Linux プラットフォームのエコシステムが巨大であることとそれらの間に微妙な差異があることから、 PEP 425 で定義されたスキームは、Linux プラットフォーム向けの wheel ファイル (および、一般に *nix 向けの wheel ファイル) の公開配布物としては不十分です。

代わりに、 PEP 600 で Linux プラットフォームの共通のサブセットを表現する``manylinux`` 標準が定義されており、普通の Linux ディストロのほとんどで使える manylinux プラットフォームタグ付きの wheel をビルドできるようにしています。

manylinux 仕様は複数回の改訂があり、それぞれの版がその時々の Linux の共通のサブセットを表現しています:

• manylinux1 (PEP 513) は、 x86_64 および i686 アーキテクチャをサポートしていて、 2007 年から互換性のある Linux プラットフォームに基づいています。

• manylinux2010 (PEP 571) は、 x86_64 および i686 アーキテクチャをサポートしており、以前の仕様を更新して、その代わりに 2010 年から互換性のある Linux プラットフォームに基づいています。

• manylinux2014 (PEP 599) では、多数のアーキテクチャ (aarch64, armv7l, ppc64, ppc64le, and s390x) へのサポートを追加し、また、2014 年以降の互換 Linux プラットフォームのベースを更新しました。

manylinux_x_y (PEP 600) では、それまでの PEP 群を全て代替する形で将来を見据えた標準を定義しました。 x と y は、その標準がサポートする glibc のメジャーバージョンとマイナーバージョンとして定義されています (例えば、 manylinux_2_24 は glibc 2.24+ を使っているディストロならどれでも、その上で動作するはずです) 。以前に使われたタグは広報互換性を保つために依然としてサポートされています。

一般に、古めのバージョンの仕様向けにビルドされた配布物には前方互換性があります (というのは、 manylinux1 の配布物はより新しいシステムでも同様に動作するはずだということです) が、後方互換性はありません (manylinux2010 の配布物が 2010 年よりも前に存在していたプラットフォームで動作するとは想定されていないということです) 。

manylinux1 と manylinux2010 は既に end-of-life に達していて、提供されているビルド環境にはもはやセキュリティアップデートが提供されることはないであろうという警告されていることもあって、パッケージ保守者は最も互換性のある仕様をターゲットにするように努力するべきです。

Manylinux 互換性サポート

注釈

• manylinux2014 仕様は相対的に新しく、未だインストールツールに広く認識されたと言える状況ではありません。

• manylinux_x_y 仕様は相対的に新しく、未だインストールツールに広く認識されたと言える状況ではありません。

適切なプロジェクトがサポートするさまざまな manylinux 標準の最低限のバージョンを次に掲げる表に示します:

ツール	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]

audit wheel 3.3.0 では manylinux_2_24 へのサポートだけが追加されました

使い方

タグ類は、 (もしダウンロードが必要なら) 選択可能なビルド済配布物のリストの中からどれをダウンロードするのかをインストーラが決定するために使われます。インストーラは、自身がサポートする (pyver, abi, arch) タプルのリストを維持管理しています。ビルド済配布物のタグがリストに含まれて (in ) いれば、それをインストールすることができます。

古い Python リリース向けに発行された純 Python のバージョンにフォールバックするよりも前に、利用できる中で最も機能を網羅したビルド済配布物 (インストールする先の環境に最も適したもの) をインストーラがデフォルトで選択することが推奨されています。インストーラは、また、受け入れ可能な互換性タグのリストを設定変更したり順序を入れ替えたりする方法を持つことが推奨されています; 例えば、ユーザは、純 Python であると広報しているビルド済みパッケージだけをダウンロードするために、 *-none-any タグだけを受容しても構いません。

互換性はあるがもはや古くなってしまったビルド済みのものを使う選択肢よりもより好ましいという点で、インストーラに望まれるもうひとつの機能は "可能ならソースコードから再コンパイルする" でしょう。

この事例集は、インストーラを linux_x86_64 システム上の CPython 3.3 のもとで走らせるためのものです。最も好ましいもの (最新版の Python 向けにビルドされたコンパイル済みの拡張モジュールが付属している配布物) から、最も好ましくはないもの (古いバージョンの Python でビルドされた純 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

• ビルド済み配布物は、サブプロセスとして起動されるネーティブの実行可能ファイルを含んでいるなどのようなC 言語拡張以外の理由によって、特定のプラットフォーム向けであっても構いません。

時々、あるパッケージの特定のバージョンとして複数のビルド済み配布物が存在することがあるでしょう。例えば、パッケージ製作者が、 cp33-abi3-linux_x86_64 というタグを付けて追加的な C 言語拡張を含むパッケージをリリースし、そのようなものを含まない同じ配布物に py3-none-any というタグを付けてリリースするような場合です。(このような場合でも) サポートされるタグのリストで先に出現する方を優先するという理由によって C 言語拡張付きのパッケージがそうでないパッケージよりも選好されてインストールされるという形で、インデックスによってどちらかに決めることができます。

圧縮されたタグのセット

bdists のコンパクトなファイル名で、互換性のあるタグトリプルが複数ある場合にもきちんと動作するものを許容するためには、代わりにファイル名の中のそれぞれのタグが '.' で分割可能でありソート可能であるような一連のタグになっていることが可能です。例えば、 pip は純 Python のパッケージで、同一のソースコードで Python 2 でも 3 でも動作するように書かれていますが、これは py2.py3-none-any というタグを付けた bdist として配布することができるでしょう。単純なタグの完全なリストは:

for x in pytag.split('.'):
    for y in abitag.split('.'):
        for z in archtag.split('.'):
            yield '-'.join((x, y, z))

このスキームを実装する bdist フォーマットは、拡張されたタグ群を bdist に特有のメタデータの中に含んでいるべきです。この圧縮スキームは、サポートされていないタグや例えば "cp33-cp31u-win64" のようにいかなる Python 実装においてもサポートされていない "不可能な" タグを大量に生成すると思われるので、控えめに使うようにしてください。

FAQ

デフォルトではどんなタグが使われますか？

ツール類は、 cp33-cp33m-win32 のようなアーキテクチャへの依存を示すタグや py33-none-any のような純 Python タグの中で最も好ましいものをデフォルトで採用するべきです。パッケージ製作者がデフォルトをオーバーライドしていたとすれば、それは彼らが異なる Python 間での互換性を提供しようという意図があったことを示しています。

自分の配布物が最新版の Python と相容れない機能を使っているとしたら、どんなタグを使いますか？

互換性タグは、インストーラがある配布物の 単一のバージョン の 最も互換性がある ビルドを選択する際に助けとなります。例えば、 (Python 3.4 に特有の機能を使っている) beaglevote-1.2.0``には Python 3.3 と互換性を持つビルドがひとつもないという場合でも、 ``py34-none-any タグの代わりに py3-none-any タグを使っても構いません。 Python 3.3 のユーザが互換性のあるビルドを得るためには、新しい機能を使う前のリリースである beaglevote-1.1.0 用の要求 (requirement) などを他の指定子を組み合わせなければなりません。

Python のバージョン番号に . がないのはなぜですか?

CPython は、数字３個のメジャーリリースなしで 20 年以上にわたって存続してきました。これはしばらくの間は続くに違いありません。 - や . が周辺のファイル名を区切る役割を果たしているので、他の実装では _ を区切り子として使っても構いません。

ハイフンやその他の英数字以外の文字をアンダースコアに正規化するのはなぜですか?

ファイル名の部分部分を区分けする . 文字や - 文字との干渉を避けるために、かつ、 (クォートすることなく URL パス内で使用可能であることを含む) 数多あるファイルシステムのファイル名に対する制限事項との間のより良い互換性のために。

何故、 . や - の代わりに特殊な文字 <X> を使わないのですか？

それは、その文字が不便であるかコンテクストによっては潜在的に混乱を招きやすい (例えば + は URL 内ではクォートしなければなりませんし、 ~ は POSIX でユーザのホームディレクトリを示すために使われます) から、あるいは、 PEP 427 で定義された wheel フォーマットを参照して作成された既存の参照実装を変更すること (例えば、圧縮タグで部分部分を分割するのに . ではなく , を使うようにすること) を正当化するに足りるだけのアドバンテージがないから、のいずれかです。

誰が実装に関する短縮形のレジストリの維持管理をしているのですか？

python-dev メーリングリストで要求することで、新しい２文字省略形の割り当てを受けることができるでしょう。経験上は、その時点で最も卓越した４個の実装のために省略形が予約されています。

互換性タグは METADATA に含まれるのか、あるいは PKG-INFO か？

否。互換性タグはビルド済み配布物のメタデータの一部です。METADATA / PKG-INFO は、その配布物の単一のビルドではなく配布物の全体にとって正当なものであるべきです。

どうして私のお気に入りの Python 実装について言及しなかったの？

省略形タグは、コンパイル済みの Python コードを公開のインデックスでシェアすることを促進します。あなたの Python 実装においてもこの仕様を使うことができますが、しかしもっと長いタグになってしまうことでしょう。すべての "純 Python" なビルド済み配布物が単に py を使うだけであることを思い出してください。

どうして参照実装における ABI タグ (第２のタグ) は時々 "none" なのですか？

Python 2 では SOABI (より新しい版の Python 3 から来た概念) を作成する簡単な方法がないので、本稿執筆時点の参照実装は "none" なのです。理想的には、それはもっと新しい版の Python に相似の "py27(d|m|u)" を検出するようになるでしょうが、それまでの間は "知られていない" ことを示すのに "none" とすることが必要十分な方法なのです。