# 簡介

「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`）在行動平台上均無法使用。