簡介
****

「Python 函式庫」包含了許多不同的部分。

函式庫中包括被視為程式語言「核心」部分的資料型別，像是數字 (number) 或
是串列 (list)。對於這些型別，Python 核心對這些字面值 (literal) 的形式
做定義，並對它們的語意制定了一些限制，但在此同時卻不把文字對應的語意完
全定義。（另一方面，Python 在語法面上有確實的定義，例如拼字或是運算元
次序）

Python 函式庫也囊括了內建函式與例外處理——這些物件都可以不用透過
"import" 陳述式來引入 Python 程式中就能使用。函式庫中有部份是被 Python
核心所定義的，但在這裡僅解釋最核心的語意部分。

整個函式庫中包含了許多模組，有許多方法可以從函式庫中取用這些模組。有些
模組是以 C 語言撰寫並建置於 Python 直譯器之中，其他的是由 Python 撰寫
並以源碼的方式 (source form) 引入。有些模組提供的功能是專屬於 Python
的，像是把 stack trace 印出來；有些則是針對特定作業系統，去試著存取特
定硬體；還有些提供對特定應用的功能與操作介面，像是 World Wide Web。模
組的使用情況會因機器與 Python 的版本而不同，部分模組是開放所有版本以及
Port 的 Python 來使用的，但有些會因系統支援或需求在某些版本或系統下無
法使用，甚至有些僅限在特定的設定環境下才能使用。

這個手冊會「深入淺出」地介紹 Python 函式庫。它會先介紹一些內建函式、資
料型態、和一些例外處理，再來一章章的主題式介紹相關模組。

這代表如果你從這個手冊的最開始讀起，並在感到無聊時跳到下一個章節，你仍
然可以得到一個對 Python 函式庫所支援的模組與其合理應用的概觀。當然，你
*沒有必要*像是在讀一本小說一樣讀這本手冊——你可以快速瀏覽目錄（在手冊的
最前頭）、或是你可以利用最後面的索引來查詢特定的函式或模組。最後，如果
你享受閱讀一些隨機的主題，你可以選擇一個隨機的數字並開始閱讀（見
"random" 模組) 。不管你想要以什麼順序來閱讀這個手冊，內建函式會是一個
很好的入門，因為手冊中其他章節都預設你已經對這個章節有一定的熟悉程度。

讓我們開始吧！


可用性之標註
============

* 如果出現「適用：Unix」標註，則代表該函式普遍存在於 Unix 系統中，但這
  並不保證其存在於某特定作業系統。

* 如果沒有分別標註的話，有標明「適用：Unix」標註的所有函式也都於 macOS
  、iOS 和 Android 上支援，因其建於 Unix 核心之上。

* 如果可用性標註同時包含最低核心 (Kernel) 版本及最低 libc 版本，則兩項
  條件必須同時符合。例如，標註為 *適用：Linux >= 3.17 與 glibc >=
  2.27* 的功能需要 Linux 3.17 或更新版本以及 glibc 2.27 或更新版本。


WebAssembly 平台
----------------

WebAssembly 平台 "wasm32-emscripten" (Emscripten) 及 "wasm32-wasi"
(WASI) 提供一組 POSIX API 的子集。WebAssembly 執行環境 (runtime) 與瀏
覽器均採用沙盒機制，並限制對主機與外部資源的存取。任何使用到行程
(process)、執行緒 (threading)、網路、訊號 (signal) 或其他形式行程間通
訊 (IPC) 的 Python 標準函式庫模組，皆可能無法使用，或無法像在其他類
Unix 系統上正常運作。檔案 I/O、檔案系統以及與 Unix 權限相關的函式亦有
限制。Emscripten 不允許阻塞式 (blocking) I/O。其他阻塞操作（如
"sleep()"）則會阻塞瀏覽器的事件迴圈 (event loop)。

Python 在 WebAssembly 平台上的特性與行為取決於 Emscripten-SDK 或 WASI-
SDK 的版本、WASM 執行環境（瀏覽器、NodeJS、wasmtime）以及 Python 的編
譯時期 (build time) 旗標。WebAssembly、Emscripten 及 WASI 均為不斷演進
中的標準；某些功能（如網路）未來可能獲得支援。

若要在瀏覽器中使用 Python，使用者應考慮 Pyodide 或 PyScript。PyScript
建構於 Pyodide 之上，而 Pyodide 本身則建構於 CPython 與 Emscripten 之
上。Pyodide 提供存取瀏覽器 JavaScript 與 DOM API 的管道，並透過
JavaScript 的 "XMLHttpRequest" 與 "Fetch" API 提供有限的網路功能。

* 與行程 (process) 相關的 API 皆無法使用，或一律回傳錯誤。這包含建立新
  行程（"fork()"、"execve()"）、等待行程（"waitpid()"）、發送訊號（
  "kill()"）或以其他方式與行程互動的 API。雖然可以引入 (import)
  "subprocess" 模組，但它無法正常運作。

* "socket" 模組雖可使用，但功能受限且行為與其他平台不同。在 Emscripten
  上，socket 一律為非阻塞的 （non-blocking），且需要在伺服器端搭配額外
  的 JavaScript 程式碼與輔助工具來透過 WebSocket 代理 TCP；詳情請參閱
  Emscripten Networking。WASI 快照預覽 1 (snapshot preview 1) 僅允許透
  過現有的檔案描述器 (file descriptor) 使用 socket。

* 部分函式僅為虛設常式 (stub)，它們不執行任何操作，且一律回傳固定的
  (hardcoded) 數值。

* 與檔案描述器 (file descriptor)、檔案權限、檔案所有權及連結相關的函式
  均受限，且不支援某些操作。例如，WASI 不允許使用絕對路徑檔名的符號連
  結 (symlink)。


行動平台
--------

在大多數方面，Android 與 iOS 皆屬於 POSIX 作業系統。檔案 I/O、socket
處理及執行緒 (threading) 的行為均與任何 POSIX 作業系統相同。然而，兩者
仍有幾項重大差異。

* 行動平台僅能以「嵌入 (embedded)」模式使用 Python。這些平台不提供
  Python REPL，也無法使用獨立的可執行檔（如 **python** 或 **pip**）。
  若要在行動應用程式中加入 Python 程式碼，您必須使用 Python 嵌入 API。
  詳情請參閱 在 Android 上使用 Python 與 在 iOS 上使用 Python。

* 子行程 (Subprocess)：

  * 在 Android 上雖可建立子行程 (subprocess)，但 官方並不支援。具體而
    言，Android 不支援 System V IPC API 的任何部分，因此無法使用
    "multiprocessing" 模組。

  * iOS 應用程式無法使用任何形式的子行程、多行程 (multiprocessing) 或
    行程間通訊 (IPC)。若 iOS 應用程式嘗試建立子行程，該發起動作的行程
    將會卡死或崩潰。除了 iOS 專用的 API 外，iOS 應用程式無法得知其他正
    在執行的應用程式，也無法與其進行通訊。

* 行動應用程式修改系統資源（如系統時鐘）的權限有限。這類資源通常 *可供
  讀取* ，但嘗試修改時多半會失敗。

* 主控台 (Console) 輸入與輸出：

  * 在 Android 上，原生的 "stdout" 與 "stderr" 未導向至任何地方，因此
    Python 會安裝自有的串流 (stream)，將訊息重新導向至系統日誌。您可以
    分別在 "python.stdout" 與 "python.stderr" 標籤下查看這些訊息。

  * iOS 應用程式的主控台輸出功能有限。雖然 "stdout" 與 "stderr" *確實
    存在*，且在 Xcode 中執行時可看見寫入其中的內容，但這些內容 *不會*
    記錄在系統日誌中。若使用者提供應用程式日誌作為診斷輔助，其中並不會
    包含任何寫入 "stdout" 或 "stderr" 的細節。

  * 行動應用程式完全沒有可用的 "stdin"。雖然應用程式可以顯示螢幕鍵盤，
    但那是軟體功能，並未連接至 "stdin"。

    因此，涉及主控台操作的 Python 模組（如 "curses" 與 "readline"）在
    行動平台上均無法使用。
