28.2. "ensurepip" ---  "pip" インストーラのブートストラップ
***********************************************************

バージョン 3.4 で追加.

======================================================================

"ensurepip" パッケージは "pip" インストーラを既にインストールされてい
る Python 環境や仮想環境にブートストラップする助けになります。このブー
トストラップのアプローチは "pip" が独立したリリースサイクルを持ち、最
新の利用可能な安定版が CPython リファレンスインタープリタのメンテナン
スリリースや feature リリースにバンドルされていることを反映しています
。

ほとんどの場合、Python のエンドユーザーがこのモジュールを直接呼び出す
必要はないでしょう("pip" はデフォルトでブートストラップされるからです)
。しかし、もし Python のインストール時に "pip" のインストールをスキッ
プしたり、仮想環境を構築したり、明示的に "pip" をアンインストールした
場合、直接呼び出す必要があるかもしれません。

注釈: このモジュールはインターネットに *アクセスしません*。"pip" の
  ブート ストラップに必要な全てはこのパッケージの一部として含まれてい
  ます。

参考:

  Python モジュールのインストール
     エンドユーザーが Python パッケージをインストールする際のガイドで
     す。

  **PEP 453**: Python インストールの際の明示的なpipのブートストラッピ
  ング
     このモジュールのもともとの論拠と仕様。


28.2.1. コマンドラインインターフェイス
======================================

コマンドラインインターフェースを起動するには "-m" スイッチをつけてイン
タープリターを使用します。

最も簡単な起動方法は:

   python -m ensurepip

この起動方法は "pip" をインストールします。既にインストールされていた
場合は何もしません。インストールされた "pip" のバージョンを
"ensurepip" にバンドルされているもののうち、できるだけ新しいものにする
ためには、"--upgrade" オプションを追加して:

   python -m ensurepip --upgrade

デフォルトでは、"pip" は現在の仮想環境(もしアクティブなら)か、システム
のサイトパッケージ(もしアクティブな仮想環境がなければ)にインストールさ
れます。インストール先は２つの追加コマンドラインオプションで制御できま
す:

* "--root <dir>": 現在のアクティブな仮想環境(もしあれば)の root や現
  在 インストールされている Python の root ディレクトリに入れる代わり
  に、 与えられたディレクトリを root として "pip" をインストールします
  。

* "--user": は、現在インストールされている Python にグローバルにイン
  ス トールされる代わりに、ユーザーの site packages ディレクトリに
  "pip" をインストールします(このオプションはアクティブな仮想環境のも
  とでは 許可されません)。

デフォルトでは "pipX" と "pipX.Y" がインストールされます(X.Yは
"ensurepip" を起動したPythonのバージョン)。インストールされるスクリプ
トは2つの追加コマンドラインオプションで制御できます:

* "--altinstall": alternate インストール。X.Y でバージョン付けされた
  も のだけがインストールされます。

* "--default-pip": もし  "default pip" のインストールが要求されたな
  ら

     この "pip" スクリプトは2つの標準スクリプトと共にインストールされ
     ます。

2つのスクリプト選択オプションを指定すると例外が発生します。

バージョン 3.6.3 で変更: コマンドが失敗した場合、終了ステータスは非ゼ
ロです。


28.2.2. モジュール API
======================

"ensurepip" はプログラムから利用出来る 2 つの関数を公開しています:

ensurepip.version()

   環境にブートストラップする際にインストールされることになる pip のバ
   ンドルバージョンを示す文字列を返します。

ensurepip.bootstrap(root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

   現在の環境あるいは指示された環境へ "pip" をブートストラップします。

   *root* で、インストールの root ディレクトリを変更します。 *root* が
   "None" の場合は、インストールは現在の環境でのデフォルトの場所を使い
   ます。

   *upgrade* で、 "pip" のバンドルのバージョンとして、インストール済み
   の以前のバージョンをアップグレードするかどうかを指定します。

   *user* で、グローバルなインストールではなく user スキームを使うかど
   うかを指定します。

   デフォルトではスクリプト "pipX" と "pipX.Y" はインストールされます
   (X.YはPythonの現在のバージョンです)。

   *altinstall* が設定されていた場合は "pipX" はインストール *されませ
   ん*。

   *default_pip* がセットされていれば、 "pip" スクリプトが2つの標準ス
   クリプトと共にインストールされます。

   *altinstall* と *default_pip* の両方を指定すると、 "ValueError" を
   起こします。

   *verbosity* でブートストラップ操作からの "sys.stdout" への出力の冗
   長レベルをコントロールします。

   注釈: ブートストラップ処理は "sys.path", "os.environ" の両方に対
     して副 作用を持ちます。代わりに、サブプロセスとしてコマンドライン
     インタ ーフェイスを使うことで、これら副作用を避けることが出来ます
     。

   注釈: ブートストラップ処理は "pip" によって必要とされるモジュール
     を追加 インストールするかもしれませんが、ほかのソフトウェアはそれ
     ら依存 物がいつもデフォルトで存在していることを仮定すべきではあり
     ません( 将来のバージョンの "pip" ではその依存はなくなるかもしれま
     せんので )。
