6. Python Package Index (PyPI)¶
Python Package Index (PyPI) はパッケージ作者が望む場合、配布ファイルのようなパッケージデータだけでなく、 distutils でパッケージされた配布物について記述した メタデータ も保存します。
Distutils には、メタデータの発行を行う register と、PyPI に配布物をアップロードする upload コマンドが用意されています。これらコマンドについての詳細は distutils コマンド を参照してください。
6.1. PyPI の概要¶
配布物の様々なバージョンについて、好きなだけインデクスへの提出を行ってかまいません。特定のバージョンに関するメタデータを入れ替えたければ、再度提出を行えば、インデクス上のデータが更新されます。
PyPI は提出された配布物の (名前、バージョン) の各組み合わせについて記録を保持しています。ある配布物名について最初に情報を提出したユーザが、 その配布物名のオーナ (owner) になります。変更は register コマンドか、web インタフェースを介して提出できます。オーナは他のユーザをオーナやメンテナとして指名できます。 メンテナはパッケージ情報を編集できますが、他の人をオーナやメンテナに指名することはできません。
デフォルトでは PyPI はパッケージの最新バージョンしか表示しません。Web インターフェースからこのデフォルトの振る舞いを変更することができ、手動でどのバージョンを見せ、どのバージョンを見せないかを選べます。
それぞれのバージョンについて、 PyPI はホームページを表示します。ホームページは register コマンドで提出出来る long_description から作られます。詳細については PyPI パッケージ表示 をご覧ください。
6.2. distutils コマンド¶
distutils には PyPI にパッケージのデータを送信するための 2 つのコマンドがあります: PyPI にメタデータを送信するための register と配布物ファイルを送信するための upload です。どちらのコマンドも、 .pypirc ファイル という特別なファイルから設定データを読みます。
6.2.1. register コマンド¶
Distutils の register コマンドは、配布物のメタデータをインデックスサーバーに送信するために使います。次のように実行します:
python setup.py register
Distutils は以下のようなプロンプトを出します:
running register
We need to know who you are, so please choose either:
1. use your existing login,
2. register as a new user,
3. have the server generate a new password for you (and email it to you), or
4. quit
Your selection [default 1]:
注意: ユーザ名とパスワードをローカルに保存している場合、このメニューは表示されません。認証情報を .pypirc ファイルに保存する方法については .pypirc ファイル を参照してください。
まだ PyPI に登録したことがなければ、まず登録する必要があります。この場合選択肢 2 番を選び、リクエストされた詳細情報を入力してゆきます。詳細情報を提出し終えると、登録情報の承認を行うためのメールを受け取るはずです。
すでに登録を行ったことがあれば、選択肢 1 を選べます。この選択肢を選ぶと、PyPI ユーザ名とパスワードを入力するよう促され、 register がメタデータをインデクスに自動的に提出します。
register コマンドのオプションについては 追加のコマンドオプション を参照してください。
6.2.2. upload コマンド¶
Distutils のコマンド upload は、配布物ファイルを PyPI へ送ります。
このコマンドは一つ以上の配布物ファイルをビルドした直後に呼び出されます。例えば、次のコマンド
python setup.py sdist bdist_wininst upload
は、ソース配布物とWindowsのインストーラをPyPIにアップロードします。以前に setup.py を実行してビルドした配布物もアップロード対象になるけれども、アップロードされるのは upload コマンドと同時に指定された配布物だけだということに注意してください。
同じコマンド内で register コマンドが呼ばれていて、そこでプロンプトからパスワードを入力した場合、 upload は入力されたパスワードを再利用します。 $HOME/.pypirc ファイルにプレインテキストでパスワードを保存したくない場合はこの方法を利用できます。
You can use the --sign option to tell upload to sign each
uploaded file using GPG (GNU Privacy Guard). The gpg program must
be available for execution on the system PATH. You can also specify
which key to use for signing using the --identity=name option.
upload コマンドの追加のオプションについては 追加のコマンドオプション を参照してください。
6.2.3. 追加のコマンドオプション¶
このセクションで説明するオプションは register, upload の両コマンドに共通です。
--repository または -r オプションで、デフォルトとは異なる PyPI サーバを指定出来ます。例えば:
python setup.py sdist bdist_wininst upload -r https://example.com/pypi
簡単のために、 .pypirc ファイルでそのように設定してあれば、URL の場所に名前を使えます。例えば:
python setup.py register -r other
代替サーバーを定義することについて、より詳しい情報は .pypirc ファイル を参照してください。
--show-response オプションを指定することで、 PyPI サーバからの全ての応答をテキストで表示します。これは登録時・アップロード時に何か問題があった場合のデバッグに有用です。
6.2.4. .pypirc ファイル¶
register, upload コマンドともに、 .pypirc ファイルが $HOME/.pypirc にいるかどうかをチェックします。このファイルがあれば、これらコマンドはユーザ名、パスワード、登録 URL として、このファイルで設定されているものを使います。 .pypirc ファイルのフォーマットは以下のようなものです:
[distutils]
index-servers =
pypi
[pypi]
repository: <repository-url>
username: <username>
password: <password>
distutils セクションは、 index-servers でリポジトリを設定する全てのセクション名の リストを定義しています。
リポジトリを表す各セクションは3つの変数を定義します:
- repository は PyPI サーバの URL を定義します。
デフォルトは
https://upload.pypi.org/legacy/です。
username は PyPI サーバーに登録されたユーザー名です。
- password は認証に使われます。
省略された場合、必要なときに入力を求められます。
別のサーバーを定義した場合は、新しいセクションを作成し、 index-servers に追加します:
[distutils]
index-servers =
pypi
other
[pypi]
repository: <repository-url>
username: <username>
password: <password>
[other]
repository: https://example.com/pypi
username: <username>
password: <password>
これらセクションは register, upload コマンドで、 追加のコマンドオプション で説明した --repository オプションとともに使うことが出来ます。
特に、 PyPI そのものに最初にアップロードする前にテストするのを容易にすべく、あなたの .pypirc には PyPI Test Repository を追加したいでしょう。
6.3. PyPI パッケージ表示¶
long_description フィールドは PyPI において特別な役目を持ちます。サーバーは登録されたパッケージのホームページを表示するためにこれを利用します。
このフィールドに reStructuredText 記法を利用した場合、PyPI はこれをパースして、パッケージのホームページにHTML 出力を表示します。
long_description フィールドにパッケージ内のファイルの内容を利用することもできます:
from distutils.core import setup
with open('README.txt') as file:
long_description = file.read()
setup(name='Distutils',
long_description=long_description)
この例では、 README.txt は通常の reStructuredText テキストファイルで、 setup.py と同じパッケージのルートディレクトリに置かれています。
壊れた reStructuredText を登録してしまうのを防ぐために、コマンドラインから docutils パッケージが提供している rst2html プログラムを利用して long_description をチェックすることができます:
$ python setup.py --long-description | rst2html.py > output.html
docutils は文法に何か問題があると警告を表示します。 PyPI は他にもチェックを行うので (例えば rst2html.py に --no-raw を指定します)、上のコマンドを警告なしに実行できたとしても PyPI での変換が成功することを保証するわけではありません。