storage – Storage management — Adafruit CircuitPython 1 documentation (original) (raw)

The storage provides storage management functionality such as mounting and unmounting which is typically handled by the operating system hosting Python. CircuitPython does not have an OS, so this module provides this functionality directly.

For more information regarding using the storage module, refer to the CircuitPython Essentials Learn guide.

Available on these boards

storage.mount(filesystem: VfsFat, mount_path: str, *, readonly: bool = False) → None

Mounts the given filesystem object at the given path.

This is the CircuitPython analog to the UNIX mount command.

Parameters:

storage.umount(mount: str | VfsFat) → None

Unmounts the given filesystem object or if mount is a path, then unmount the filesystem mounted at that location.

This is the CircuitPython analog to the UNIX umount command.

storage.remount(mount_path: str, readonly: bool = False, *, disable_concurrent_write_protection: bool = False) → None

Remounts the given path with new parameters.

This can always be done from boot.py. After boot, it can only be done when the host computer doesn’t have write access and CircuitPython isn’t currently writing to the filesystem. An exception will be raised if this is the case. Some host OSes allow you to eject a drive which will allow for remounting.

Remounting after USB is active may take a little time because it “ejects” the drive for one query from the host. These queries happen every second or so.

Parameters:

storage.getmount(mount_path: str) → VfsFat

Retrieves the mount object associated with the mount path

storage.erase_filesystem(extended: bool | None = None) → None

Erase and re-create the CIRCUITPY filesystem.

On boards that present USB-visible CIRCUITPY drive (e.g., SAMD21 and SAMD51), then call microcontroller.reset() to restart CircuitPython and have the host computer remount CIRCUITPY.

This function can be called from the REPL when CIRCUITPYhas become corrupted.

Parameters:

extended (bool) – On boards that support dualbank module and the extended parameter, the CIRCUITPY storage can be extended by setting this to True. If this isn’t provided or set to None (default), the existing configuration will be used.

Note

New firmware starts with storage extended. In case of an existing filesystem (e.g. uf2 load), the existing extension setting is preserved.

Warning

All the data on CIRCUITPY will be lost, and CircuitPython will restart on certain boards.

storage.disable_usb_drive() → None

Disable presenting CIRCUITPY as a USB mass storage device. By default, the device is enabled and CIRCUITPY is visible. Can be called in boot.py, before USB is connected.

storage.enable_usb_drive() → None

Enabled presenting CIRCUITPY as a USB mass storage device. By default, the device is enabled and CIRCUITPY is visible, so you do not normally need to call this function. Can be called in boot.py, before USB is connected.

If you enable too many devices at once, you will run out of USB endpoints. The number of available endpoints varies by microcontroller. CircuitPython will go into safe mode after running boot.py to inform you if not enough endpoints are available.

class storage.VfsFat(block_device: circuitpython_typing.BlockDevice)

Create a new VfsFat filesystem around the given block device.

Parameters:

block_device – Block device the the filesystem lives on

label_: str_

The filesystem label, up to 11 case-insensitive bytes. Note that this property can only be set when the device is writable by the microcontroller.

readonly_: bool_

True when the device is mounted as readonly by the microcontroller. This property cannot be changed, use storage.remount instead.

static mkfs(block_device: circuitpython_typing.BlockDevice) → None

Format the block device, deleting any data that may have been there.

Limitations: On SAMD21 builds, mkfs() will raise OSError(22) when attempting to format filesystems larger than 4GB. The extra code to format larger filesystems will not fit on these builds. You can still access larger filesystems, but you will need to format the filesystem on another device.

open(path: str, mode: str) → None

Like builtin open()

ilistdir(path: str) → Iterator[Tuple[AnyStr, int, int, int] | Tuple[AnyStr, int, int]]

Return an iterator whose values describe files and folders withinpath

mkdir(path: str) → None

Like os.mkdir

rmdir(path: str) → None

Like os.rmdir

stat(path: str) → Tuple[int, int, int, int, int, int, int, int, int, int]

Like os.stat

statvfs(path: int) → Tuple[int, int, int, int, int, int, int, int, int, int]

Like os.statvfs

mount(readonly: bool, mkfs: VfsFat) → None

Don’t call this directly, call storage.mount.

umount() → None

Don’t call this directly, call storage.umount.