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

バージョン 3.4 で追加.

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

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

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

注釈:

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

参考:

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

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


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

コマンドラインインターフェースを起動するには "-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つのスクリプト選択オプションを指定すると例外が発生します。


モジュール 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" への出力の冗
   長レベルをコントロールします。

   引数 "root" 付きで 監査イベント "ensurepip.bootstrap" を送出します
   。

   注釈:

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

   注釈:

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