:mod:`os` --- basic "operating system" services =============================================== .. module:: os :synopsis: basic "operating system" services The ``os`` module contains functions for filesystem access and mounting, terminal redirection and duplication, and the ``uname`` and ``urandom`` functions. General functions ----------------- .. function:: uname() -> Tuple[str, str, str, str, str] Return a tuple (possibly a named tuple) containing information about the underlying machine and/or its operating system. The tuple has five fields in the following order, each of them being a string: * ``sysname`` -- The name of the underlying system * ``nodename`` -- The network name (can be the same as ``sysname``) * ``release`` -- The version of the underlying system * ``version`` -- The MicroPython version and build date * ``machine`` -- An identifier for the underlying hardware (e.g. board, CPU) .. function:: urandom(n: int) -> bytes Return a bytes object with *n* random bytes. The source is cryptographically suitable on every supported cam, though the implementation varies by port: - **STM32 cams** (M4, M7, H7, H7+, PT, N6) use the STM32 hardware RNG peripheral. - **i.MX RT1062 cams** (RT1060) use the chip's hardware TRNG. - **Alif Ensemble cams** (AE3) use the Secure Enclave's hardware random service. - **Arduino Nano 33 BLE Sense** uses the nRF52 hardware RNG peripheral. - **Arduino Nano RP2040 Connect** has no hardware TRNG; the pico-sdk PRNG is seeded and continuously re-mixed with the RP2040's on-chip entropy sources. Filesystem access ----------------- .. function:: chdir(path: str) -> None Change current directory. .. function:: getcwd() -> str Get the current directory. .. function:: ilistdir(dir: Optional[str] = None) -> Iterator[Tuple] This function returns an iterator which then yields tuples corresponding to the entries in the directory that it is listing. With no argument it lists the current directory, otherwise it lists the directory given by *dir*. The tuples have the form *(name, type, inode[, size])*: - *name* is a string (or bytes if *dir* is a bytes object) and is the name of the entry; - *type* is an integer that specifies the type of the entry, with 0x4000 for directories and 0x8000 for regular files; - *inode* is an integer corresponding to the inode of the file, and may be 0 for filesystems that don't have such a notion. - *size* is an integer that may be included depending on the filesystem type. For file entries, *size* represents the size of the file or -1 if unknown. Its meaning is currently undefined for directory entries. .. function:: listdir(dir: Optional[str] = None) -> List[str] With no argument, list the current directory. Otherwise list the given directory. .. function:: mkdir(path: str) -> None Create a new directory. .. function:: remove(path: str) -> None Remove a file. .. function:: unlink(path: str) -> None Remove a file. This is an alias for :func:`remove`. .. function:: rmdir(path: str) -> None Remove a directory. .. function:: rename(old_path: str, new_path: str) -> None Rename a file. .. function:: stat(path: str) -> Tuple Get the status of a file or directory. .. function:: statvfs(path: str) -> Tuple Get the status of a filesystem. Returns a tuple with the filesystem information in the following order: * ``f_bsize`` -- File system block size * ``f_frsize`` -- Fragment size * ``f_blocks`` -- Size of fs in f_frsize units * ``f_bfree`` -- Number of free blocks * ``f_bavail`` -- Number of free blocks for unprivileged users * ``f_files`` -- Number of inodes * ``f_ffree`` -- Number of free inodes * ``f_favail`` -- Number of free inodes for unprivileged users * ``f_flag`` -- Mount flags * ``f_namemax`` -- Maximum filename length Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_favail`` and the ``f_flag`` parameter may return ``0`` as they can be unavailable in a port-specific implementation. .. function:: sync() -> None Sync all filesystems. .. data:: sep :type: str The path-component separator used by the filesystem, the string ``'/'``. Terminal redirection and duplication ------------------------------------ .. function:: dupterm(stream_object: Any, index: int = 0, /) -> Any Duplicate or switch the MicroPython terminal (the REPL) on the given :std:term:`stream`-like object. The *stream_object* argument must be a native stream object, or derive from :class:`io.IOBase` and implement the ``readinto()`` and ``write()`` methods. The stream should be in non-blocking mode and ``readinto()`` should return ``None`` if there is no data available for reading. After calling this function all terminal output is repeated on this stream, and any input that is available on the stream is passed on to the terminal input. The *index* parameter should be a non-negative integer and specifies which duplication slot is set. A given port may implement more than one slot (slot 0 will always be available) and in that case terminal input and output is duplicated on all the slots that are set. If ``None`` is passed as the *stream_object* then duplication is cancelled on the slot given by *index*. The function returns the previous stream-like object in the given slot. .. function:: dupterm_notify(obj_in: Any, /) -> None Notify the MicroPython REPL that input is available on a stream-like object previously registered via :func:`os.dupterm`. This function should be called by custom stream implementations (e.g., UART, Bluetooth, or other non-USB REPL streams) to inform the REPL that input is ready to be read. Proper use ensures that special characters such as Ctrl+C (used to trigger KeyboardInterrupt) are processed promptly by the REPL, enabling expected interruption behavior for user code. The *obj_in* parameter is ignored by :func:`os.dupterm_notify`, but is required to allow calling dupterm_notify from an interrupt handler such as `UART.irq()`. Example: .. code-block:: python from machine import UART import os uart = UART(0) os.dupterm(uart, 0) uart.irq(os.dupterm_notify, machine.UART.IRQ_RX) .. note:: If the ``dupterm_notify()`` function is not called, input from the custom stream may not be detected or processed until the next REPL poll, potentially delaying KeyboardInterrupts or other control signals. This is especially important for UART, Bluetooth and other non-standard REPL connections, where automatic notification is not guaranteed. Filesystem mounting ------------------- The following functions and classes have been moved to the :mod:`vfs` module. They are provided in this module only for backwards compatibility and will be removed in version 2 of MicroPython. .. function:: mount(fsobj: Any, mount_point: str, *, readonly: bool = False) -> None Mount the filesystem object *fsobj* at the location in the VFS given by the *mount_point* string. *fsobj* can be a VFS object that has a ``mount()`` method, or a block device. If it's a block device then the filesystem type is automatically detected (an exception is raised if no filesystem was recognised). *mount_point* may be ``'/'`` to mount *fsobj* at the root, or ``'/'`` to mount it at a subdirectory under the root. If *readonly* is ``True`` then the filesystem is mounted read-only. During the mount process the method ``mount()`` is called on the filesystem object. Will raise ``OSError(EPERM)`` if *mount_point* is already mounted. .. function:: mount() -> List[Tuple[Any, str]] :noindex: With no arguments to :func:`mount`, return a list of tuples representing all active mountpoints. The returned list has the form *[(fsobj, mount_point), ...]*. .. function:: umount(mount_point: Union[str, Any]) -> None Unmount a filesystem. *mount_point* can be a string naming the mount location, or a previously-mounted filesystem object. During the unmount process the method ``umount()`` is called on the filesystem object. Will raise ``OSError(EINVAL)`` if *mount_point* is not found. .. class:: VfsFat(block_dev: AbstractBlockDev) Create a filesystem object that uses the FAT filesystem format. Storage of the FAT filesystem is provided by *block_dev*. Objects created by this constructor can be mounted using :func:`mount`. .. staticmethod:: mkfs(block_dev: AbstractBlockDev) -> None Build a FAT filesystem on *block_dev*. .. class:: VfsPosix(root: Optional[str] = None) Create a filesystem object that accesses the host POSIX filesystem. If *root* is specified then it should be a path in the host filesystem to use as the root of the ``VfsPosix`` object. Otherwise the current directory of the host filesystem is used. .. note:: ``VfsPosix`` is only available on the Unix port; it is not present on the OpenMV Cam.