ファイルのヤンク <Yanking>¶
注釈
この仕様は、元々は PEP 592 で定義されました。
注釈
PEP 592 は、 HTML と JSON のインデックス API への変更を含んでいます。これらの変更は、 HTML - プロジェクトの詳細 と JSON - プロジェクトの詳細 の下で シンプルなリポジトリ API で文書化されています。
仕様¶
シンプルなリポジトリの中のリンク群は、値を持たないか任意の文字列を値に取る data-yanked アトリビュートを持っていても 構いません 。 data-yanked アトリビュートが存在していれば、この特定のリンクによって指し示されたファイルが "ヤンクされた <Yanked>" ものだと解釈される べきであって 、特定のシナリオ下を除けば一般的にはインストーラによって選択されるべきものではありません。
data-yanked アトリビュートの値は、もし値が存在するなら、そのファイルがヤンクされた理由を表現する任意の文字列です。シンプルなリポジトリ API を処理するツール類は、エンドユーザ向けにその文字列を表示しても 構いません 。
ヤンクされたアトリビュートは一旦設定されると変更できないというわけではなく、将来の時点で廃止されても構いません (そして、一旦廃止されても再設定することができます) 。そういうことですので、 API ユーザは、ヤンクされたファイルが "ヤンク解除" され (さらに再びヤンクされ) ることに対処でき なければなりません 。
インストーラ類¶
ユーザにとって望ましい経験とは、あるファイルが一旦ヤンクされたら、人間側が今まさにヤンクされたファイルを直接にインストールしようと試みている時、まるでそのファイルが削除されたかのように失敗することです。しかしながら、その人が少し前の時点で試みた場合には、今回はコンピュータが機械的にオリジナルの順序にしたがって今まさにヤンクされたファイルをインストールし、それがヤンクされたファイルなどではなかったかのように振る舞うことです。
インストーラは、ヤンクされたバージョン以外のもので選択上の制約を満足することが可能なら、ヤンクされたリリース群を 無視しなければならず 、要求が全く満たされないことを意味する場合でさえもヤンクされたリリースを 拒否しても構いません 。実装では、上記の意図を汲んだポリシーで、かつ、 "新しい" 依存関係を訳されたリリースやファイルに課すことを避けポリシーを 選択するべきです 。
これが意味するものは、特定のインストーラの全体的な使い方に一番うまく合致する方法を決定するということで、インストーラの裁量に任されています。
ヤンクされたファイル群は、それが (
.*のような範囲を構成するいかなる修正子も付いていない)==か===を使って特定のバージョンに "ピン留め" されたバージョン指定子に合致する唯一のファイルでない限り、常に無視されます。それ以外の場合、このバージョン指定子とのマッチングは、ローカルバージョン・ゼロでのパディング・その他のような事柄について バージョン指定子仕様 にしたがって行われるべきです。ヤンクされたファイル群は、 (
Pipfile.lockやpoetry.lockのような) ロックファイルがインストールされるべきものとして指定しているものに合致する唯一のファイル出ない限り、常に無視されます。この場合には、ヤンクされたファイルは、何らかの入力ファイルやコマンドからそのロックファイルを作成したり更新したりする場合には、 使われるべきではありません 。
あるインストーラがヤンクされたファイルをいつインストールするのかを決めるにあたって、ヤンクされたファイルをインストールすると決定した時にインストーラが警告を 発出するべきです 。そのような警告は、そのファイルがヤンクされた理由についてユーザにより詳しいフィードバックを提供するために、 (もし値があれば) data-yanked アトリビュートの値を 使っても構いません 。
ミラー¶
ミラーは、ヤンクされたファイルを次の二つの方法のうちの一つで扱います:
"アクティブ" なヤンクされたものではないファイル群だけを見せるリポジトリのビューを提供して、シンプルなリポジトリ API から (ヤンクされたファイル群を) 完全に排除する選択をしても構いません。
ヤンクされたファイルも表示するとともに、
data-yankedアトリビュートをもミラーするという選択をしても構いません。
ミラーは、 data-yanked アトリビュートを同時にミラーするのでなければヤンクされたファイルを ミラーしてはいけません 。