v0.18.0

v0.18.0

UTF-8 filenames by default

The default filename encoding has changed from ASCII to UTF-8 (littlefs.lfs.FILENAME_ENCODING).

littlefs stores names as opaque byte strings, so the API-level encoding is a free choice. Previously the ASCII default rejected any non-ASCII filename with a UnicodeEncodeError (and decoded directory entries as ASCII as well). Now non-ASCII names — Latin-1, CJK, emoji, etc. — round-trip cleanly through open, stat, listdir/scandir, mkdir, rename, and remove.

This change is backward compatible: ASCII is a strict subset of UTF-8, so all existing filenames encode and decode identically. New regression tests cover Latin-1, CJK, and astral-plane (emoji) filenames.

Thanks to @slash-proc for their first contribution! (PR #168)

Configurable per-instance filename encoding

Building on the UTF-8 default, the filename encoding is now selectable per filesystem instead of relying solely on the process-wide lfs.FILENAME_ENCODING global:

# Read an image whose names were written with a non-UTF-8 codec
fs = LittleFS(..., filename_encoding="shift-jis")

• LittleFS(filename_encoding=...) threads the chosen encoding through every path-handling call (open, stat, listdir/scandir, mkdir, remove, rename, and the *attr methods).
• The low-level lfs.* functions accept an optional filename_encoding argument that falls back to the module global, so existing callers are unaffected.
• Useful for images whose names were written with a non-UTF-8 encoding (e.g. latin-1, shift-jis) that would otherwise mis-decode or raise.

New CLI options

The littlefs-python CLI gained several options on the shared parser, available to the create, extract, list, and repl commands:

• --attr-max — maximum custom attribute size per file.
• --file-max — maximum file size.
• --inline-max — maximum inline file size (limiting this can improve flash usage); 0 uses the library default.
• --filename-encoding — encode/decode image filenames with a non-UTF-8 codec (e.g. latin-1, shift-jis); defaults to UTF-8.

Note the distinction surfaced in the help text and docs:

• --name-max, --attr-max, and --file-max are stored in the image superblock and must match when mounting an existing image.
• --inline-max is a format-time option.
• --filename-encoding is a host-side encode/decode choice that is never stored in the image. You must extract an image with the same --filename-encoding that was used to create it, otherwise filenames will fail to decode or come out as mojibake.

Thanks to @amgross for the additional CLI options! (PR #160)

Bug Fixes

• scandir directory-handle leak: directory iteration is now wrapped in try/finally so the underlying handle is always closed via dir_close, even if a read raises mid-iteration (e.g. a UnicodeDecodeError from a mismatched filename encoding).
• lfs.file_sync return value: now returns the error code, matching its -> int type stub and the behavior of every other file_* function (it was the lone outlier returning None).
• Type stubs: lfs.dir_read is now annotated as returning Optional[LFSStat] (it returns None at end-of-directory).

CI / Dependencies

• Bump pypa/cibuildwheel from 3.3.1 to 3.4.1 (PR #165).
• Bump pypa/gh-action-pypi-publish from 1.13.0 to 1.14.0 (PR #166).

New Contributors

• @slash-proc made their first contribution in PR #168.

Full Changelog: v0.17.1...v0.18.0

v0.17.1

Bug Fixes

• Fix create CLI command not following symlinks when globbing source directory by @skrat in #151
• Remove stray print() in --compact code path that wasn't gated by --verbose by @amgross in #153
• Fix REPL re-executing the previous command when pressing Enter on an empty line by @amgross in #154
• Fix REPL failing to mount compacted images due to incorrect block_count by @amgross in #157
• Fix --compact producing corrupt images due to filesystem walk order differing from on-disk order by @amgross in #159

Internal

• Bump pypa/cibuildwheel from 3.3.0 to 3.3.1 by @dependabot[bot] in #155
• Add option to run CLI tests from Python, and add example test by @amgross in #156
• Add tests for UserContextWinDisk by @amgross in #158

New Contributors

• @skrat made their first contribution in #151

Full Changelog: v0.17.0...v0.17.1

v0.17.0

What's Changed

• Add the LFSConfig .inline_max attribute by @amgross in #148

New Contributors

• @amgross made their first contribution in #148

Full Changelog: v0.16.0...v0.17.0

v0.16.0

What's Changed

• Add repl command to the CLI to interact with an existing littlefs image. By @radrogow in #143

New Contributors

• @radrogow made their first contribution in #143

Full Changelog: v0.15.0...v0.16.0

v0.15.0

What's Changed

• update littlefs core from v2.11.0 to v2.11.2 by @BrianPugh in #141
• Fix compiling in certain environments by including limits.h by @BrianPugh in #139
• Prebuilt wheels for Python 3.14. No longer build prebuilt wheels for Python 3.7. By @BrianPugh in #140

Full Changelog: v0.14.0...v0.15.0

v0.14.0

Features

• Update littlefs 2.11.0 by @BrianPugh in #125

Full Changelog: v0.13.3...v0.14.0

v0.13.3

Bug Fixes

• Update LittleFS core to v2.10.1 -> v2.10.2.

Full Changelog: v0.13.2...v0.13.3

v0.13.2

Bug Fixes

• The CLI list command now has --block-size as required. By @niggowai in #119

New Contributors

• @niggowai made their first contribution in #119

Full Changelog: v0.13.1...v0.13.2

v0.13.1

Bug Fixes

• update littlefs to v2.10.1 by @BrianPugh in #117

Full Changelog: v0.13.0...v0.13.1

v0.13.0

What's Changed

• Update LFS to v2.10.0 by @BrianPugh in #114
• Prebuilt wheels for CPython 3.13 by @BrianPugh in #115

Full Changelog: v0.12.0...v0.13.0