ext2py 0.1.0__py3-none-any.whl

ext2py/__init__.py

@@ -0,0 +1,11 @@
+"""ext2py - read-only ext2/ext3/ext4 filesystem reader in pure Python."""
+
+__version__ = "0.1.0"
+
+from ext2py.partitions import Partition, find_partitions, open_fs
+from ext2py.reader import DirEntry, ExtError, ExtFS, Inode, Superblock
+
+__all__ = [
+    "__version__", "ExtFS", "ExtError", "Inode", "DirEntry", "Superblock",
+    "Partition", "find_partitions", "open_fs",
+]

ext2py/__main__.py

@@ -0,0 +1,3 @@
+from ext2py.cli import main
+
+raise SystemExit(main())

ext2py/cli.py

@@ -0,0 +1,115 @@
+"""Command-line entry point for `ext2py` (also `python -m ext2py`)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import sys
+from typing import List, Optional
+
+from ext2py import __version__
+from ext2py.partitions import find_partitions, open_fs
+from ext2py.reader import ExtError, ExtFS
+from ext2py.shell import ExtShell, format_info, format_stat, human_size
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ext2py",
+        description="Read-only ext2/ext3/ext4 filesystem browser. Never writes to the image.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    image = argparse.ArgumentParser(add_help=False)
+    image.add_argument("image", help="filesystem image, disk image or device (e.g. /dev/rdisk4)")
+    where = image.add_mutually_exclusive_group()
+    where.add_argument("-p", "--partition", type=int, metavar="N",
+                       help="use partition N of a partitioned disk (see 'parts')")
+    where.add_argument("--offset", type=int, metavar="BYTES",
+                       help="byte offset of the filesystem within the image")
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.add_parser("shell", parents=[image], help="interactive shell: cd, ls, cat, get ...")
+    sub.add_parser("info", parents=[image], help="show filesystem information")
+    sub.add_parser("parts", help="list partitions of a disk image").add_argument("image")
+    p = sub.add_parser("ls", parents=[image], help="list a directory")
+    p.add_argument("path", nargs="?", default="/")
+    p.add_argument("-l", action="store_true", help="long listing")
+    p.add_argument("-a", action="store_true", help="include hidden entries")
+    p.add_argument("-H", "--human", action="store_true", help="human-readable sizes")
+    p = sub.add_parser("cat", parents=[image], help="print a file to stdout")
+    p.add_argument("path")
+    p = sub.add_parser("stat", parents=[image], help="show inode details")
+    p.add_argument("path")
+    p = sub.add_parser("get", parents=[image], help="copy a file or directory tree out")
+    p.add_argument("path")
+    p.add_argument("dest", nargs="?", default=".")
+    return parser
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "parts":
+        with open(args.image, "rb", buffering=0) as f:
+            parts = find_partitions(f)
+        if not parts:
+            print("no partition table found")
+            return 0
+        for part in parts:
+            print(f"{part.number:>3}  offset={part.offset:<14} size={human_size(part.size):<8} "
+                  f"type={part.type}{'  (linux)' if part.is_linux else ''}  {part.name}")
+        return 0
+
+    with open_fs(args.image, partition=args.partition, offset=args.offset) as fs:
+        if args.command == "shell":
+            ExtShell(fs, label=os.path.basename(args.image)).cmdloop()
+        elif args.command == "info":
+            print("\n".join(format_info(fs)))
+        elif args.command == "ls":
+            flags = "".join(f for f, on in (("l", args.l), ("a", args.a), ("h", args.human)) if on)
+            ExtShell(fs).do_ls(shlex.join(([f"-{flags}"] if flags else []) + [args.path]))
+        elif args.command == "cat":
+            out = sys.stdout.buffer
+            for chunk in fs.iter_read(args.path):
+                out.write(chunk)
+            out.flush()
+        elif args.command == "stat":
+            print("\n".join(format_stat(fs, args.path)))
+        elif args.command == "get":
+            return _get(fs, args.path, args.dest)
+    return 0
+
+
+def _get(fs: ExtFS, path: str, dest: str) -> int:
+    errors = []
+    n = fs.extract(path, dest, on_error=lambda s, e: errors.append((s, e)))
+    for s, e in errors:
+        print(f"ext2py: {s}: {e}", file=sys.stderr)
+    print(f"{n} item(s) copied" + (f", {len(errors)} error(s)" if errors else ""), file=sys.stderr)
+    return 1 if errors else 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        return run(args)
+    except BrokenPipeError:
+        sys.stderr.close()   # e.g. `ext2py cat img /big | head`
+        return 0
+    except KeyboardInterrupt:
+        return 130
+    except (OSError, ExtError) as exc:
+        if isinstance(exc, OSError) and exc.strerror:
+            msg = f"{exc.filename}: {exc.strerror}" if exc.filename else exc.strerror
+        else:
+            msg = str(exc)
+        print(f"ext2py: {msg}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ext2py/partitions.py

@@ -0,0 +1,120 @@
+"""Minimal MBR / GPT partition table parsing, to find ext filesystems on whole disks."""
+
+from __future__ import annotations
+
+import os
+import struct
+import uuid
+from dataclasses import dataclass
+from typing import BinaryIO, List, Optional, Union
+
+from ext2py.reader import EXT_MAGIC, SUPERBLOCK_OFFSET, ExtError, ExtFS, Source
+
+LINUX_FS_GUID = uuid.UUID("0FC63DAF-8483-4772-8E79-3D69D8477DE4")
+_MBR_EXTENDED = (0x05, 0x0F, 0x85)
+_MBR_GPT_PROTECTIVE = 0xEE
+
+
+@dataclass
+class Partition:
+    number: int       # 1-based, as in /dev/sdaN or diskNsN
+    offset: int       # bytes
+    size: int         # bytes
+    type: str         # MBR type byte (hex) or GPT type GUID
+    name: str = ""
+
+    @property
+    def is_linux(self) -> bool:
+        return self.type in ("0x83", str(LINUX_FS_GUID))
+
+
+def _gpt(src: Source, sector: int) -> Optional[List[Partition]]:
+    hdr = src.pread(sector, 92)
+    if hdr[:8] != b"EFI PART":
+        return None
+    entries_lba, count, entry_size = struct.unpack_from("<QII", hdr, 72)
+    if entry_size < 128 or count > 1024:
+        return None
+    table = src.pread(entries_lba * sector, count * entry_size)
+    parts = []
+    for i in range(count):
+        e = table[i * entry_size:(i + 1) * entry_size]
+        type_guid = uuid.UUID(bytes_le=e[:16])
+        if type_guid.int == 0:
+            continue
+        first, last = struct.unpack_from("<QQ", e, 32)
+        name = e[56:128].decode("utf-16-le", "replace").split("\0", 1)[0]
+        parts.append(Partition(i + 1, first * sector, (last - first + 1) * sector, str(type_guid), name))
+    return parts
+
+
+def find_partitions(f: BinaryIO) -> List[Partition]:
+    """Return the partitions on a disk image or device (empty if none found).
+
+    Logical partitions inside MBR extended partitions are not listed.
+    """
+    src = Source(f)
+    try:
+        mbr = src.pread(0, 512)
+    except ExtError:
+        return []
+    for sector in (512, 4096):
+        try:
+            parts = _gpt(src, sector)
+        except ExtError:
+            parts = None
+        if parts is not None:
+            return parts
+    if mbr[510:512] != b"\x55\xaa":
+        return []
+    parts = []
+    for i in range(4):
+        _status, ptype, start, count = struct.unpack_from("<B3xB3xII", mbr, 446 + 16 * i)
+        if ptype == 0 or ptype in _MBR_EXTENDED or ptype == _MBR_GPT_PROTECTIVE or count == 0:
+            continue
+        parts.append(Partition(i + 1, start * 512, count * 512, f"0x{ptype:02x}"))
+    return parts
+
+
+def _has_ext_magic(f: BinaryIO, offset: int) -> bool:
+    try:
+        sb = Source(f, offset).pread(SUPERBLOCK_OFFSET, 64)
+    except ExtError:
+        return False
+    return struct.unpack_from("<H", sb, 56)[0] == EXT_MAGIC
+
+
+def open_fs(
+    path: Union[str, "os.PathLike[str]"],
+    partition: Optional[int] = None,
+    offset: Optional[int] = None,
+) -> ExtFS:
+    """Open an ext filesystem from a bare filesystem image or a partitioned disk.
+
+    With neither ``partition`` nor ``offset``, a bare filesystem is tried
+    first, then the partition table is searched for exactly one ext partition.
+    """
+    f = open(path, "rb", buffering=0)
+    try:
+        if offset is None:
+            if partition is not None:
+                parts = {p.number: p for p in find_partitions(f)}
+                if partition not in parts:
+                    raise ExtError(f"no partition {partition} (found: {sorted(parts) or 'none'})")
+                offset = parts[partition].offset
+            elif _has_ext_magic(f, 0):
+                offset = 0
+            else:
+                found = [p for p in find_partitions(f) if _has_ext_magic(f, p.offset)]
+                if not found:
+                    raise ExtError("no ext2/3/4 filesystem found (not a bare image, no ext partition)")
+                if len(found) > 1:
+                    nums = ", ".join(str(p.number) for p in found)
+                    raise ExtError(f"several ext partitions found ({nums}); pick one with --partition")
+                offset = found[0].offset
+        fs = ExtFS(f, offset)
+    except BaseException:
+        f.close()
+        raise
+    fs._owns_file = True
+    return fs