littlefs-python 0.14.0__tar.gz → 0.16.0__tar.gz

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/.github/workflows/deploy.yml

@@ -1,6 +1,13 @@
 name: Build and Deploy Package
 
-on: workflow_dispatch
+on:
+  workflow_dispatch:
+    inputs:
+      upload_to_pypi:
+        description: 'Upload to PyPI after building'
+        required: true
+        default: false
+        type: boolean
 
 jobs:
   build_wheels:
@@ -11,14 +18,15 @@ jobs:
         os: [ubuntu-22.04, macos-13, windows-latest]
 
     env:
-      CIBW_BUILD: "cp37-* cp38-* cp39-* cp310-* cp311-* cp312-* cp313-* pp37-* pp38-* pp39-* pp310-*"
-      CIBW_SKIP: "cp36-* pp* *-win_arm64 *-musllinux_aarch64"
+      CIBW_BUILD: "cp38-* cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*"
+      CIBW_SKIP: "*-win_arm64 *-musllinux_aarch64"
       CIBW_ARCHS_LINUX: "x86_64 i686 aarch64"
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: "recursive"
+          fetch-depth: 0
 
       - name: Setup QEMU # Needed to build aarch64 wheels
         if: runner.os == 'Linux'
@@ -27,9 +35,9 @@ jobs:
           platforms: all
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.23.3
+        uses: pypa/cibuildwheel@v3.2.1
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v5
         with:
           name: wheels-${{ matrix.os }}
           path: ./wheelhouse/*.whl
@@ -43,15 +51,16 @@ jobs:
         cibw_archs: ["arm64"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: "recursive"
+          fetch-depth: 0
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v2.23.3
+        uses: pypa/cibuildwheel@v3.2.1
         env:
           CIBW_BUILD: ${{ matrix.cibw_build }}
-          CIBW_SKIP: "cp36-* pp*"
+          CIBW_SKIP: "pp*"
           CIBW_ARCHS: ${{ matrix.cibw_archs }}
           CIBW_REPAIR_WHEEL_COMMAND: |
             echo "Target delocate archs: {delocate_archs}"
@@ -75,7 +84,7 @@ jobs:
             delocate-listdeps --all {dest_dir}/$WHEEL_SIMPLE_FILENAME
 
             echo "DONE."
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v5
         with:
           name: wheels-macos-arm64
           path: ./wheelhouse/*.whl
@@ -84,16 +93,17 @@ jobs:
     name: Build source distribution
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: "recursive"
+          fetch-depth: 0
 
       - name: Build sdist
         run: |
           pip install build
           python -m build . --sdist
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v5
         with:
           name: wheels-sdist
           path: dist/*.tar.gz
@@ -101,15 +111,15 @@ jobs:
   upload_pypi:
     needs: [build_wheels, build_wheels_macos_arm64, build_sdist]
     runs-on: ubuntu-22.04
-    # if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/')
+    if: ${{ inputs.upload_to_pypi }}
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v6
         with:
           path: dist
           pattern: wheels-*
           merge-multiple: true
 
-      - uses: pypa/gh-action-pypi-publish@v1.12.4
+      - uses: pypa/gh-action-pypi-publish@v1.13.0
         with:
           user: __token__
           password: ${{ secrets.pypi_api_token }}

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/.github/workflows/run-tests.yml

@@ -15,14 +15,14 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-22.04, macos-13, windows-latest]
-        python-version: [3.7, 3.8, 3.9, "3.10", "3.11"]
+        python-version: [3.8, 3.9, "3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: "recursive"
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: littlefs-python
-Version: 0.14.0
+Version: 0.16.0
 Summary: A python wrapper for littlefs
 Home-page: https://github.com/jrast/littlefs-python
 Author: Jürg Rast
@@ -103,6 +103,7 @@ from scratch the latest version is recommended.
 .. csv-table::
     :header: "LittleFS Version", "Package Version", "LittleFS File System Version"
 
+    2.11.2, v0.15.X, 2.0 / 2.1 [#f1]_
     2.11.0, v0.14.X, 2.0 / 2.1 [#f1]_
     2.10.0, v0.13.X, 2.0 / 2.1 [#f1]_
     2.9.0, v0.12.X v0.11.X, 2.0 / 2.1 [#f1]_
@@ -135,7 +136,7 @@ littlefs-python comes bundled with a command-line tool, ``littlefs-python``, tha
 .. code:: console
 
    $ littlefs-python --help
-   usage: littlefs-python [-h] [--version] {create,extract,list} ...
+   usage: littlefs-python [-h] [--version] {create,extract,list,repl} ...
 
    Create, extract and inspect LittleFS filesystem images. Use one of the
    commands listed below, the '-h' / '--help' option can be used on each command
@@ -146,10 +147,11 @@ littlefs-python comes bundled with a command-line tool, ``littlefs-python``, tha
      --version             show program's version number and exit
 
    Available Commands:
-     {create,extract,list}
+     {create,extract,list,repl}
        create              Create LittleFS image from file/directory contents.
        extract             Extract LittleFS image contents to a directory.
        list                List LittleFS image contents.
+       repl                Inspect an existing LittleFS image through an interactive shell.
 
 To create a littlefs binary image:
 
@@ -167,6 +169,17 @@ To extract the contents of a littlefs binary image:
 
    $ littlefs-python extract lfs.bin output/ --block-size=4096
 
+To inspect or debug an existing image without extracting it first you can start a
+simple REPL. It provides shell-like commands such as ``ls``, ``tree``, ``put``, ``get``
+and ``rm`` that operate directly on the image data:
+
+.. code:: console
+
+   $ littlefs-python repl lfs.bin --block-size=4096
+   Mounted remote littlefs.
+   littlefs> ls
+   README.rst
+
 Development Setup
 =================
 

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/README.rst

@@ -70,6 +70,7 @@ from scratch the latest version is recommended.
 .. csv-table::
     :header: "LittleFS Version", "Package Version", "LittleFS File System Version"
 
+    2.11.2, v0.15.X, 2.0 / 2.1 [#f1]_
     2.11.0, v0.14.X, 2.0 / 2.1 [#f1]_
     2.10.0, v0.13.X, 2.0 / 2.1 [#f1]_
     2.9.0, v0.12.X v0.11.X, 2.0 / 2.1 [#f1]_
@@ -102,7 +103,7 @@ littlefs-python comes bundled with a command-line tool, ``littlefs-python``, tha
 .. code:: console
 
    $ littlefs-python --help
-   usage: littlefs-python [-h] [--version] {create,extract,list} ...
+   usage: littlefs-python [-h] [--version] {create,extract,list,repl} ...
 
    Create, extract and inspect LittleFS filesystem images. Use one of the
    commands listed below, the '-h' / '--help' option can be used on each command
@@ -113,10 +114,11 @@ littlefs-python comes bundled with a command-line tool, ``littlefs-python``, tha
      --version             show program's version number and exit
 
    Available Commands:
-     {create,extract,list}
+     {create,extract,list,repl}
        create              Create LittleFS image from file/directory contents.
        extract             Extract LittleFS image contents to a directory.
        list                List LittleFS image contents.
+       repl                Inspect an existing LittleFS image through an interactive shell.
 
 To create a littlefs binary image:
 
@@ -134,6 +136,17 @@ To extract the contents of a littlefs binary image:
 
    $ littlefs-python extract lfs.bin output/ --block-size=4096
 
+To inspect or debug an existing image without extracting it first you can start a
+simple REPL. It provides shell-like commands such as ``ls``, ``tree``, ``put``, ``get``
+and ``rm`` that operate directly on the image data:
+
+.. code:: console
+
+   $ littlefs-python repl lfs.bin --block-size=4096
+   Mounted remote littlefs.
+   littlefs> ls
+   README.rst
+
 Development Setup
 =================
 

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/littlefs/Makefile

@@ -475,6 +475,7 @@ benchmarks-diff: $(BENCH_CSV)
 # rules
 -include $(DEP)
 -include $(TEST_DEP)
+-include $(BENCH_DEP)
 .SUFFIXES:
 .SECONDARY:
 

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/littlefs/README.md

@@ -267,7 +267,11 @@ License Identifiers that are here available: http://spdx.org/licenses/
   to create images of the filesystem on your PC. Check if littlefs will fit
   your needs, create images for a later download to the target memory or
   inspect the content of a binary image of the target memory.
-  
+
+- [littlefs-toy] - A command-line tool for creating and working with littlefs
+  images. Uses syntax similar to tar command for ease of use. Supports working
+  on littlefs images embedded inside another file (firmware image, etc).
+
 - [littlefs2-rust] - A Rust wrapper for littlefs. This project allows you
   to use littlefs in a Rust-friendly API, reaping the benefits of Rust's memory
   safety and other guarantees.
@@ -321,6 +325,7 @@ License Identifiers that are here available: http://spdx.org/licenses/
 [littlefs-js]: https://github.com/geky/littlefs-js
 [littlefs-js-demo]:http://littlefs.geky.net/demo.html
 [littlefs-python]: https://pypi.org/project/littlefs-python/
+[littlefs-toy]: https://github.com/tjko/littlefs-toy
 [littlefs2-rust]: https://crates.io/crates/littlefs2
 [nim-littlefs]: https://github.com/Graveflo/nim-littlefs
 [chamelon]: https://github.com/yomimono/chamelon

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/littlefs/lfs.c

@@ -93,6 +93,7 @@ static int lfs_bd_read(lfs_t *lfs,
             // bypass cache?
             diff = lfs_aligndown(diff, lfs->cfg->read_size);
             int err = lfs->cfg->read(lfs->cfg, block, off, data, diff);
+            LFS_ASSERT(err <= 0);
             if (err) {
                 return err;
             }
@@ -739,6 +740,7 @@ static lfs_stag_t lfs_dir_getslice(lfs_t *lfs, const lfs_mdir_t *dir,
         int err = lfs_bd_read(lfs,
                 NULL, &lfs->rcache, sizeof(ntag),
                 dir->pair[0], off, &ntag, sizeof(ntag));
+        LFS_ASSERT(err <= 0);
         if (err) {
             return err;
         }
@@ -767,6 +769,7 @@ static lfs_stag_t lfs_dir_getslice(lfs_t *lfs, const lfs_mdir_t *dir,
             err = lfs_bd_read(lfs,
                     NULL, &lfs->rcache, diff,
                     dir->pair[0], off+sizeof(tag)+goff, gbuffer, diff);
+            LFS_ASSERT(err <= 0);
             if (err) {
                 return err;
             }
@@ -828,9 +831,6 @@ static int lfs_dir_getread(lfs_t *lfs, const lfs_mdir_t *dir,
                 size -= diff;
                 continue;
             }
-
-            // rcache takes priority
-            diff = lfs_min(diff, rcache->off-off);
         }
 
         // load to cache, first condition can no longer fail
@@ -1282,6 +1282,7 @@ static lfs_stag_t lfs_dir_fetchmatch(lfs_t *lfs,
                     if (err == LFS_ERR_CORRUPT) {
                         break;
                     }
+                    return err;
                 }
 
                 lfs_fcrc_fromle32(&fcrc);
@@ -2267,7 +2268,7 @@ static int lfs_dir_relocatingcommit(lfs_t *lfs, lfs_mdir_t *dir,
         }
     }
 
-    if (dir->erased) {
+    if (dir->erased && dir->count < 0xff) {
         // try to commit
         struct lfs_commit commit = {
             .block = dir->pair[0],
@@ -5225,7 +5226,9 @@ static int lfs_fs_gc_(lfs_t *lfs) {
     }
 
     // try to populate the lookahead buffer, unless it's already full
-    if (lfs->lookahead.size < 8*lfs->cfg->lookahead_size) {
+    if (lfs->lookahead.size < lfs_min(
+            8 * lfs->cfg->lookahead_size,
+            lfs->block_count)) {
         err = lfs_alloc_scan(lfs);
         if (err) {
             return err;

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/src/littlefs/__init__.py

@@ -34,6 +34,7 @@ __all__ = [
     "LittleFS",
     "LittleFSError",
     "UserContext",
+    "UserContextFile",
     "UserContextWinDisk",
     "__LFS_DISK_VERSION__",
     "__LFS_VERSION__",
@@ -48,7 +49,7 @@ except PackageNotFoundError:
     # Package not installed
     pass
 
-from .context import UserContext, UserContextWinDisk
+from .context import UserContext, UserContextFile, UserContextWinDisk
 
 if TYPE_CHECKING:
     from .lfs import LFSStat

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/src/littlefs/__main__.py

@@ -6,6 +6,8 @@ import textwrap
 
 from littlefs import LittleFS, __version__
 from littlefs.errors import LittleFSError
+from littlefs.repl import LittleFSRepl
+from littlefs.context import UserContextFile
 
 # Dictionary mapping suffixes to their size in bytes
 _suffix_map = {
@@ -110,7 +112,7 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
         compact_fs.fs_grow(args.block_count)
         data = compact_fs.context.buffer
         if not args.no_pad:
-            data = data.ljust(args.fs_size, b"\xFF")
+            data = data.ljust(args.fs_size, b"\xff")
     else:
         data = fs.context.buffer
 
@@ -188,6 +190,47 @@ def extract(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
     return 0
 
 
+def repl(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
+    """Inspect an existing LittleFS image through an interactive shell."""
+
+    source: Path = args.source
+    if not source.is_file():
+        parser.error(f"Source image '{source}' does not exist.")
+
+    image_size = source.stat().st_size
+    if not image_size or image_size % args.block_size:
+        parser.error(
+            f"Image size ({image_size} bytes) is not a multiple of the supplied block size ({args.block_size})."
+        )
+
+    block_count = image_size // args.block_size
+    if block_count == 0:
+        parser.error("Image is smaller than a single block; cannot mount.")
+
+    context = UserContextFile(str(source))
+    fs = LittleFS(
+        context=context,
+        block_size=args.block_size,
+        block_count=block_count,
+        name_max=args.name_max,
+        mount=False,
+    )
+
+    shell = LittleFSRepl(fs)
+    try:
+        try:
+            shell.do_mount()
+        except LittleFSError as exc:
+            parser.error(f"Failed to mount '{source}': {exc}")
+        shell.cmdloop()
+    finally:
+        if shell._mounted:
+            with suppress(LittleFSError):
+                fs.unmount()
+
+    return 0
+
+
 def get_parser():
     if sys.argv[0].endswith("__main__.py"):
         prog = f"python -m littlefs"
@@ -299,6 +342,19 @@ def get_parser():
         help="LittleFS block size.",
     )
 
+    parser_repl = add_command(repl)
+    parser_repl.add_argument(
+        "source",
+        type=Path,
+        help="Source LittleFS filesystem binary.",
+    )
+    parser_repl.add_argument(
+        "--block-size",
+        type=size_parser,
+        required=True,
+        help="LittleFS block size.",
+    )
+
     return parser
 
 

{littlefs_python-0.14.0 → littlefs_python-0.16.0}/src/littlefs/context.py

@@ -1,6 +1,7 @@
 import logging
 import typing
 import ctypes
+import os
 
 if typing.TYPE_CHECKING:
     from .lfs import LFSConfig
@@ -78,6 +79,60 @@ class UserContext:
         return 0
 
 
+class UserContextFile(UserContext):
+    """File-backed context using the standard library"""
+
+    def __init__(self, file_path: str, *, create: bool = False) -> None:
+        mode = "r+b"
+        if not os.path.exists(file_path):
+            if not create:
+                raise FileNotFoundError(f"Context file '{file_path}' does not exist")
+            mode = "w+b"
+
+        self._path = file_path
+        self._fh = open(file_path, mode)
+
+    def read(self, cfg: "LFSConfig", block: int, off: int, size: int) -> bytearray:
+        logging.getLogger(__name__).debug("LFS Read : Block: %d, Offset: %d, Size=%d" % (block, off, size))
+        start = block * cfg.block_size + off
+        self._fh.seek(start)
+        data = self._fh.read(size)
+
+        if len(data) < size:
+            data += b"\xff" * (size - len(data))
+
+        return bytearray(data)
+
+    def prog(self, cfg: "LFSConfig", block: int, off: int, data: bytes) -> int:
+        logging.getLogger(__name__).debug("LFS Prog : Block: %d, Offset: %d, Data=%r" % (block, off, data))
+        start = block * cfg.block_size + off
+        self._fh.seek(start)
+        self._fh.write(data)
+        return 0
+
+    def erase(self, cfg: "LFSConfig", block: int) -> int:
+        logging.getLogger(__name__).debug("LFS Erase: Block: %d" % block)
+        start = block * cfg.block_size
+        self._fh.seek(start)
+        self._fh.write(b"\xff" * cfg.block_size)
+        return 0
+
+    def sync(self, cfg: "LFSConfig") -> int:
+        self._fh.flush()
+        os.fsync(self._fh.fileno())
+        return 0
+
+    def close(self) -> None:
+        if not self._fh.closed:
+            self._fh.close()
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+
 try:
     import win32file
 except ImportError: