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" ファイル
-------------------------

The **register** and **upload** commands both check for the existence
of a ".pypirc" file at the location "$HOME/.pypirc". If this file
exists, the command uses the username, password, and repository URL
configured in the file.  The format of a ".pypirc" file is as follows:

   [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* は認証に使われます。

     省略された場合、必要なときに入力を求められます。

If you want to define another server a new section can be created and
listed in the *index-servers* variable:

   [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 での変換が成功することを
保証するわけではありません。
