0
# LittleFS Python
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: littlefs-python
7
- **Language**: Python (with Cython extensions)
8
- **Installation**: `pip install littlefs-python`
9
- **Version**: 0.14.0
10
- **License**: BSD 3-Clause
11

12
## Core Imports
13

14
```python
15
from littlefs import LittleFS
16
```
17

18
For low-level API access:
19

20
```python
21
from littlefs import lfs
22
```
23

24
For error handling:
25

26
```python
27
from littlefs import LittleFSError
28
```
29

30
## Basic Usage
31

32
### High-Level Interface
33

34
```python
35
from littlefs import LittleFS
36

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

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

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

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

52
# Export filesystem image to binary file
53
with open('filesystem.bin', 'wb') as f:
54
    f.write(fs.context.buffer)
55
```
56

57
### Low-Level C-Style API
58

59
```python
60
from littlefs import lfs
61

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

66
# Format and mount
67
lfs.format(fs_obj, cfg)
68
lfs.mount(fs_obj, cfg)
69

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

75
# Export filesystem image
76
with open('filesystem.bin', 'wb') as f:
77
    f.write(cfg.user_context.buffer)
78
```
79

80
## Architecture
81

82
LittleFS Python provides multiple API layers:
83

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

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

91
## Capabilities
92

93
### High-Level Filesystem Interface
94

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

97
```python { .api }
98
class LittleFS:
99
    def __init__(self, context=None, mount=True, **kwargs): ...
100
    def open(self, fname: str, mode="r", **kwargs): ...
101
    def mkdir(self, path: str) -> int: ...
102
    def listdir(self, path=".") -> List[str]: ...
103
    def remove(self, path: str, recursive: bool = False) -> None: ...
104
    def stat(self, path: str) -> LFSStat: ...
105
```
106

107
[High-Level Filesystem](./filesystem.md)
108

109
### Low-Level API
110

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

113
```python { .api }
114
def format(fs: LFSFilesystem, cfg: LFSConfig) -> int: ...
115
def mount(fs: LFSFilesystem, cfg: LFSConfig) -> int: ...
116
def file_open(fs: LFSFilesystem, path: str, flags: str) -> LFSFile: ...
117
def file_read(fs: LFSFilesystem, fh: LFSFile, size: int) -> bytes: ...
118
def mkdir(fs: LFSFilesystem, path: str) -> int: ...
119
```
120

121
[Low-Level API](./low-level-api.md)
122

123
### File and Directory Operations
124

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

127
```python { .api }
128
def file_write(fs: LFSFilesystem, fh: LFSFile, data: bytes) -> int: ...
129
def file_seek(fs: LFSFilesystem, fh: LFSFile, off: int, whence: int) -> int: ...
130
def dir_open(fs: LFSFilesystem, path: str) -> LFSDirectory: ...
131
def getattr(fs: LFSFilesystem, path: str, typ: int) -> bytes: ...
132
```
133

134
[File and Directory Operations](./file-operations.md)
135

136
### Context Classes
137

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

140
```python { .api }
141
class UserContext:
142
    def __init__(self, buffsize: int) -> None: ...
143
    def read(self, cfg: LFSConfig, block: int, off: int, size: int) -> bytearray: ...
144
    def prog(self, cfg: LFSConfig, block: int, off: int, data: bytes) -> int: ...
145

146
class UserContextWinDisk:
147
    def __init__(self, disk_path: str) -> None: ...
148
```
149

150
[Context Classes](./contexts.md)
151

152
### Command-Line Interface
153

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

156
```python { .api }
157
# CLI commands available via 'littlefs-python' executable
158
def create(source: Path, destination: Path, block_size: int, **kwargs): ...
159
def extract(source: Path, destination: Path, block_size: int): ...
160
def list(source: Path, block_size: int): ...
161
```
162

163
[Command-Line Interface](./cli.md)
164

165
## Error Handling
166

167
```python { .api }
168
class LittleFSError(Exception):
169
    class Error(IntEnum):
170
        LFS_ERR_OK = 0
171
        LFS_ERR_IO = -5
172
        LFS_ERR_CORRUPT = -84
173
        LFS_ERR_NOENT = -2
174
        LFS_ERR_EXIST = -17
175
        # ... additional error codes
176
    
177
    def __init__(self, code: int): ...
178
    @property
179
    def name(self) -> str: ...
180
    @property  
181
    def code(self) -> int: ...
182
```
183

184
Common exception mapping for high-level API:
185
- `LFS_ERR_NOENT` → `FileNotFoundError`
186
- `LFS_ERR_ISDIR` → `IsADirectoryError`
187
- `LFS_ERR_EXIST` → `FileExistsError`
188

189
## Types
190

191
```python { .api }
192
class LFSStat(NamedTuple):
193
    """File or directory status information."""
194
    type: int  # LFS_TYPE_REG (1) or LFS_TYPE_DIR (2)
195
    size: int  # Size in bytes
196
    name: str  # Filename
197

198
class LFSFSStat(NamedTuple):
199
    """Filesystem status information."""
200
    disk_version: int
201
    name_max: int
202
    file_max: int
203
    attr_max: int
204
    block_count: int
205
    block_size: int
206

207
class LFSFileFlag(IntFlag):
208
    """File open mode flags."""
209
    rdonly = 1
210
    wronly = 2
211
    rdwr = 3
212
    creat = 0x0100
213
    excl = 0x0200
214
    trunc = 0x0400
215
    append = 0x0800
216
```