""" Virtual filesystem control. MicroPython module: https://docs.micropython.org/en/v1.26.0/library/vfs.html The ``vfs`` module contains functions for creating filesystem objects and mounting/unmounting them in the Virtual Filesystem. Filesystem mounting ------------------- Some ports provide a Virtual Filesystem (VFS) and the ability to mount multiple "real" filesystems within this VFS. Filesystem objects can be mounted at either the root of the VFS, or at a subdirectory that lives in the root. This allows dynamic and flexible configuration of the filesystem that is seen by Python programs. Ports that have this functionality provide the :func:`mount` and :func:`umount` functions, and possibly various filesystem implementations represented by VFS classes. --- Module: 'vfs' on micropython-v1.26.0-rp2-RPI_PICO """ # MCU: {'mpy': 'v6.3', 'build': '', 'ver': '1.26.0', 'arch': 'armv6m', 'version': '1.26.0', 'port': 'rp2', 'board': 'RPI_PICO', 'family': 'micropython', 'board_id': 'RPI_PICO', 'variant': '', 'cpu': 'RP2040'} # Stubber: v1.26.0 from __future__ import annotations from _typeshed import Incomplete from _mpy_shed import _BlockDeviceProtocol from abc import ABC, abstractmethod from typing import List, overload from typing_extensions import Awaitable, TypeAlias, TypeVar def umount(mount_point: Incomplete) -> Incomplete: """ 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. """ ... @overload def mount(fsobj, mount_point: str, *, readonly: bool = False) -> None: """ :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), ...]*. """ ... @overload def mount() -> List[tuple[Incomplete, 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), ...]*. """ ... class VfsLfs2: """ Create a filesystem object that uses the `littlefs v2 filesystem format`_. Storage of the littlefs filesystem is provided by *block_dev*, which must support the :ref:`extended interface `. Objects created by this constructor can be mounted using :func:`mount`. The *mtime* argument enables modification timestamps for files, stored using littlefs attributes. This option can be disabled or enabled differently each mount time and timestamps will only be added or updated if *mtime* is enabled, otherwise the timestamps will remain untouched. Littlefs v2 filesystems without timestamps will work without reformatting and timestamps will be added transparently to existing files once they are opened for writing. When *mtime* is enabled `os.stat` on files without timestamps will return 0 for the timestamp. See :ref:`filesystem` for more information. """ def rename(self, *args, **kwargs) -> Incomplete: ... @staticmethod def mkfs(block_dev: AbstractBlockDev, readsize=32, progsize=32, lookahead=32) -> None: """ Build a Lfs2 filesystem on *block_dev*. ``Note:`` There are reports of littlefs v2 failing in certain situations, for details see `littlefs issue 295`_. """ ... def mount(self, *args, **kwargs) -> Incomplete: ... def statvfs(self, *args, **kwargs) -> Incomplete: ... def rmdir(self, *args, **kwargs) -> Incomplete: ... def stat(self, *args, **kwargs) -> Incomplete: ... def umount(self, *args, **kwargs) -> Incomplete: ... def remove(self, *args, **kwargs) -> Incomplete: ... def mkdir(self, *args, **kwargs) -> Incomplete: ... def open(self, *args, **kwargs) -> Incomplete: ... def ilistdir(self, *args, **kwargs) -> Incomplete: ... def chdir(self, *args, **kwargs) -> Incomplete: ... def getcwd(self, *args, **kwargs) -> Incomplete: ... def __init__(self, block_dev: AbstractBlockDev, readsize=32, progsize=32, lookahead=32, mtime=True) -> None: ... class VfsFat: """ 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`. """ def rename(self, *args, **kwargs) -> Incomplete: ... @staticmethod def mkfs(block_dev: AbstractBlockDev) -> None: """ Build a FAT filesystem on *block_dev*. """ ... def mount(self, *args, **kwargs) -> Incomplete: ... def statvfs(self, *args, **kwargs) -> Incomplete: ... def rmdir(self, *args, **kwargs) -> Incomplete: ... def stat(self, *args, **kwargs) -> Incomplete: ... def umount(self, *args, **kwargs) -> Incomplete: ... def remove(self, *args, **kwargs) -> Incomplete: ... def mkdir(self, *args, **kwargs) -> Incomplete: ... def open(self, *args, **kwargs) -> Incomplete: ... def ilistdir(self, *args, **kwargs) -> Incomplete: ... def chdir(self, *args, **kwargs) -> Incomplete: ... def getcwd(self, *args, **kwargs) -> Incomplete: ... def __init__(self, block_dev: AbstractBlockDev) -> None: ... class AbstractBlockDev: # @abstractmethod @overload def readblocks(self, block_num: int, buf: bytearray) -> bool: ... @abstractmethod @overload def readblocks(self, block_num: int, buf: bytearray, offset: int) -> bool: """ The first form reads aligned, multiples of blocks. Starting at the block given by the index *block_num*, read blocks from the device into *buf* (an array of bytes). The number of blocks to read is given by the length of *buf*, which will be a multiple of the block size. The second form allows reading at arbitrary locations within a block, and arbitrary lengths. Starting at block index *block_num*, and byte offset within that block of *offset*, read bytes from the device into *buf* (an array of bytes). The number of bytes to read is given by the length of *buf*. """ ... @abstractmethod @overload def writeblocks(self, block_num: int, buf: bytes | bytearray, /) -> None: """ The first form writes aligned, multiples of blocks, and requires that the blocks that are written to be first erased (if necessary) by this method. Starting at the block given by the index *block_num*, write blocks from *buf* (an array of bytes) to the device. The number of blocks to write is given by the length of *buf*, which will be a multiple of the block size. The second form allows writing at arbitrary locations within a block, and arbitrary lengths. Only the bytes being written should be changed, and the caller of this method must ensure that the relevant blocks are erased via a prior ``ioctl`` call. Starting at block index *block_num*, and byte offset within that block of *offset*, write bytes from *buf* (an array of bytes) to the device. The number of bytes to write is given by the length of *buf*. Note that implementations must never implicitly erase blocks if the offset argument is specified, even if it is zero. """ @abstractmethod @overload def writeblocks(self, block_num: int, buf: bytes | bytearray, offset: int, /) -> None: """ The first form writes aligned, multiples of blocks, and requires that the blocks that are written to be first erased (if necessary) by this method. Starting at the block given by the index *block_num*, write blocks from *buf* (an array of bytes) to the device. The number of blocks to write is given by the length of *buf*, which will be a multiple of the block size. The second form allows writing at arbitrary locations within a block, and arbitrary lengths. Only the bytes being written should be changed, and the caller of this method must ensure that the relevant blocks are erased via a prior ``ioctl`` call. Starting at block index *block_num*, and byte offset within that block of *offset*, write bytes from *buf* (an array of bytes) to the device. The number of bytes to write is given by the length of *buf*. Note that implementations must never implicitly erase blocks if the offset argument is specified, even if it is zero. """ ... @abstractmethod @overload def ioctl(self, op: int, arg) -> int | None: ... # @abstractmethod @overload def ioctl(self, op: int) -> int | None: """ Control the block device and query its parameters. The operation to perform is given by *op* which is one of the following integers: - 1 -- initialise the device (*arg* is unused) - 2 -- shutdown the device (*arg* is unused) - 3 -- sync the device (*arg* is unused) - 4 -- get a count of the number of blocks, should return an integer (*arg* is unused) - 5 -- get the number of bytes in a block, should return an integer, or ``None`` in which case the default value of 512 is used (*arg* is unused) - 6 -- erase a block, *arg* is the block number to erase As a minimum ``ioctl(4, ...)`` must be intercepted; for littlefs ``ioctl(6, ...)`` must also be intercepted. The need for others is hardware dependent. Prior to any call to ``writeblocks(block, ...)`` littlefs issues ``ioctl(6, block)``. This enables a device driver to erase the block prior to a write if the hardware requires it. Alternatively a driver might intercept ``ioctl(6, block)`` and return 0 (success). In this case the driver assumes responsibility for detecting the need for erasure. Unless otherwise stated ``ioctl(op, arg)`` can return ``None``. Consequently an implementation can ignore unused values of ``op``. Where ``op`` is intercepted, the return value for operations 4 and 5 are as detailed above. Other operations should return 0 on success and non-zero for failure, with the value returned being an ``OSError`` errno code. """ ...