os --- 基本的「作業系統」服務

os 模組包含用於檔案系統存取與掛載、終端機重新導向與複製的函式，以及 uname 與 urandom 函式。

一般函式

os.uname() → Tuple[str, str, str, str, str]

回傳一個元組（可能是具名元組），其中包含關於底層機器及／或其作業系統的資訊。此元組有以下五個欄位，依序排列，每個欄位皆為字串：

  • sysname -- 底層系統的名稱

  • nodename -- 網路名稱（可與 sysname 相同）

  • release -- 底層系統的版本

  • version -- MicroPython 版本與建置日期

  • machine -- 底層硬體的識別碼（例如開發板、CPU）

os.urandom(n: int) → bytes

回傳一個含有 n 個隨機位元組的 bytes 物件。在所有支援的 cam 上，其來源皆適用於密碼學用途，不過實作會因 port 而異：

  • STM32 cam（M4、M7、H7、H7+、PT、N6）使用 STM32 硬體 RNG 周邊裝置。

  • i.MX RT1062 cam（RT1060）使用晶片的硬體 TRNG。

  • Alif Ensemble cam（AE3）使用 Secure Enclave 的硬體亂數服務。

  • Arduino Nano 33 BLE Sense 使用 nRF52 硬體 RNG 周邊裝置。

  • Arduino Nano RP2040 Connect 沒有硬體 TRNG；pico-sdk PRNG 會被植入種子，並持續以 RP2040 的晶片內熵源重新混合。

檔案系統存取

os.chdir(path: str) → None

變更目前目錄。

os.getcwd() → str

取得目前目錄。

os.ilistdir(dir: str | None = None) → Iterator[Tuple]

此函式回傳一個迭代器，接著產生對應於它所列示目錄中各項目的元組。若未提供引數，則列示目前目錄，否則列示 dir 所指定的目錄。

這些元組的形式為 (name, type, inode[, size])：

  • name 為字串（若 dir 為 bytes 物件則為 bytes），是該項目的名稱；

  • type 為整數，指定該項目的類型，目錄為 0x4000，一般檔案為 0x8000；

  • inode 為對應於該檔案 inode 的整數，對於沒有此概念的檔案系統可能為 0。

  • size 為整數，是否包含視檔案系統類型而定。對於檔案項目，size 表示檔案的大小，若未知則為 -1。對於目錄項目，其意義目前尚未定義。

os.listdir(dir: str | None = None) → List[str]

若未提供引數，則列示目前目錄。否則列示指定的目錄。

os.mkdir(path: str) → None

建立新目錄。

os.remove(path: str) → None

移除檔案。

移除檔案。這是 remove() 的別名。

os.rmdir(path: str) → None

移除目錄。

os.rename(old_path: str, new_path: str) → None

重新命名檔案。

os.stat(path: str) → Tuple

取得檔案或目錄的狀態。

os.statvfs(path: str) → Tuple

取得檔案系統的狀態。

回傳一個含有檔案系統資訊的元組，依以下順序排列：

  • f_bsize -- 檔案系統區塊大小

  • f_frsize -- 片段大小

  • f_blocks -- 檔案系統大小（以 f_frsize 為單位）

  • f_bfree -- 可用區塊數

  • f_bavail -- 非特權使用者可用的區塊數

  • f_files -- inode 數

  • f_ffree -- 可用 inode 數

  • f_favail -- 非特權使用者可用的 inode 數

  • f_flag -- 掛載旗標

  • f_namemax -- 最大檔名長度

與 inode 相關的參數：f_files、f_ffree、f_favail 以及 f_flag 參數可能回傳 0，因為在特定 port 的實作中它們可能無法取得。

os.sync() → None

同步所有檔案系統。

os.sep: str

檔案系統所使用的路徑元件分隔符號，即字串 '/'。

終端機重新導向與複製

os.dupterm(stream_object: Any, index: int = 0, /) → Any

在指定的類 stream 物件上複製或切換 MicroPython 終端機（亦即 REPL）。stream_object 引數必須是原生串流物件，或衍生自 io.IOBase 並實作 readinto() 與 write() 方法。該串流應處於非阻塞模式，且當沒有可供讀取的資料時 readinto() 應回傳 None。

呼叫此函式後，所有終端機輸出都會在此串流上重複出現，而此串流上任何可用的輸入都會被傳遞至終端機輸入。

index 參數應為非負整數，指定要設定哪一個複製插槽。特定 port 可能實作多個插槽（插槽 0 一律可用），在這種情況下，終端機輸入與輸出會在所有已設定的插槽上複製。

若 stream_object 傳入 None，則會取消由 index 所指定插槽上的複製。

此函式回傳指定插槽中先前的類串流物件。

os.dupterm_notify(obj_in: Any, /) → None

通知 MicroPython REPL，先前透過 os.dupterm() 註冊的類串流物件上有可用輸入。

此函式應由自訂串流實作（例如 UART、Bluetooth 或其他非 USB 的 REPL 串流）呼叫，以告知 REPL 已有輸入可供讀取。正確使用可確保特殊字元（例如用以觸發 KeyboardInterrupt 的 Ctrl+C）能被 REPL 即時處理，使使用者程式碼具備預期的中斷行為。

obj_in 參數會被 os.dupterm_notify() 忽略，但必須提供，以允許從中斷處理常式（例如 UART.irq()）呼叫 dupterm_notify。

範例：

from machine import UART
import os
uart = UART(0)
os.dupterm(uart, 0)
uart.irq(os.dupterm_notify, machine.UART.IRQ_RX)

備註

若未呼叫 dupterm_notify() 函式，來自自訂串流的輸入可能要等到下一次 REPL 輪詢時才會被偵測或處理，這可能延遲 KeyboardInterrupt 或其他控制訊號。對於 UART、Bluetooth 及其他無法保證自動通知的非標準 REPL 連線而言，這一點尤其重要。

檔案系統掛載

以下函式與類別已移至 vfs 模組。它們僅為了向後相容而保留在此模組中，並將在 MicroPython 版本 2 中移除。

os.mount(fsobj: Any, mount_point: str, *, readonly: bool = False) → None

將檔案系統物件 fsobj 掛載至 VFS 中由 mount_point 字串所指定的位置。fsobj 可以是具有 mount() 方法的 VFS 物件，或是區塊裝置。若為區塊裝置，則會自動偵測檔案系統類型（若無法辨識任何檔案系統則引發例外）。mount_point 可為 '/' 以將 fsobj 掛載於根目錄，或 '/<name>' 以將其掛載於根目錄下的子目錄。

若 readonly 為 True，則檔案系統以唯讀方式掛載。

在掛載過程中，會對檔案系統物件呼叫 mount() 方法。

若 mount_point 已被掛載，則會引發 OSError(EPERM)。

os.mount() → List[Tuple[Any, str]]

若呼叫 mount() 時不帶引數，則回傳一個代表所有作用中掛載點的元組清單。

回傳的清單形式為 [(fsobj, mount_point), ...]。

os.umount(mount_point: str | Any) → None

卸載檔案系統。mount_point 可為命名掛載位置的字串，或先前已掛載的檔案系統物件。在卸載過程中，會對檔案系統物件呼叫 umount() 方法。

若找不到 mount_point，則會引發 OSError(EINVAL)。

class os.VfsFat(block_dev: AbstractBlockDev)

建立使用 FAT 檔案系統格式的檔案系統物件。FAT 檔案系統的儲存空間由 block_dev 提供。由此建構函式建立的物件可使用 mount() 掛載。

static mkfs(block_dev: AbstractBlockDev) → None

在 block_dev 上建置 FAT 檔案系統。

class os.VfsPosix(root: str | None = None)

建立一個存取主機 POSIX 檔案系統的檔案系統物件。若指定了 root，則它應為主機檔案系統中的路徑，作為 VfsPosix 物件的根目錄。否則使用主機檔案系統的目前目錄。

備註

VfsPosix 僅在 Unix port 上可用；OpenMV Cam 上並不提供。