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 上，其来源都适用于密码学用途，不过具体实现因移植版本而异：

• 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

删除一个文件。

os.unlink(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，因为它们在特定移植版本的实现中可能不可用。

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 参数应为非负整数，指定设置的是哪个复制槽位。某个移植版本可能实现多个槽位（槽位 0 始终可用），在这种情况下，终端的输入和输出会在所有已设置的槽位上复制。

如果将 None 作为 stream_object 传入，则取消由 index 给定的槽位上的复制。

该函数返回给定槽位中之前的流类对象。

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

通知 MicroPython REPL：之前通过 os.dupterm() 注册的流类对象上有可用输入。

此函数应由自定义流实现（例如 UART、蓝牙或其他非 USB 的 REPL 流）调用，以告知 REPL 已有输入可供读取。正确使用可确保诸如 Ctrl+C（用于触发 KeyboardInterrupt）之类的特殊字符能被 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、蓝牙及其他非标准 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 移植版本上可用；在 OpenMV Cam 上不存在。