"ensurepip" --- "pip" 安裝器的初始建置 (bootstrapping)
******************************************************

在 3.4 版被加入.

**原始碼：**Lib/ensurepip

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

"ensurepip" 套件 (package) 為既有的 Python 安裝或虛擬環境提供 "pip" 安
裝器初始建置 (bootstrapping) 的支援。這個初始建置的方式應證了事實 ——
"pip" 是有其獨立發布週期的專案，且其最新可用穩定的版本，會與 CPython
直譯器 (interpreter) 之維護和功能發布綁定。

大多數情況下，Python 的終端使用者不需要直接叫用此模組（因為 "pip" 預設
應為初始建置），但若安裝 Python 時 "pip" 被省略（或建立一虛擬環境時）
，又或是 "pip" 被明確解除安裝時，則此模組的初始建置仍有可能用上。

備註:

  此模組*不會*存取網路。所有需要用來初始建置 "pip" 的元件都已包含在套
  件之內。

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see 可選
模組的需求.

也參考:

  安裝 Python 模組
     對於終端使用者安裝 Python 套件的指引

  **PEP 453**: 在 Python 安裝中的 pip 明確初始建置
     此模組的最初設計理念與規範。

可用性: not Android, not iOS, not WASI.

此模組在行動平台或 WebAssembly 平台上不支援。


命令列介面
==========

使用直譯器 (interpreter) 的 "-m" 來叫用命令列介面

最簡單可行的呼叫：

   python -m ensurepip

若 "pip" 未安裝，此呼叫會將其安裝；否則甚麼也不做。可透過傳入 "--
upgrade" 參數來確保 "pip" 的安裝版本至少為目前 "ensurepip" 中最新可用
的版本：

   python -m ensurepip --upgrade

預設上，"pip" 會被安裝至目前虛擬環境（若已啟動虛擬環境）或系統端的套件
（若沒有啟動的虛擬環境）。安裝位置可透過兩個額外的命令列選項來控制：

--root <dir>

   安裝 "pip" 到給定的根目錄 (root directory) 的相對路徑，而不是目前虛
   擬環境（若存在）的根目錄，或目前 Python 安裝版所預設的根目錄。

--user

   安裝 "pip" 到使用者端的套件目錄，而不是全域安裝到目前的 Python 安裝
   版（此選項不允許在一啟動的虛擬環境中使用）。

預設會安裝 "pipX" 和 "pipX.Y" 腳本（X.Y 代表用來叫用 "ensurepip" 的
Python 之版本）。安裝的腳本可透過兩個額外的命令列選項來控制：

--altinstall

   若要求一個替代安裝版，則*不會*安裝 "pipX" 腳本。

--default-pip

   若要求安裝「預設 pip」，則會安裝 "pip" 腳本，及 2 個常規腳本。

提供兩種指令選項將會導致例外 (exception) 。


模組 API
========

"ensurepip" 開放了兩個用於編寫程式的函式：

ensurepip.version()

   回傳一個字串，用以標明初始建置時，安裝的 pip 的可行版本號。

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

   在目前或指定的環境之中建立 "pip"。

   *root* 指定一個替代的根目錄，作為安裝的相對路徑。若 *root* 為
   "None"，則安裝使用目前環境的預設安裝位置。

   *upgrade* 指出是否要將一個既有的較早版本的 "pip" 升級至可用的新版。

   *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" 均有副作用。改為在
     一子行程 (subprocess) 呼叫命令列介面可避免這些副作用。

   備註:

     初始建置的過程也許會安裝 "pip" 所需要的額外的模組，但其他軟體不應
     該假設這些相依 (dependency) 總是預設存在（因為這些相依很可能會在
     未來版本的 "pip" 中被移除）。
