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

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

@@ -35,7 +35,7 @@ jobs:
           platforms: all
 
       - name: Build wheels
-        uses: pypa/cibuildwheel@v3.3.1
+        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.1
+        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.1 → littlefs_python-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: littlefs-python
-Version: 0.17.1
+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.17.1 → 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.1 → littlefs_python-0.18.0}/src/littlefs/__main__.py

@@ -19,14 +19,20 @@ _suffix_map = {
 
 
 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)
-    return LittleFS(
-        context=context,
-        block_size=args.block_size,
-        block_count=block_count,
-        name_max=args.name_max,
-        mount=mount,
-    )
+    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):
@@ -81,6 +87,12 @@ 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()
@@ -144,6 +156,12 @@ def _mount_from_context(parser: argparse.ArgumentParser, args: argparse.Namespac
             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
@@ -251,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")