littlefs-python 0.17.0__tar.gz → 0.18.0__tar.gz

{littlefs_python-0.17.0 → littlefs_python-0.18.0}/.github/workflows/deploy.yml

@@ -35,7 +35,7 @@ jobs:
           platforms: all
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.3.0
+        uses: pypa/cibuildwheel@v3.4.1
 
       - uses: actions/upload-artifact@v6
         with:
@@ -57,7 +57,7 @@ jobs:
           fetch-depth: 0
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.3.0
+        uses: pypa/cibuildwheel@v3.4.1
         env:
           CIBW_BUILD: ${{ matrix.cibw_build }}
           CIBW_SKIP: "pp*"
@@ -119,7 +119,7 @@ jobs:
           pattern: wheels-*
           merge-multiple: true
 
-      - uses: pypa/gh-action-pypi-publish@v1.13.0
+      - uses: pypa/gh-action-pypi-publish@v1.14.0
         with:
           user: __token__
           password: ${{ secrets.pypi_api_token }}

{littlefs_python-0.17.0 → littlefs_python-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: littlefs-python
-Version: 0.17.0
+Version: 0.18.0
 Summary: A python wrapper for littlefs
 Home-page: https://github.com/jrast/littlefs-python
 Author: Jürg Rast

littlefs_python-0.18.0/requirements.txt

@@ -0,0 +1,3 @@
+pytest>=4.0.0
+tox>=3.14.0
+pywin32; sys_platform == "win32"

{littlefs_python-0.17.0 → littlefs_python-0.18.0}/src/littlefs/__init__.py

@@ -58,7 +58,29 @@ if TYPE_CHECKING:
 class LittleFS:
     """Littlefs file system"""
 
-    def __init__(self, context: Optional["UserContext"] = None, mount=True, **kwargs) -> None:
+    def __init__(
+        self,
+        context: Optional["UserContext"] = None,
+        mount=True,
+        filename_encoding: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        filename_encoding : Optional[str]
+            Encoding used to encode/decode filenames passed to and returned by
+            the filesystem. littlefs stores names as opaque byte strings, so this
+            is a free choice. Defaults to :data:`littlefs.lfs.FILENAME_ENCODING`
+            (``"utf-8"``). Set this when reading an image whose names were written
+            with a different encoding (e.g. ``"latin-1"`` or ``"shift-jis"``).
+
+            Note that littlefs's ``name_max`` limit is measured in *encoded
+            bytes*, not characters. With a multi-byte encoding such as UTF-8, a
+            single non-ASCII character consumes 2-4 bytes, so a name can exceed
+            ``name_max`` (default 255) well before it looks long.
+        """
+        self.filename_encoding = filename_encoding or lfs.FILENAME_ENCODING
         self.cfg = lfs.LFSConfig(context=context, **kwargs)
         self.fs = lfs.LFSFilesystem()
 
@@ -204,7 +226,7 @@ class LittleFS:
                 buffering = -1
 
         try:
-            fh = lfs.file_open(self.fs, fname, mode)
+            fh = lfs.file_open(self.fs, fname, mode, self.filename_encoding)
         except LittleFSError as e:
             # Try to map to standard Python exceptions
             if e.code == LittleFSError.Error.LFS_ERR_NOENT:
@@ -251,15 +273,15 @@ class LittleFS:
 
     def getattr(self, path: str, typ: Union[str, bytes, int]) -> bytes:
         typ = _typ_to_uint8(typ)
-        return lfs.getattr(self.fs, path, typ)
+        return lfs.getattr(self.fs, path, typ, self.filename_encoding)
 
     def setattr(self, path: str, typ: Union[str, bytes, int], data: bytes) -> None:
         typ = _typ_to_uint8(typ)
-        lfs.setattr(self.fs, path, typ, data)
+        lfs.setattr(self.fs, path, typ, data, self.filename_encoding)
 
     def removeattr(self, path: str, typ: Union[str, bytes, int]) -> None:
         typ = _typ_to_uint8(typ)
-        lfs.removeattr(self.fs, path, typ)
+        lfs.removeattr(self.fs, path, typ, self.filename_encoding)
 
     def listdir(self, path=".") -> List[str]:
         """List directory content
@@ -274,7 +296,7 @@ class LittleFS:
     def mkdir(self, path: str) -> int:
         """Create a new directory"""
         try:
-            return lfs.mkdir(self.fs, path)
+            return lfs.mkdir(self.fs, path, self.filename_encoding)
         except errors.LittleFSError as e:
             if e.code == LittleFSError.Error.LFS_ERR_EXIST:
                 msg = "[LittleFSError {:d}] Cannot create a file when that file already exists: '{:s}'.".format(
@@ -310,7 +332,7 @@ class LittleFS:
             If ``true`` and ``path`` is a directory, recursively remove all children files/folders.
         """
         try:
-            lfs.remove(self.fs, path)
+            lfs.remove(self.fs, path, self.filename_encoding)
             return
         except errors.LittleFSError as e:
             if e.code == LittleFSError.Error.LFS_ERR_NOENT:
@@ -326,7 +348,7 @@ class LittleFS:
         # Recursively delete the ``path`` directory
         for elem in self.scandir(path):
             self.remove(path + "/" + elem.name, recursive=True)
-        lfs.remove(self.fs, path)
+        lfs.remove(self.fs, path, self.filename_encoding)
 
     def removedirs(self, name):
         """Remove directories recursively
@@ -351,7 +373,7 @@ class LittleFS:
 
     def rename(self, src: str, dst: str) -> int:
         """Rename a file or directory"""
-        return lfs.rename(self.fs, src, dst)
+        return lfs.rename(self.fs, src, dst, self.filename_encoding)
 
     def rmdir(self, path: str) -> int:
         """Remove a directory
@@ -362,17 +384,19 @@ class LittleFS:
 
     def scandir(self, path=".") -> Iterator["LFSStat"]:
         """List directory content"""
-        dh = lfs.dir_open(self.fs, path)
-        info = lfs.dir_read(self.fs, dh)
-        while info:
-            if info.name not in [".", ".."]:
-                yield info
-            info = lfs.dir_read(self.fs, dh)
-        lfs.dir_close(self.fs, dh)
+        dh = lfs.dir_open(self.fs, path, self.filename_encoding)
+        try:
+            info = lfs.dir_read(self.fs, dh, self.filename_encoding)
+            while info:
+                if info.name not in [".", ".."]:
+                    yield info
+                info = lfs.dir_read(self.fs, dh, self.filename_encoding)
+        finally:
+            lfs.dir_close(self.fs, dh)
 
     def stat(self, path: str) -> "LFSStat":
         """Get the status of a file or directory"""
-        return lfs.stat(self.fs, path)
+        return lfs.stat(self.fs, path, self.filename_encoding)
 
     def unlink(self, path: str) -> int:
         """Remove a file or directory

{littlefs_python-0.17.0 → littlefs_python-0.18.0}/src/littlefs/__main__.py

@@ -1,5 +1,6 @@
 import argparse
 from contextlib import suppress
+import os
 from pathlib import Path
 import sys
 import textwrap
@@ -7,7 +8,7 @@ import textwrap
 from littlefs import LittleFS, __version__
 from littlefs.errors import LittleFSError
 from littlefs.repl import LittleFSRepl
-from littlefs.context import UserContextFile
+from littlefs.context import UserContextFile, UserContext
 
 # Dictionary mapping suffixes to their size in bytes
 _suffix_map = {
@@ -17,13 +18,21 @@ _suffix_map = {
 }
 
 
-def _fs_from_args(args: argparse.Namespace, mount=True) -> LittleFS:
-    return LittleFS(
-        block_size=args.block_size,
-        block_count=getattr(args, "block_count", 0),
-        name_max=args.name_max,
-        mount=mount,
-    )
+def _fs_from_args(args: argparse.Namespace, block_count=None, mount=True, context: UserContext = None) -> LittleFS:
+    """Build LittleFS from CLI args. Options name_max, attr_max, file_max are stored in the
+    superblock and must match when mounting an existing image. inline_max is format-relevant
+    (limiting it may improve flash usage)."""
+    block_count = block_count if block_count is not None else getattr(args, "block_count", 0)
+    kwargs = {
+        "block_size": args.block_size,
+        "block_count": block_count,
+        "name_max": args.name_max,
+        "inline_max": args.inline_max,
+        "attr_max": args.attr_max,
+        "file_max": args.file_max,
+        "filename_encoding": getattr(args, "filename_encoding", None),
+    }
+    return LittleFS(context=context, mount=mount, **kwargs)
 
 
 def size_parser(size_str):
@@ -51,6 +60,16 @@ def size_parser(size_str):
     return int(size_str, base)
 
 
+def _walk_all(root):
+    """Recursively yield all paths under root, following symlinks."""
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=True):
+        dirpath = Path(dirpath)
+        for dirname in dirnames:
+            yield dirpath / dirname
+        for filename in filenames:
+            yield dirpath / filename
+
+
 def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
     """Create LittleFS image from file/directory contents."""
     # fs_size OR block_count may be populated; make them consistent.
@@ -68,11 +87,17 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
         print(f"  Image Size:  {args.fs_size:9d}  /  0x{args.fs_size:X}")
         print(f"  Block Count: {args.block_count:9d}")
         print(f"  Name Max:    {args.name_max:9d}")
+        if args.inline_max:
+            print(f"  Inline Max:  {args.inline_max:9d}  /  0x{args.inline_max:X}")
+        if args.attr_max:
+            print(f"  Attr Max:    {args.attr_max:9d}")
+        if args.file_max:
+            print(f"  File Max:    {args.file_max:9d}")
         print(f"  Image:       {args.destination}")
 
     source = Path(args.source).absolute()
     if source.is_dir():
-        sources = source.rglob("*")
+        sources = list(_walk_all(source))
         root = source
     else:
         sources = [source]
@@ -94,21 +119,14 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
     if args.compact:
         if args.verbose:
             print(f"Compacting... {fs.used_block_count} / {args.block_count}")
-        compact_fs = LittleFS(
-            block_size=args.block_size,
-            block_count=fs.used_block_count,
-            name_max=args.name_max,
-        )
-        for root, dirs, files in fs.walk("/"):
-            if not root.endswith("/"):
-                root += "/"
-            for _dir in dirs:
-                compact_fs.makedirs(root + _dir, exist_ok=True)
-            for file in files:
-                path = root + file
-                print(path)
-                with fs.open(path, "rb") as src, compact_fs.open(path, "wb") as dest:
-                    dest.write(src.read())
+        compact_fs = _fs_from_args(args, block_count=fs.used_block_count)
+        for path in sources:
+            rel_path = path.relative_to(root)
+            if path.is_dir():
+                compact_fs.mkdir(rel_path.as_posix())
+            else:
+                with compact_fs.open(rel_path.as_posix(), "wb") as dest:
+                    dest.write(path.read_bytes())
         compact_fs.fs_grow(args.block_count)
         data = compact_fs.context.buffer
         if not args.no_pad:
@@ -121,21 +139,43 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
     return 0
 
 
-def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
-    """List LittleFS image contents."""
-    fs = _fs_from_args(args, mount=False)
-    fs.context.buffer = bytearray(args.source.read_bytes())
+def _mount_from_context(parser: argparse.ArgumentParser, args: argparse.Namespace, context: UserContext) -> LittleFS:
+    # Block count is 0 because we don't know the size of the real image yet, the source file may be compacted (with the create --compact option).
+    fs = _fs_from_args(args, block_count=0, mount=False, context=context)
     fs.mount()
 
     if args.verbose:
-        fs_size = len(fs.context.buffer)
+        input_image_size = context.in_size
+        actual_image_size = fs.block_count * args.block_size
         print("LittleFS Configuration:")
         print(f"  Block Size:  {args.block_size:9d}  /  0x{args.block_size:X}")
-        print(f"  Image Size:  {fs_size:9d}  /  0x{fs_size:X}")
+        if input_image_size != actual_image_size:
+            print(f"  Image Size:  {actual_image_size:9d}  /  0x{actual_image_size:X}")
+            print(f"  Input Image Size (compacted): {input_image_size:9d}  /  0x{input_image_size:X}")
+        else:
+            print(f"  Image Size:  {input_image_size:9d}  /  0x{input_image_size:X}")
         print(f"  Block Count: {fs.block_count:9d}")
         print(f"  Name Max:    {args.name_max:9d}")
+        if args.inline_max:
+            print(f"  Inline Max:  {args.inline_max:9d}  /  0x{args.inline_max:X}")
+        if args.attr_max:
+            print(f"  Attr Max:    {args.attr_max:9d}")
+        if args.file_max:
+            print(f"  File Max:    {args.file_max:9d}")
         print(f"  Image:       {args.source}")
 
+    return fs
+
+
+def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
+    """List LittleFS image contents."""
+    source: Path = args.source
+    if not source.is_file():
+        parser.error(f"Source image '{source}' does not exist.")
+    context = UserContext(buffer=bytearray(source.read_bytes()))
+
+    fs = _mount_from_context(parser, args, context)
+
     for root, dirs, files in fs.walk("/"):
         if not root.endswith("/"):
             root += "/"
@@ -148,18 +188,12 @@ def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
 
 def extract(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
     """Extract LittleFS image contents to a directory."""
-    fs = _fs_from_args(args, mount=False)
-    fs.context.buffer = bytearray(args.source.read_bytes())
-    fs.mount()
+    source: Path = args.source
+    if not source.is_file():
+        parser.error(f"Source image '{source}' does not exist.")
+    context = UserContext(buffer=bytearray(source.read_bytes()))
 
-    if args.verbose:
-        fs_size = len(fs.context.buffer)
-        print("LittleFS Configuration:")
-        print(f"  Block Size:  {args.block_size:9d}  /  0x{args.block_size:X}")
-        print(f"  Image Size:  {fs_size:9d}  /  0x{fs_size:X}")
-        print(f"  Block Count: {fs.block_count:9d}")
-        print(f"  Name Max:    {args.name_max:9d}")
-        print(f"  Image:       {args.source}")
+    fs = _mount_from_context(parser, args, context)
 
     root_dest = args.destination.absolute()
     if not root_dest.exists():
@@ -192,36 +226,19 @@ def extract(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
 
 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.")
+    context = UserContextFile(str(source))  # In repl we want context to be the file itself, so commands will change it
 
-    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()
+            fs = _mount_from_context(parser, args, context)
         except LittleFSError as exc:
             parser.error(f"Failed to mount '{source}': {exc}")
+
+        shell = LittleFSRepl(fs)
+
         shell.cmdloop()
     finally:
         if shell._mounted:
@@ -252,12 +269,41 @@ def get_parser():
 
     common_parser = argparse.ArgumentParser(add_help=False)
     common_parser.add_argument("-v", "--verbose", action="count", default=0)
+    # Stored in superblock; must match when mounting an existing image:
     common_parser.add_argument(
         "--name-max",
         type=size_parser,
         default=255,
         help="LittleFS max file path length. Defaults to LittleFS's default (255).",
     )
+    common_parser.add_argument(
+        "--attr-max",
+        type=int,
+        default=0,
+        help="Max custom attribute size per file. Defaults to LittleFS's default (0 = use library default).",
+    )
+    common_parser.add_argument(
+        "--file-max",
+        type=int,
+        default=0,
+        help="Max number of open files. Defaults to LittleFS's default (0 = use library default).",
+    )
+    # Format option: limiting inline_max may improve flash usage.
+    common_parser.add_argument(
+        "--inline-max",
+        type=size_parser,
+        default=0,
+        help="Max inline file size; 0 = use library default. Limiting can improve flash usage.",
+    )
+    # Host-side encode/decode choice; never stored in the image. The same encoding
+    # must be used to extract an image as was used to create it, otherwise filenames
+    # will fail to decode or come out as mojibake.
+    common_parser.add_argument(
+        "--filename-encoding",
+        default=None,
+        help="Encoding for filenames stored in the image. Defaults to utf-8. "
+        "Use e.g. latin-1 or shift-jis for images whose names use a different encoding.",
+    )
 
     subparsers = parser.add_subparsers(required=True, title="Available Commands", dest="command")
 
@@ -358,10 +404,13 @@ def get_parser():
     return parser
 
 
-def main():
+# Getting argv optionally from the caller to enable call from python (generally for testing, but could be used for other purposes)
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv
     parser = get_parser()
-    parser.parse_known_args(sys.argv[1:])  # Allows for ``littlefs-python --version``
-    args = parser.parse_args(sys.argv[1:])
+    parser.parse_known_args(argv[1:])  # Allows for ``littlefs-python --version``
+    args = parser.parse_args(argv[1:])
     return args.func(parser, args)
 
 

{littlefs_python-0.17.0 → littlefs_python-0.18.0}/src/littlefs/context.py

@@ -10,8 +10,14 @@ if typing.TYPE_CHECKING:
 class UserContext:
     """Basic User Context Implementation"""
 
-    def __init__(self, buffsize: int) -> None:
-        self.buffer = bytearray([0xFF] * buffsize)
+    def __init__(self, buffsize: int = None, buffer: bytearray = None) -> None:
+        if buffer is not None:
+            self.buffer = buffer
+        elif buffsize is not None:
+            self.buffer = bytearray([0xFF] * buffsize)
+        else:
+            raise ValueError("Either buffsize or buffer must be provided")
+        self.in_size = len(self.buffer)
 
     def read(self, cfg: "LFSConfig", block: int, off: int, size: int) -> bytearray:
         """read data
@@ -91,6 +97,7 @@ class UserContextFile(UserContext):
 
         self._path = file_path
         self._fh = open(file_path, mode)
+        self.in_size = os.path.getsize(file_path)
 
     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))
@@ -150,10 +157,11 @@ class UserContextWinDisk(UserContext):
                 "Unable to import 'win32file'. This module is required for Windows-specific functionality. Please ensure you are running on a Windows platform or install 'pywin32' using: 'pip install pywin32'."
             )
         self.device = win32file.CreateFile(
-            disk_path, win32file.GENERIC_READ, win32file.FILE_SHARE_READ, None, win32file.OPEN_EXISTING, 0, None
+            disk_path, win32file.GENERIC_READ | win32file.GENERIC_WRITE, win32file.FILE_SHARE_READ, None, win32file.OPEN_EXISTING, 0, None
         )
         if self.device == win32file.INVALID_HANDLE_VALUE:
             raise IOError("Could not open disk %s" % disk_path)
+        self.in_size = win32file.GetFileSize(self.device)
 
     def read(self, cfg: "LFSConfig", block: int, off: int, size: int) -> bytearray:
         """read data
@@ -214,7 +222,7 @@ class UserContextWinDisk(UserContext):
         start = block * cfg.block_size
 
         win32file.SetFilePointer(self.device, start, win32file.FILE_BEGIN)
-        win32file.WriteFile(self.device, [0xFF] * cfg.block_size)
+        win32file.WriteFile(self.device, b'\xff' * cfg.block_size)
         return 0
 
     def sync(self, cfg: "LFSConfig") -> int: