Repository files navigation

littlefs-python provides a thin wrapper aroundlittlefs, a filesystem targeted forsmall embedded systems.The wrapper provides a pythonic interface to the filesystem and allows the creation,inspection and modification of the filesystem or individual files.Even if this package usesCython, the goal is not to provide a high performanceimplementation. Cython was chosen as an easy method is offered to generate the bindingand the littlefs library in one step.

Let's create a image ready to transfer to a flash memory using the pythonic interface:

fromlittlefsimportLittleFS# Initialize the File System according to your specificationsfs=LittleFS(block_size=512,block_count=256)# Open a file and write some contentwithfs.open('first-file.txt','w')asfh:fh.write('Some text to begin with\n')# Dump the filesystem content to a filewithopen('FlashMemory.bin','wb')asfh:fh.write(fs.context.buffer)

The same can be done by using the more verbose C-Style API, which closely resembles thesteps which must be performed in C:

fromlittlefsimportlfscfg=lfs.LFSConfig(block_size=512,block_count=256)fs=lfs.LFSFilesystem()# Format and mount the filesystemlfs.format(fs,cfg)lfs.mount(fs,cfg)# Open a file and write some contentfh=lfs.file_open(fs,'first-file.txt','w')lfs.file_write(fs,fh,b'Some text to begin with\n')lfs.file_close(fs,fh)# Dump the filesystem content to a filewithopen('FlashMemory.bin','wb')asfh:fh.write(cfg.user_context.buffer)

Aslittlefs is bundled with the package you will need to install the correct version ofthis package in successfully read or create images for your embedded system. If you startfrom scratch the latest version is recommended.

This is as simple as it can be:

pip install littlefs-python

At the moment wheels (which require no build) are provided for the following platforms,on other platforms the source package is used and a compiler is required:

• Linux: Python 3.7 - 3.13 / x86_64, arm64
• MacOS: Python 3.7 - 3.13 / x86_64, arm64
• Windows: Python 3.7 - 3.13 / 32- & 64-bit

littlefs-python comes bundled with a command-line tool,littlefs-python, that can be used to create and extract littlefs binary images.

$littlefs-python --helpusage: littlefs-python [-h] [--version] {create,extract,list} ...Create, extract and inspect LittleFS filesystem images. Use one of thecommands listed below, the '-h' / '--help' option can be used on each commandto learn more about the usage.optional arguments:  -h, --help            show this help message and exit  --version             show program's version number and exitAvailable Commands:  {create,extract,list}    create              Create LittleFS image from file/directory contents.    extract             Extract LittleFS image contents to a directory.    list                List LittleFS image contents.

To create a littlefs binary image:

#Creates a 1-megabyte"lfs.bin" containing README.rst$littlefs-python create README.rst lfs.bin --fs-size=1mb --block-size=4096#Creates a 1-megabyte"lfs.bin" containing the contents of the examples/ folder$littlefs-python create examples lfs.bin --fs-size=1mb --block-size=4096

To extract the contents of a littlefs binary image:

$littlefs-python extract lfs.bin output/ --block-size=4096

Start by checking out the source repository of littlefs-python:

git clone https://github.com/jrast/littlefs-python.git

The source code for littlefs is included as a submodule which must bechecked out after the clone:

cd <littlefs-python>git submodule update --init

this ensures that the correct version oflittlefs is cloned intothe littlefs folder. As a next step install the dependencies and installthe package:

pip install -r requirements.txtpip install -e .

It's highly recommended to install the package in a virtual environment!

• Test should be run before committing:pytest test
• Mypy is used for typechecking. Run it also on the tests to catch more issues:mypy src test test/lfs
• Mypy stubs can be generated withstubgen src. This will create aout directorycontaining the generated stub files.

NEW (with github deploy action):

• Make sure the master branch is in the state you want it.
• Create a new tag with the correct version number and push the tag to github
• Start the "Build and Deploy Package" workflow for the created tag on github

OUTDATED (without github deploy action):

• Make sure the master branch is in the state you want it.
• Create a tag with the new version number
• Wait until all builds are completed. A new release should be createdautomatically on github.
• Build the source distribution withpython setup.py sdist.
• Download all assets (usingci/download_release_files.py).
• Upload to pypi using twine:twine upload dist/*.