charmfix 0.1.0__py3-none-any.whl

charmfix/__init__.py

@@ -0,0 +1,10 @@
+"""charmfix: repair EXIF metadata of Kodak Charmera JPEGs without touching image data."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("charmfix")
+except PackageNotFoundError:  # run from a source tree that was never installed
+    __version__ = "0+unknown"

charmfix/cli.py

@@ -0,0 +1,233 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+from . import __version__
+from .discovery import unreadable_reason
+from .pipeline import DiskFullError, Job, RunOptions, prepare, process_file
+from .report import FileResult, Summary, build_report, write_report
+
+DEFAULT_OUTPUT = Path.home() / "Pictures" / "Kodak Charmera Repaired"
+MACOS_PERMISSION_HINT = (
+    "macOS is blocking access. Allow the app you run charmfix from (Terminal, iTerm, "
+    "VS Code, ...) under System Settings > Privacy & Security > Files and Folders > "
+    "Removable Volumes (or Full Disk Access), then restart that app and try again."
+)
+EXIT_OK, EXIT_FAILURES, EXIT_FATAL, EXIT_INTERRUPTED = 0, 1, 2, 130
+
+log = logging.getLogger("charmfix")
+
+
+class _Progress:
+    """A single status line rewritten on stderr, only when stderr is a terminal."""
+
+    def __init__(self, stream: TextIO, enabled: bool) -> None:
+        self.stream, self.enabled, self.active = stream, enabled, False
+
+    def update(self, text: str) -> None:
+        if self.enabled:
+            self.stream.write("\r\x1b[K" + text[:120])
+            self.stream.flush()
+            self.active = True
+
+    def clear(self) -> None:
+        if self.active:
+            self.stream.write("\r\x1b[K")
+            self.stream.flush()
+            self.active = False
+
+
+class _ProgressAwareHandler(logging.StreamHandler):  # type: ignore[type-arg]
+    def __init__(self, progress: _Progress) -> None:
+        super().__init__(sys.stderr)
+        self.progress = progress
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.progress.clear()
+        super().emit(record)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="charmfix",
+        description="Write copies of Kodak Charmera JPEGs with repaired EXIF metadata. "
+        "Image data is never changed and source files are never modified.",
+    )
+    p.add_argument("input", type=Path, help="folder (e.g. the mounted SD card) or a single JPEG")
+    p.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=DEFAULT_OUTPUT,
+        help=f"output folder (default: {DEFAULT_OUTPUT})",
+    )
+    p.add_argument(
+        "--recursive",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="descend into subfolders (default: yes)",
+    )
+    p.add_argument("-n", "--dry-run", action="store_true", help="analyse only; write no images")
+    p.add_argument("--force", action="store_true", help="overwrite existing output files")
+    p.add_argument("-v", "--verbose", action="store_true", help="log details for every file")
+    p.add_argument("--report", type=Path, help="write a JSON report to this path")
+    p.add_argument(
+        "--no-preserve-structure",
+        dest="preserve_structure",
+        action="store_false",
+        help="put all outputs directly in the output folder",
+    )
+    p.add_argument(
+        "--no-assume-charmera",
+        dest="assume_charmera",
+        action="store_false",
+        help="do not set Make/Model to Kodak/Charmera on files with only a GPEncoder comment",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def _same(a: Path, b: Path) -> bool:
+    """Same file or folder on disk, whatever the spelling (letter case, Unicode form).
+
+    A path that cannot be statted counts as different: nothing can be written there either.
+    """
+    if a == b:
+        return True
+    try:
+        return a.samefile(b)
+    except OSError:
+        return False
+
+
+def _within(path: Path, root: Path) -> bool:
+    """``path`` is ``root`` or lies under it, judged by identity on disk."""
+    return any(_same(p, root) for p in (path, *path.parents))
+
+
+def _refusal(
+    input_path: Path, is_folder: bool, output_root: Path, report_path: Path | None
+) -> str | None:
+    """Why these paths would put a source file at risk (CLI.md source safety), or None."""
+    if is_folder:
+        if _within(output_root, input_path) or _within(input_path, output_root):
+            return "input and output folders must not overlap"
+        if report_path and _within(report_path, input_path):
+            return "the report must not be written inside the input folder"
+    else:
+        if _same(output_root, input_path.parent):
+            return "the output folder must not be the input file's folder"
+        if report_path and _same(report_path, input_path):
+            return "the report must not replace the input file"
+    return None
+
+
+def _log_result(r: FileResult) -> None:
+    if r.status == "failed":
+        log.error("FAILED  %s: %s", r.rel_path, r.error)
+    elif r.status == "partial":
+        log.warning("partial %s: %s", r.rel_path, "; ".join(r.partial_reasons))
+    elif r.warnings:
+        log.warning("%-7s %s: %s", r.status, r.rel_path, "; ".join(r.warnings))
+    else:
+        log.debug("%-7s %s", r.status, r.rel_path)
+    if r.status not in ("skipped", "failed"):
+        log.debug(
+            "  SOF %s, old sizes %s; date %r -> %s (source: %s); identity %s; MakerNote %s",
+            r.sof_size,
+            r.old_sizes,
+            r.raw_date,
+            r.date_written,
+            r.timestamp_source,
+            r.identity,
+            r.makernote,
+        )
+        for change in r.changes:
+            log.debug("  change: %s", change)
+    elif r.reason:
+        log.debug("  reason: %s", r.reason)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    progress = _Progress(sys.stderr, enabled=sys.stderr.isatty() and not args.verbose)
+    handler = _ProgressAwareHandler(progress)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    log.handlers[:] = [handler]
+    log.setLevel(logging.DEBUG if args.verbose else logging.INFO)
+    log.propagate = False
+
+    input_path: Path = args.input.expanduser().resolve()
+    output_root: Path = args.output.expanduser().resolve()
+    if not input_path.exists():
+        log.error("input not found: %s", args.input)
+        return EXIT_FATAL
+    report_path = args.report.expanduser().resolve() if args.report else None
+    is_folder = input_path.is_dir()  # anything else is one file, as in discovery
+    refusal = _refusal(input_path, is_folder, output_root, report_path)
+    if refusal:
+        log.error(refusal)
+        return EXIT_FATAL
+
+    opts = RunOptions(
+        output_root=output_root,
+        recursive=args.recursive,
+        preserve_structure=args.preserve_structure,
+        force=args.force,
+        dry_run=args.dry_run,
+        assume_charmera=args.assume_charmera,
+    )
+    input_root = input_path if is_folder else input_path.parent
+    reason = unreadable_reason(input_root)
+    if reason is not None:
+        log.error("cannot read %s: %s", input_root, reason)
+        if sys.platform == "darwin" and reason == "Operation not permitted":
+            log.error(MACOS_PERMISSION_HINT)
+        return EXIT_FATAL
+
+    summary = Summary()
+    results: list[FileResult] = []
+    exit_code = EXIT_OK
+    try:
+        jobs: list[Job] = prepare(input_path, opts)  # walks the card: Ctrl-C may land here too
+        if not jobs:
+            log.warning("no .jpg/.jpeg files found in %s", input_path)
+        summary.discovered = len(jobs)
+        for i, job in enumerate(jobs, 1):
+            progress.update(f"[{i}/{len(jobs)}] {job.candidate.rel.as_posix()}")
+            r = process_file(job, opts)
+            results.append(r)
+            summary.add(r)
+            _log_result(r)
+    except DiskFullError as exc:
+        summary.stopped = str(exc)
+        log.error("stopping: %s", exc)
+        exit_code = EXIT_FATAL
+    except KeyboardInterrupt:
+        summary.stopped = "interrupted"
+        exit_code = EXIT_INTERRUPTED
+    finally:
+        progress.clear()
+
+    print(summary.render(args.dry_run))
+    if report_path:
+        try:
+            write_report(report_path, build_report(results, summary, opts.report_options()))
+        except OSError as exc:
+            log.error("cannot write the report: %s", exc.strerror or exc.__class__.__name__)
+            if exit_code != EXIT_INTERRUPTED:
+                exit_code = EXIT_FATAL
+    if exit_code == EXIT_OK and summary.failed:
+        exit_code = EXIT_FAILURES
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

charmfix/dates.py

@@ -0,0 +1,54 @@
+"""EXIF date parsing and formatting. Dates are naive local wall-clock times."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+EXIF_FORMAT = "%Y:%m:%d %H:%M:%S"
+
+# Accepts the standard "YYYY:MM:DD HH:MM:SS" and the broken variants seen in the
+# wild, e.g. the Charmera's six-part "YYYY:MM:DD:HH:MM:SS", or "T"/"-" separators.
+_DATE_RE = re.compile(r"^\s*(\d{4})[:\-](\d{2})[:\-](\d{2})[ :T\-](\d{2}):(\d{2}):(\d{2})\s*$")
+_NORMAL_RE = re.compile(r"^\d{4}:\d{2}:\d{2} \d{2}:\d{2}:\d{2}$")
+
+
+def _text(raw: bytes | str) -> str:
+    if isinstance(raw, bytes):
+        raw = raw.decode("ascii", errors="replace")
+    return raw.rstrip("\x00")
+
+
+def normalize(raw: bytes | str | None) -> datetime | None:
+    """Parse an EXIF-ish date string; None for blank, zero or impossible dates."""
+    if raw is None:
+        return None
+    m = _DATE_RE.match(_text(raw))
+    if not m:
+        return None
+    year, month, day, hour, minute, second = (int(g) for g in m.groups())
+    try:
+        return datetime(year, month, day, hour, minute, second)
+    except ValueError:
+        return None
+
+
+def is_normal_form(raw: bytes | str | None) -> bool:
+    """True when the value is already a valid, standard EXIF date string."""
+    if raw is None:
+        return False
+    text = _text(raw)
+    return bool(_NORMAL_RE.match(text)) and normalize(text) is not None
+
+
+def format_exif(dt: datetime) -> str:
+    return dt.strftime(EXIF_FORMAT)
+
+
+def sanity_warning(dt: datetime, now: datetime) -> str | None:
+    """A warning for dates that parse but look implausible; the date is still used."""
+    if dt.year < 2000:
+        return f"capture date {format_exif(dt)} is before 2000 (camera clock not set?)"
+    if dt > now + timedelta(days=1):
+        return f"capture date {format_exif(dt)} is in the future"
+    return None

charmfix/discovery.py

@@ -0,0 +1,85 @@
+"""Find JPEG files under an input folder."""
+
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+JPEG_EXTENSIONS = frozenset({".jpg", ".jpeg"})
+SKIP_DIRS = frozenset({".Trashes", ".Spotlight-V100", ".fseventsd"})
+MAX_FILE_SIZE = 64 * 1024 * 1024
+JPEG_MAGIC = b"\xff\xd8\xff"
+
+
+@dataclass(frozen=True)
+class Candidate:
+    path: Path
+    rel: Path  # relative to the input root
+    skip_reason: str | None = None
+    error: str | None = None
+
+
+def _check(path: Path, rel: Path) -> Candidate:
+    try:
+        st = path.lstat()
+        if stat.S_ISLNK(st.st_mode):
+            return Candidate(path, rel, skip_reason="symlink")
+        if not stat.S_ISREG(st.st_mode):
+            return Candidate(path, rel, skip_reason="not a regular file")
+        if st.st_size > MAX_FILE_SIZE:
+            return Candidate(path, rel, skip_reason="too large")
+        with open(path, "rb") as f:
+            magic = f.read(3)
+    except OSError as exc:
+        return Candidate(path, rel, error=f"cannot read: {exc.strerror or exc.__class__.__name__}")
+    if magic != JPEG_MAGIC:
+        return Candidate(path, rel, skip_reason="not JPEG content")
+    return Candidate(path, rel)
+
+
+def _is_jpeg_name(name: str) -> bool:
+    return not name.startswith("._") and os.path.splitext(name)[1].lower() in JPEG_EXTENSIONS
+
+
+def discover(root: Path, recursive: bool = True) -> Iterator[Candidate]:
+    """Yield every *.jpg/*.jpeg under root in a stable order.
+
+    AppleDouble ``._*`` files and macOS volume system folders are ignored.
+    Symlinked folders are not followed.
+    """
+    if not root.is_dir():  # a single file, or something that is neither (checked below)
+        yield _check(root, Path(root.name))
+        return
+    # os.walk silently skips folders it cannot list unless told otherwise; report them
+    # as failures instead, so an unreadable card never looks like an empty one.
+    errors: list[OSError] = []
+
+    def unreadable() -> Iterator[Candidate]:
+        while errors:
+            exc = errors.pop(0)
+            folder = Path(exc.filename) if exc.filename else root
+            rel = folder.relative_to(root) if folder.is_relative_to(root) else Path(folder.name)
+            reason = exc.strerror or exc.__class__.__name__
+            yield Candidate(folder, rel, error=f"cannot list folder: {reason}")
+
+    for dirpath, dirnames, filenames in os.walk(root, onerror=errors.append, followlinks=False):
+        yield from unreadable()
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS) if recursive else []
+        base = Path(dirpath)
+        for name in sorted(filenames):
+            if _is_jpeg_name(name):
+                path = base / name
+                yield _check(path, path.relative_to(root))
+    yield from unreadable()
+
+
+def unreadable_reason(folder: Path) -> str | None:
+    """Why ``folder`` cannot be listed, or None if it can."""
+    try:
+        with os.scandir(folder):
+            return None
+    except OSError as exc:
+        return exc.strerror or exc.__class__.__name__

charmfix/exif_read.py

@@ -0,0 +1,217 @@
+"""Tolerant TIFF/EXIF reader.
+
+Never raises on malformed input: every problem is skipped and recorded as a
+warning. Values are decoded into plain Python types; the original bytes are
+kept as well.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import Literal
+
+TYPE_SIZES = {1: 1, 2: 1, 3: 2, 4: 4, 5: 8, 6: 1, 7: 1, 8: 2, 9: 4, 10: 8, 11: 4, 12: 8, 13: 4}
+MAX_ENTRIES = 1024
+
+TAG_EXIF_IFD = 0x8769
+TAG_GPS_IFD = 0x8825
+TAG_INTEROP_IFD = 0xA005
+TAG_MAKERNOTE = 0x927C
+TAG_THUMB_OFFSET = 0x0201
+TAG_THUMB_LENGTH = 0x0202
+
+IfdName = Literal["0th", "Exif", "GPS", "Interop", "1st"]
+MakerNoteStatus = Literal["absent", "present", "invalid"]
+
+Value = bytes | tuple[int, ...] | tuple[tuple[int, int], ...] | tuple[float, ...]
+
+
+@dataclass(frozen=True)
+class RawValue:
+    type: int
+    count: int
+    raw: bytes  # value bytes exactly as stored
+    value: Value  # bytes for ASCII/UNDEFINED, otherwise a tuple of numbers/rationals
+
+
+@dataclass
+class ExifData:
+    byte_order: str = ""
+    ifds: dict[str, dict[int, RawValue]] = field(default_factory=dict)
+    thumbnail: bytes | None = None
+    warnings: list[str] = field(default_factory=list)
+    makernote_status: MakerNoteStatus = "absent"
+    duplicate_tags: list[tuple[str, int]] = field(default_factory=list)
+    readable: bool = False
+
+    def get(self, ifd: str, tag: int) -> RawValue | None:
+        return self.ifds.get(ifd, {}).get(tag)
+
+
+def _decode(type_: int, count: int, raw: bytes, bo: str) -> Value:
+    if type_ in (2, 7):
+        return raw
+    if type_ == 1:
+        return tuple(raw)
+    if type_ == 6:
+        return struct.unpack(f"{count}b", raw)
+    fmt = {3: "H", 8: "h", 4: "L", 9: "l", 13: "L", 11: "f", 12: "d"}.get(type_)
+    if fmt is not None:
+        return struct.unpack(f"{bo}{count}{fmt}", raw)
+    # rationals
+    nums = struct.unpack(f"{bo}{count * 2}{'L' if type_ == 5 else 'l'}", raw)
+    return tuple((nums[i], nums[i + 1]) for i in range(0, len(nums), 2))
+
+
+class _Reader:
+    def __init__(self, tiff: bytes) -> None:
+        self.data = tiff
+        self.n = len(tiff)
+        self.result = ExifData()
+        self.visited: set[int] = set()
+        self.bo = ">"
+
+    def warn(self, msg: str) -> None:
+        self.result.warnings.append(msg)
+
+    def u16(self, pos: int) -> int:
+        return int(struct.unpack_from(f"{self.bo}H", self.data, pos)[0])
+
+    def u32(self, pos: int) -> int:
+        return int(struct.unpack_from(f"{self.bo}L", self.data, pos)[0])
+
+    def run(self) -> ExifData:
+        d = self.data
+        if self.n < 8:
+            self.warn("EXIF block too short for a TIFF header")
+            return self.result
+        if d[:4] == b"II*\x00":
+            self.bo, self.result.byte_order = "<", "II"
+        elif d[:4] == b"MM\x00*":
+            self.bo, self.result.byte_order = ">", "MM"
+        else:
+            self.warn("invalid TIFF header in EXIF block")
+            return self.result
+
+        ifd0 = self.read_ifd(self.u32(4), "0th")
+        if ifd0 is None:
+            return self.result
+        self.result.readable = True
+        entries0, next_offset = ifd0
+
+        exif_ptr = self.pointer(entries0, TAG_EXIF_IFD, "0th")
+        if exif_ptr is not None:
+            exif = self.read_ifd(exif_ptr, "Exif")
+            if exif is not None:
+                interop_ptr = self.pointer(exif[0], TAG_INTEROP_IFD, "Exif")
+                if interop_ptr is not None:
+                    self.read_ifd(interop_ptr, "Interop")
+        gps_ptr = self.pointer(entries0, TAG_GPS_IFD, "0th")
+        if gps_ptr is not None:
+            self.read_ifd(gps_ptr, "GPS")
+        if next_offset:
+            ifd1 = self.read_ifd(next_offset, "1st")
+            if ifd1 is not None:
+                self.read_thumbnail(ifd1[0])
+        return self.result
+
+    def pointer(self, entries: dict[int, RawValue], tag: int, ifd: str) -> int | None:
+        rv = entries.get(tag)
+        if rv is None:
+            return None
+        if rv.type not in (4, 13) or rv.count != 1 or not isinstance(rv.value[0], int):
+            self.warn(f"{ifd}: invalid IFD pointer tag 0x{tag:04X}")
+            return None
+        return rv.value[0]
+
+    def read_ifd(self, offset: int, name: str) -> tuple[dict[int, RawValue], int] | None:
+        if offset in self.visited:
+            self.warn(f"{name}: IFD offset {offset} already visited (loop)")
+            return None
+        if offset < 8 or offset + 2 > self.n:
+            self.warn(f"{name}: IFD offset {offset} outside EXIF block")
+            return None
+        self.visited.add(offset)
+        count = self.u16(offset)
+        if count > MAX_ENTRIES:
+            self.warn(f"{name}: implausible entry count {count}")
+            return None
+        avail = (self.n - offset - 2) // 12
+        if count > avail:
+            self.warn(f"{name}: IFD truncated ({count} entries declared, {avail} present)")
+            count = avail
+        entries: dict[int, RawValue] = {}
+        for i in range(count):
+            self.read_entry(offset + 2 + 12 * i, name, entries)
+        self.result.ifds[name] = entries
+        if name != "0th":  # only IFD0 links to another IFD (IFD1); sub-IFD links are ignored
+            return entries, 0
+        next_pos = offset + 2 + 12 * count
+        next_offset = self.u32(next_pos) if next_pos + 4 <= self.n else 0
+        if next_offset and next_offset + 2 > self.n:
+            self.warn(f"{name}: next IFD offset {next_offset} outside EXIF block")
+            next_offset = 0
+        return entries, next_offset
+
+    def read_entry(self, pos: int, ifd: str, entries: dict[int, RawValue]) -> None:
+        tag = self.u16(pos)
+        type_ = self.u16(pos + 2)
+        count = self.u32(pos + 4)
+        is_makernote = ifd == "Exif" and tag == TAG_MAKERNOTE
+
+        def bad(msg: str) -> None:
+            self.warn(f"{ifd}: tag 0x{tag:04X} {msg}; skipped")
+            if is_makernote:
+                self.result.makernote_status = "invalid"
+
+        size_per = TYPE_SIZES.get(type_)
+        if size_per is None:
+            bad(f"has unknown type {type_}")
+            return
+        if count == 0:
+            bad("has count 0")
+            return
+        size = size_per * count
+        if size > self.n:
+            bad(f"declares {size} bytes, more than the EXIF block")
+            return
+        if size <= 4:
+            raw = self.data[pos + 8 : pos + 8 + size]
+        else:
+            value_offset = self.u32(pos + 8)
+            if value_offset + size > self.n:
+                bad(f"value at offset {value_offset} (+{size}) is outside the EXIF block")
+                return
+            raw = self.data[value_offset : value_offset + size]
+        if tag in entries:
+            self.warn(f"{ifd}: duplicate tag 0x{tag:04X}; first value kept")
+            self.result.duplicate_tags.append((ifd, tag))
+            return
+        entries[tag] = RawValue(type_, count, raw, _decode(type_, count, raw, self.bo))
+        if is_makernote:
+            self.result.makernote_status = "present"
+
+    def read_thumbnail(self, entries: dict[int, RawValue]) -> None:
+        off_rv = entries.get(TAG_THUMB_OFFSET)
+        len_rv = entries.get(TAG_THUMB_LENGTH)
+        if off_rv is None or len_rv is None:
+            return
+        off, length = off_rv.value[0], len_rv.value[0]
+        if not isinstance(off, int) or not isinstance(length, int):
+            self.warn("1st: invalid thumbnail pointer")
+            return
+        if length == 0 or off + length > self.n:
+            self.warn(f"1st: thumbnail at offset {off} (+{length}) is outside the EXIF block")
+            return
+        self.result.thumbnail = self.data[off : off + length]
+
+
+def read_exif(tiff: bytes) -> ExifData:
+    """Parse TIFF bytes (the APP1 payload after the 6-byte Exif header)."""
+    try:
+        return _Reader(tiff).run()
+    except Exception as exc:  # defensive: the reader must never crash the pipeline
+        result = ExifData()
+        result.warnings.append(f"EXIF reader error: {exc!r}")
+        return result