tessl/pypi-littlefs-python

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

LittleFS Python

Name: tessl/pypi-littlefs-python
Author: tessl

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

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:pypi/littlefs-python@0.14.x
Publish Source: CLI
Badge