picoware.system.storage.Storage

class documentation

class Storage:

Constructor: Storage()

Control the storage on a Raspberry Pi Pico device.

Method	`__del__`	Destructor to ensure SD card is unmounted.
Method	`__init__`	Initialize the storage class and mount the SD card.
Method	`copy`	Copy a file or directory from source_path to destination_path.
Method	`deserialize`	Write a JSON object to a file.
Method	`execute_script`	Run a Python file from the storage.
Method	`exists`	Check if a file or directory exists.
Method	`file_close`	Close an open file handle.
Method	`file_copy`	Copy an open file to a new location.
Method	`file_move`	Move an open file to a new location.
Method	`file_open`	Open a file and return the file handle.
Method	`file_read`	Read data from an open file.
Method	`file_readinto`	Read data from an open file into a pre-allocated buffer.
Method	`file_seek`	Seek to a specific position in an open file.
Method	`file_write`	Write data to an open file.
Method	`is_directory`	Check if a path is a directory.
Method	`listdir`	List files in a directory.
Method	`mkdir`	Create a new directory.
Method	`mount`	Mount the SD card.
Method	`mount_vfs`	Mount the SD card as a VFS filesystem.
Method	`move`	Move a file or directory from source_path to destination_path.
Method	`read`	Read and return the contents of a file.
Method	`read_chunked`	Read a chunk of data from a file without loading the entire file.
Method	`read_directory`	Read the contents of a directory and return a list of entries.
Method	`readinto`	Read data from a file into a pre-allocated buffer.
Method	`remove`	Remove a file or directory.
Method	`rename`	Rename a file or directory.
Method	`rmdir`	Remove a directory.
Method	`serialize`	Read a file and return its contents as a JSON object.
Method	`size`	Get the size of a file or directory in bytes.
Method	`unmount`	Unmount the SD card (including VFS if mounted).
Method	`unmount_vfs`	Unmount the VFS filesystem.
Method	`write`	Write data to a file, creating or overwriting as needed.
Class Variable	`__slots__`	Undocumented
Property	`active`	Returns True if the storage is active (mounted).
Property	`vfs_mounted`	Returns True if the VFS is mounted (allows use of open(), __import__, etc.).
Property	`vfs_prefix`	Returns the filesystem path prefix for VFS access.
Instance Variable	`_has_storage`	Undocumented
Instance Variable	`_vfs_mounted`	Undocumented

def __del__(self): ¶

Destructor to ensure SD card is unmounted.

def __init__(self): ¶

Initialize the storage class and mount the SD card.

def copy(self, source_path: str, destination_path: str, bytes_per_chunk: int = 2048) -> bool: ¶

Copy a file or directory from source_path to destination_path.

Parameters
source_path:`str`	The source file or directory path.
destination_path:`str`	The destination file or directory path.
bytes_per_chunk:`int`	Bytes per copy chunk. Defaults to 2048.

Returns
`bool`	True if the copy succeeded, False otherwise.

def deserialize(self, json_dict: dict, file_path: str) -> bool: ¶

Write a JSON object to a file.

Parameters
json_dict:`dict`	The JSON object to write.
file_path:`str`	The path of the file to write.

Returns
`bool`	True if the write succeeded, False otherwise.

def execute_script(self, file_path: str = '/'): ¶

Run a Python file from the storage.

Parameters
file_path:`str`	The path of the script to run. Defaults to "/".

def exists(self, path: str) -> bool: ¶

Check if a file or directory exists.

Parameters
path:`str`	The path to check.

Returns
`bool`	True if the path exists, False otherwise.

def file_close(self, file_obj: FAT32File): ¶

Close an open file handle.

Parameters
file_obj:`FAT32File`	The open file handle to close.

def file_copy(self, source_file: FAT32File, destination_path: str, bytes_per_chunk: int = 2048) -> bool: ¶

Copy an open file to a new location.

Parameters
source_file:`FAT32File`	The open source file handle.
destination_path:`str`	The destination file path.
bytes_per_chunk:`int`	Bytes per copy chunk. Defaults to 2048.

Returns
`bool`	True if the copy succeeded, False otherwise.

def file_move(self, source_file: FAT32File, destination_path: str, bytes_per_chunk: int = 2048) -> bool: ¶

Move an open file to a new location.

Parameters
source_file:`FAT32File`	The open source file handle.
destination_path:`str`	The destination file path.
bytes_per_chunk:`int`	Bytes per move chunk. Defaults to 2048.

Returns
`bool`	True if the move succeeded, False otherwise.

def file_open(self, file_path: str) -> FAT32File: ¶

Open a file and return the file handle.

Parameters
file_path:`str`	The path of the file to open.

Returns
`FAT32File`	The open file handle, or None on failure.

def file_read(self, file_obj: FAT32File, index: int = 0, count: int = 0, decode: bool = True): ¶

Read data from an open file.

Parameters
file_obj:`FAT32File`	The open file handle.
index:`int`	Starting byte position. Defaults to 0.
count:`int`	Number of bytes to read. Defaults to 0.
decode:`bool`	Whether to decode as UTF-8. Defaults to True.

Returns
`str or bytes`	The read data.

def file_readinto(self, file_obj: FAT32File, buffer: bytearray) -> int: ¶

Read data from an open file into a pre-allocated buffer.

Parameters
file_obj:`FAT32File`	The open file handle.
buffer:`bytearray`	The buffer to read into.

Returns
`int`	The number of bytes read.

def file_seek(self, file_obj: FAT32File, position: int) -> bool: ¶

Seek to a specific position in an open file.

Parameters
file_obj:`FAT32File`	The open file handle.
position:`int`	The byte position to seek to.

Returns
`bool`	True if the seek succeeded, False otherwise.

def file_write(self, file_obj: FAT32File, data, mode: str = 'w') -> bool: ¶

Write data to an open file.

Parameters
file_obj:`FAT32File`	The open file handle.
data:`str or bytes`	The data to write.
mode:`str`	Write mode ("w", "a", or "wb"). Defaults to "w".

Returns
`bool`	True if the write succeeded, False otherwise.

def is_directory(self, path: str) -> bool: ¶

Check if a path is a directory.

Parameters
path:`str`	The path to check.

Returns
`bool`	True if the path is a directory, False otherwise.

def listdir(self, path: str = '') -> list[str]: ¶

List files in a directory.

Parameters
path:`str`	Directory path to list. Defaults to "".

Returns
`list[str]`	The filenames in the directory.

def mkdir(self, path: str) -> bool: ¶

Create a new directory.

Parameters
path:`str`	The path of the directory to create.

Returns
`bool`	True if the directory was created, False otherwise.

def mount(self) -> bool: ¶

Mount the SD card.

Returns
`bool`	True if mounted successfully, False otherwise.

def mount_vfs(self, mount_point: str = '/sd') -> bool: ¶

Mount the SD card as a VFS filesystem.

This enables the use of Python's built-in open(), __import__, and os module functions with paths on the SD card.

Example

storage = Storage() storage.mount_vfs("/sd")

with open("/sd/myfile.txt", "r") as f:: content = f.read()

import sys sys.path.append("/sd/picoware/apps") import myapp

Parameters
mount_point:`str`	The mount point path. Defaults to "/sd".

Returns
`bool`	True if mounted successfully, False otherwise.

def move(self, source_path: str, destination_path: str) -> bool: ¶

Move a file or directory from source_path to destination_path.

Parameters
source_path:`str`	The source file or directory path.
destination_path:`str`	The destination file or directory path.

Returns
`bool`	True if the move succeeded, False otherwise.

def read(self, file_path, mode: str = 'r', index: int = 0, count: int = 0): ¶

Read and return the contents of a file.

Parameters
file_path:`str`	The path of the file to read.
mode:`str`	Read mode ("r" for text, otherwise binary). Defaults to "r".
index:`int`	Starting byte position. Defaults to 0.
count:`int`	Number of bytes to read. Defaults to 0.

Returns
`str or bytes`	The file contents.

def read_chunked(self, file_path, start: int = 0, chunk_size: int = 1024) -> bytes: ¶

Read a chunk of data from a file without loading the entire file.

Parameters
file_path:`str`	Path to the file to read.
start:`int`	Starting byte position (offset) in the file. Defaults to 0.
chunk_size:`int`	Number of bytes to read from the start position. Defaults to 1024.

Returns
`bytes`	The chunk of data read from the file.

def read_directory(self, path: str = '') -> list[dict]: ¶

Read the contents of a directory and return a list of entries.

Each entry is a dictionary with keys: filename, size, date, time, attributes, and is_directory.

Parameters
path:`str`	The directory path to read. Defaults to "".

Returns
`list[dict]`	The directory entries, or an empty list on failure.

def readinto(self, file_path, buffer: bytearray) -> int: ¶

Read data from a file into a pre-allocated buffer.

Parameters
file_path:`str`	The path of the file to read.
buffer:`bytearray`	The buffer to read into.

Returns
`int`	The number of bytes read.

def remove(self, file_path: str) -> bool: ¶

Remove a file or directory.

Parameters
file_path:`str`	The path of the file or directory to remove.

Returns
`bool`	True if removed successfully, False otherwise.

def rename(self, old_path: str, new_path: str) -> bool: ¶

Rename a file or directory.

Parameters
old_path:`str`	The current path.
new_path:`str`	The new path.

Returns
`bool`	True if renamed successfully, False otherwise.

def rmdir(self, path: str) -> bool: ¶

Remove a directory.

Parameters
path:`str`	The path of the directory to remove.

Returns
`bool`	True if removed successfully, False otherwise.

def serialize(self, file_path: str) -> dict: ¶

Read a file and return its contents as a JSON object.

Parameters
file_path:`str`	The path of the file to read.

Returns
`dict`	The parsed JSON object, or an empty dict on failure.

def size(self, file_path: str) -> int: ¶

Get the size of a file or directory in bytes.

Parameters
file_path:`str`	The path to measure.

Returns
`int`	The size in bytes.

def unmount(self) -> bool: ¶

Unmount the SD card (including VFS if mounted).

Returns
`bool`	True if unmounted successfully, False otherwise.

def unmount_vfs(self, mount_point: str = '/sd') -> bool: ¶

Unmount the VFS filesystem.

Parameters
mount_point:`str`	The mount point path. Defaults to "/sd".

Returns
`bool`	True if unmounted successfully, False otherwise.

def write(self, file_path, data: str, mode: str = 'w') -> bool: ¶

Write data to a file, creating or overwriting as needed.

Parameters
file_path:`str`	The path of the file to write.
data:`str`	The data to write.
mode:`str`	Write mode ("w" to overwrite, "a" to append). Defaults to "w".

Returns
`bool`	True if the write succeeded, False otherwise.

__slots__: tuple[str, ...] = ¶

Undocumented

@property

active: bool = ¶

Returns True if the storage is active (mounted).

@property

vfs_mounted: bool = ¶

Returns True if the VFS is mounted (allows use of open(), __import__, etc.).

@property

vfs_prefix: str = ¶

Returns the filesystem path prefix for VFS access.

On Cardputer the SD card is exposed at /sdcard via the C POSIX bridge; on all other boards it is mounted at /sd by mount_vfs().

_has_storage: bool = ¶

Undocumented

_vfs_mounted: bool = ¶

Undocumented