or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdcontexts.mdfile-operations.mdfilesystem.mdindex.mdlow-level-api.md
tile.json

tessl/pypi-littlefs-python

A Python wrapper for LittleFS filesystem designed for embedded systems with minimal RAM and flash requirements

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/littlefs-python@0.14.x

To install, run

npx @tessl/cli install tessl/pypi-littlefs-python@0.14.0

index.mddocs/

LittleFS Python

A comprehensive Python wrapper for LittleFS, a filesystem designed for embedded systems with minimal RAM and flash requirements. Provides both high-level Pythonic interfaces and low-level C-style APIs for creating, inspecting, and modifying LittleFS filesystem images.

Package Information

  • Package Name: littlefs-python
  • Language: Python (with Cython extensions)
  • Installation: pip install littlefs-python
  • Version: 0.14.0
  • License: BSD 3-Clause

Core Imports

from littlefs import LittleFS

For low-level API access:

from littlefs import lfs

For error handling:

from littlefs import LittleFSError

Basic Usage

High-Level Interface

from littlefs import LittleFS

# Create a new filesystem with 128KB capacity
fs = LittleFS(block_size=512, block_count=256)

# File operations using familiar Python syntax
with fs.open('data.txt', 'w') as f:
    f.write('Hello, LittleFS!')

# Directory operations
fs.mkdir('logs')
fs.makedirs('config/app', exist_ok=True)

# List directory contents
files = fs.listdir('/')
print(files)  # ['data.txt', 'logs', 'config']

# Export filesystem image to binary file
with open('filesystem.bin', 'wb') as f:
    f.write(fs.context.buffer)

Low-Level C-Style API

from littlefs import lfs

# Configure and create filesystem objects
cfg = lfs.LFSConfig(block_size=512, block_count=256)
fs_obj = lfs.LFSFilesystem()

# Format and mount
lfs.format(fs_obj, cfg)
lfs.mount(fs_obj, cfg)

# File operations
fh = lfs.file_open(fs_obj, 'data.txt', 'w')
lfs.file_write(fs_obj, fh, b'Hello, LittleFS!')
lfs.file_close(fs_obj, fh)

# Export filesystem image
with open('filesystem.bin', 'wb') as f:
    f.write(cfg.user_context.buffer)

Architecture

LittleFS Python provides multiple API layers:

  • High-Level LittleFS Class: Python-like filesystem interface with automatic error handling and familiar I/O operations
  • Low-Level lfs Module: Direct access to LittleFS C API through Cython bindings
  • Context System: Pluggable storage backends (memory, Windows disk) that handle block-level operations
  • Command-Line Tools: Utilities for creating, extracting, and inspecting LittleFS binary images

The dual API design enables both ease of use for Python developers and fine-grained control for embedded systems development.

Capabilities

High-Level Filesystem Interface

Python-like filesystem operations using the LittleFS class with automatic mounting, familiar file I/O, directory management, and comprehensive error handling.

class LittleFS:
    def __init__(self, context=None, mount=True, **kwargs): ...
    def open(self, fname: str, mode="r", **kwargs): ...
    def mkdir(self, path: str) -> int: ...
    def listdir(self, path=".") -> List[str]: ...
    def remove(self, path: str, recursive: bool = False) -> None: ...
    def stat(self, path: str) -> LFSStat: ...

High-Level Filesystem

Low-Level API

Direct access to LittleFS C API through Cython bindings, providing precise control over filesystem operations, configuration parameters, and block-level access patterns.

def format(fs: LFSFilesystem, cfg: LFSConfig) -> int: ...
def mount(fs: LFSFilesystem, cfg: LFSConfig) -> int: ...
def file_open(fs: LFSFilesystem, path: str, flags: str) -> LFSFile: ...
def file_read(fs: LFSFilesystem, fh: LFSFile, size: int) -> bytes: ...
def mkdir(fs: LFSFilesystem, path: str) -> int: ...

Low-Level API

File and Directory Operations

Comprehensive file I/O operations including reading, writing, seeking, and directory traversal with support for extended attributes and filesystem metadata.

def file_write(fs: LFSFilesystem, fh: LFSFile, data: bytes) -> int: ...
def file_seek(fs: LFSFilesystem, fh: LFSFile, off: int, whence: int) -> int: ...
def dir_open(fs: LFSFilesystem, path: str) -> LFSDirectory: ...
def getattr(fs: LFSFilesystem, path: str, typ: int) -> bytes: ...

File and Directory Operations

Context Classes

Storage backend implementations that handle block-level read, program, erase, and sync operations for different storage targets including memory buffers and Windows disk devices.

class UserContext:
    def __init__(self, buffsize: int) -> None: ...
    def read(self, cfg: LFSConfig, block: int, off: int, size: int) -> bytearray: ...
    def prog(self, cfg: LFSConfig, block: int, off: int, data: bytes) -> int: ...

class UserContextWinDisk:
    def __init__(self, disk_path: str) -> None: ...

Context Classes

Command-Line Interface

Command-line tools for creating LittleFS images from directories, extracting filesystem contents, and inspecting binary images with configurable block sizes and filesystem parameters.

# CLI commands available via 'littlefs-python' executable
def create(source: Path, destination: Path, block_size: int, **kwargs): ...
def extract(source: Path, destination: Path, block_size: int): ...
def list(source: Path, block_size: int): ...

Command-Line Interface

Error Handling

class LittleFSError(Exception):
    class Error(IntEnum):
        LFS_ERR_OK = 0
        LFS_ERR_IO = -5
        LFS_ERR_CORRUPT = -84
        LFS_ERR_NOENT = -2
        LFS_ERR_EXIST = -17
        # ... additional error codes
    
    def __init__(self, code: int): ...
    @property
    def name(self) -> str: ...
    @property  
    def code(self) -> int: ...

Common exception mapping for high-level API:

  • LFS_ERR_NOENT → FileNotFoundError
  • LFS_ERR_ISDIR → IsADirectoryError
  • LFS_ERR_EXIST → FileExistsError

Types

class LFSStat(NamedTuple):
    """File or directory status information."""
    type: int  # LFS_TYPE_REG (1) or LFS_TYPE_DIR (2)
    size: int  # Size in bytes
    name: str  # Filename

class LFSFSStat(NamedTuple):
    """Filesystem status information."""
    disk_version: int
    name_max: int
    file_max: int
    attr_max: int
    block_count: int
    block_size: int

class LFSFileFlag(IntFlag):
    """File open mode flags."""
    rdonly = 1
    wronly = 2
    rdwr = 3
    creat = 0x0100
    excl = 0x0200
    trunc = 0x0400
    append = 0x0800