magicdispel 0.1.0__py3-none-any.whl

magicdispel/__init__.py

@@ -0,0 +1,3 @@
+"""MagicDispel: clean common photo metadata locally, without recompression."""
+
+__version__ = "0.1.0"

magicdispel/__main__.py

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

magicdispel/banner.py

@@ -0,0 +1,81 @@
+"""The MagicDispel logo, shown when the command runs without photos."""
+import os
+import shutil
+import sys
+
+CREDITS = "Designed by VincentC, Powered by VincentC"
+TAGLINE = "MagicDispel, wipe the metadata, keep every pixel!"
+# Letters in the ANSI Shadow style: six rows each, every row the same width.
+LETTERS = {
+    "M": ["███╗   ███╗", "████╗ ████║", "██╔████╔██║", "██║╚██╔╝██║", "██║ ╚═╝ ██║", "╚═╝     ╚═╝"],
+    "A": [" █████╗ ", "██╔══██╗", "███████║", "██╔══██║", "██║  ██║", "╚═╝  ╚═╝"],
+    "G": [" ██████╗ ", "██╔════╝ ", "██║  ███╗", "██║   ██║", "╚██████╔╝", " ╚═════╝ "],
+    "I": ["██╗", "██║", "██║", "██║", "██║", "╚═╝"],
+    "C": [" ██████╗", "██╔════╝", "██║     ", "██║     ", "╚██████╗", " ╚═════╝"],
+    "D": ["██████╗ ", "██╔══██╗", "██║  ██║", "██║  ██║", "██████╔╝", "╚═════╝ "],
+    "S": ["███████╗", "██╔════╝", "███████╗", "╚════██║", "███████║", "╚══════╝"],
+    "P": ["██████╗ ", "██╔══██╗", "██████╔╝", "██╔═══╝ ", "██║     ", "╚═╝     "],
+    "E": ["███████╗", "██╔════╝", "█████╗  ", "██╔══╝  ", "███████╗", "╚══════╝"],
+    "L": ["██╗     ", "██║     ", "██║     ", "██║     ", "███████╗", "╚══════╝"],
+}
+# Magenta through violet and blue to cyan, from the 256-color palette nearly
+# every terminal has; the letters' edges are gray.
+GRADIENT = [201, 165, 129, 93, 57, 63, 69, 75, 81, 87, 51]
+EDGE, DIM, BOLD, RESET = "\x1b[38;5;240m", "\x1b[2m", "\x1b[1m", "\x1b[0m"
+INDENT = "  "
+
+
+def welcome(version, usage, stream=sys.stdout):
+    """The logo, credits and tagline, then `usage`. A terminal gets the logo
+    in color; anything else, such as a file, gets plain text."""
+    if not stream.isatty():
+        return "\n".join(["MagicDispel " + version, CREDITS, TAGLINE, "", usage])
+    color = colors(stream)
+    width = shutil.get_terminal_size((80, 24)).columns
+    lines = logo(["MAGICDISPEL"] if width >= len(INDENT) + 82 else ["MAGIC", "DISPEL"])
+    widest = max(map(len, lines))  # both words share one gradient
+    art = [INDENT + (painted(line, widest) if color else line) for line in lines]
+    style = (lambda code, text: code + text + RESET) if color else (lambda code, text: text)
+    return "\n".join(["", *art, "",
+                      INDENT + style(DIM, CREDITS),
+                      INDENT + style(BOLD, TAGLINE) + "   " + style(DIM, "v" + version),
+                      "", *(INDENT + line for line in usage.splitlines()), ""])
+
+
+def logo(words):
+    """The rows of each word, the words one under the other."""
+    return ["".join(LETTERS[letter][row] for letter in word) for word in words for row in range(6)]
+
+
+def painted(line, width):
+    """A logo row: blocks colored by column along the gradient, edges gray."""
+    out, current = [], None
+    for column, char in enumerate(line):
+        code = ("\x1b[38;5;%dm" % GRADIENT[min(column * len(GRADIENT) // width, len(GRADIENT) - 1)]
+                if char == "█" else EDGE if char != " " else current)
+        if code != current:
+            out.append(code)
+            current = code
+        out.append(char)
+    return "".join(out) + RESET
+
+
+def colors(stream):
+    """Whether to use color: not when NO_COLOR is set or the terminal is dumb.
+    Windows consoles need their escape-sequence support switched on."""
+    if os.environ.get("NO_COLOR") or os.environ.get("TERM") == "dumb":
+        return False
+    return os.name != "nt" or windows_escapes()
+
+
+def windows_escapes():
+    """Switch on escape sequences in the Windows console; whether that worked."""
+    try:
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        handle, mode = kernel32.GetStdHandle(-11), ctypes.c_uint32()  # standard output
+        # ENABLE_VIRTUAL_TERMINAL_PROCESSING
+        return bool(kernel32.GetConsoleMode(handle, ctypes.byref(mode))
+                    and kernel32.SetConsoleMode(handle, mode.value | 0x0004))
+    except (AttributeError, OSError):
+        return False

magicdispel/cli.py

@@ -0,0 +1,87 @@
+"""Command line: type magicdispel, drag photos into the terminal, press Enter."""
+
+import argparse
+import sys
+
+from . import __version__, banner, exiftool
+from .core import clean
+from .errors import UserError
+from .messages import message
+
+
+class Parser(argparse.ArgumentParser):
+    """Report bad arguments in our own words; the help text is our own too."""
+
+    def error(self, detail):
+        print(message("bad_arguments", detail=detail), file=sys.stderr)
+        sys.exit(2)
+
+
+def main(argv=None):
+    parser = Parser(prog="magicdispel", add_help=False)
+    parser.add_argument("-h", "--help", action="store_true")
+    parser.add_argument("--version", action="store_true")
+    parser.add_argument("--check", action="store_true")
+    naming = parser.add_mutually_exclusive_group()
+    naming.add_argument("--anonymous", dest="naming", action="store_const", const="anonymous", default="plain")
+    naming.add_argument("--keep-name", dest="naming", action="store_const", const="original")
+    parser.add_argument("photos", nargs="*")
+    # A path the console cannot show is printed with replacements, not refused.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+    args = parser.parse_args(argv)
+    if args.version:
+        print("magicdispel " + __version__)
+        return 0
+    if args.help:
+        print(message("help", version=__version__))
+        return 0
+    if not (args.photos or args.check):
+        print(banner.welcome(__version__, message("usage")))
+        return 0
+    try:
+        # ExifTool is optional: when present and recent, it double-checks results.
+        path = exiftool.find()
+        found = exiftool.version(path) if path else None
+        second_check = path if exiftool.usable(found) else None
+        if args.check:
+            print(message("ready", version=__version__))
+            print(message(second_check_state(path, found, second_check), exiftool_version=found, exiftool=path))
+        failures = 0
+        for photo in args.photos:
+            try:
+                print(message("cleaned", path=clean(photo, second_check, args.naming)))
+            except Exception as error:  # one photo failing never stops the others
+                failures += 1
+                print(message("failed", photo=photo, reason=explained(error)), file=sys.stderr)
+        if len(args.photos) > 1:
+            print(message("summary", succeeded=len(args.photos) - failures, failed=failures))
+        return 1 if failures else 0
+    except Exception as error:
+        print(message("error", reason=explained(error)), file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print(message("cancelled"), file=sys.stderr)
+        return 130
+
+
+def explained(error):
+    """Our own errors and system errors say what went wrong. Anything else is a
+    bug, or an input no check anticipated; it is reported as unexpected."""
+    if isinstance(error, (UserError, OSError)):
+        return str(error)
+    return message("unexpected_error", detail="%s: %s" % (type(error).__name__, error))
+
+
+def second_check_state(path, found_version, second_check):
+    """Which --check line describes the optional ExifTool second check."""
+    if second_check:
+        return "second_check_on"
+    if found_version:
+        return "second_check_old"
+    return "second_check_unusable" if path else "second_check_off"
+
+
+if __name__ == "__main__":
+    sys.exit(main())

magicdispel/core.py

@@ -0,0 +1,89 @@
+"""Clean one photo: rebuild it, check the result, and save a copy next to it."""
+import errno
+import hashlib
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import exiftool, formats, names, pixels
+from .errors import FormatError, InputError, VerificationError
+
+
+def clean(argument, exiftool_path=None, naming="plain"):
+    """Save a cleaned copy of a photo next to it and return the copy's path.
+
+    The format's module rebuilds the file from what is needed to show it and
+    checks the result on its own; Pillow must decode identical frames where it
+    can; ExifTool, when `exiftool_path` is given, reads it independently.
+    Nothing is saved unless every check passes. `naming` is described in
+    names.candidates.
+    """
+    source = Path(os.path.abspath(os.path.expanduser(argument)))
+    if not source.is_file():
+        raise InputError("not_a_file", path=source)
+    data = source.read_bytes()
+    kind = formats.identify(data)
+    if kind is None:
+        raise InputError("unsupported_format")
+    module = formats.MODULES[kind]
+    rebuilt = module.rebuild(data)
+    try:
+        module.verify(data, rebuilt)
+    except FormatError:
+        # The format's reader could not parse the result back.
+        raise VerificationError("verification_failed", detail="the result cannot be read back")
+    if pixels.decodes(kind):
+        pixels.compare(data, rebuilt, kind)
+    if exiftool_path:
+        exiftool.second_opinion(exiftool_path, rebuilt, kind)
+    if hashlib.sha256(data).digest() != file_digest(source):
+        raise VerificationError("source_changed")
+    suffixes = formats.SUFFIXES[kind]
+    suffix = source.suffix if source.suffix.lower() in suffixes else suffixes[0]
+    return publish(rebuilt, source, suffix, naming)
+
+
+def file_digest(path):
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.digest()
+
+
+def publish(data, source, suffix, naming="plain"):
+    """Write data next to source under a new name; never overwrite anything."""
+    for name in names.candidates(source.stem, suffix, naming):
+        destination = source.with_name(name)
+        try:
+            output = destination.open("xb")
+        except FileExistsError:
+            continue
+        try:
+            with output:
+                output.write(data)
+            clear_attributes(destination)
+            return destination
+        except BaseException:
+            destination.unlink(missing_ok=True)
+            raise
+
+
+def clear_attributes(path):
+    """The copy is written from verified bytes, so it has none of the original's
+    extended attributes, resource forks or alternate streams; clear any the
+    system added to the new file."""
+    if sys.platform == "darwin":
+        result = subprocess.run(["/usr/bin/xattr", "-c", str(path)], capture_output=True)
+        if result.returncode:
+            raise OSError("could not clear extended attributes: "
+                          + result.stderr.decode("utf-8", "replace").strip())
+    elif hasattr(os, "listxattr"):
+        try:
+            for attribute in os.listxattr(path):
+                if attribute.startswith("user."):
+                    os.removexattr(path, attribute)
+        except OSError as error:
+            if error.errno not in (errno.ENOTSUP, errno.EOPNOTSUPP, errno.ENOSYS):
+                raise

magicdispel/errors.py

@@ -0,0 +1,25 @@
+"""Errors shown to the user, worded in messages.py."""
+from .messages import message
+
+
+class UserError(ValueError):
+    """A message key plus values; str() gives the sentence for the user."""
+
+    def __init__(self, key, **values):
+        super().__init__(key, values)
+        self.key, self.values = key, values
+
+    def __str__(self):
+        return message(self.key, **self.values)
+
+
+class InputError(UserError):
+    """The argument is not a file, or not a format MagicDispel handles."""
+
+
+class FormatError(UserError):
+    """The file cannot be rebuilt safely, so nothing is saved."""
+
+
+class VerificationError(UserError):
+    """The rebuilt file failed a check against the original, so nothing is saved."""

magicdispel/exif.py

@@ -0,0 +1,188 @@
+"""The few EXIF fields that change how an image is displayed.
+
+`display_fields` reads only those fields from an EXIF (TIFF-structured) block.
+`build` writes a fresh, minimal block from them, so nothing else in the
+original EXIF can carry over. Reading is lenient: a field that cannot be read
+is treated as absent, as a viewer would.
+"""
+import struct
+from dataclasses import dataclass
+
+# TIFF field types, and the size of one value of each.
+BYTE, ASCII, SHORT, LONG, RATIONAL, UNDEFINED, SRATIONAL, IFD = 1, 2, 3, 4, 5, 7, 10, 13
+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}
+
+ORIENTATION, X_RESOLUTION, Y_RESOLUTION, RESOLUTION_UNIT = 0x0112, 0x011A, 0x011B, 0x0128
+EXIF_POINTER, INTEROP_POINTER, COLOR_SPACE, INTEROP_INDEX = 0x8769, 0xA005, 0xA001, 0x0001
+MAKER_NOTE = 0x927C
+# Apple's maker note: a header, then an IFD whose offsets count from the note's start.
+APPLE_NOTE = b"Apple iOS\0\0\1"
+APPLE_HDR_TAGS = (0x21, 0x30)  # HDR headroom and HDR gain, used to render HDR photos
+
+
+@dataclass(frozen=True)
+class DisplayFields:
+    orientation: int | None = None      # 1-8; how the stored pixels are turned for display
+    resolution: tuple | None = None     # ((x_num, x_den), (y_num, y_den), unit) - print/display size
+    color_space: int | None = None      # 1 = sRGB, 0xFFFF = uncalibrated (see interop_index)
+    interop_index: bytes | None = None  # b"R98" (sRGB) or b"R03" (Adobe RGB) for DCF files
+    apple_hdr: bytes | None = None      # a fresh Apple maker note holding only the HDR values
+
+
+def display_fields(data):
+    """Read the display fields from EXIF data, with or without an Exif\\0\\0 prefix."""
+    if data.startswith(b"Exif\0\0"):
+        data = data[6:]
+    reader = _Reader(data)
+    ifd0 = reader.directory(reader.first_directory())
+    exif_ifd = reader.directory(reader.pointer(ifd0.get(EXIF_POINTER)))
+    interop = reader.directory(reader.pointer(exif_ifd.get(INTEROP_POINTER)))
+    orientation = reader.number(ifd0.get(ORIENTATION), SHORT)
+    x, y = reader.rational(ifd0.get(X_RESOLUTION)), reader.rational(ifd0.get(Y_RESOLUTION))
+    unit = reader.number(ifd0.get(RESOLUTION_UNIT), SHORT) or 2
+    index = reader.text(interop.get(INTEROP_INDEX))
+    note = exif_ifd.get(MAKER_NOTE)
+    return DisplayFields(
+        orientation=orientation if orientation in range(1, 9) else None,
+        resolution=(x, y, unit) if x and y and unit in (1, 2, 3) else None,
+        color_space=reader.number(exif_ifd.get(COLOR_SPACE), SHORT),
+        interop_index=index if index in (b"R98", b"R03") else None,
+        # The standard type is UNDEFINED; some writers (Pillow among them) use BYTE.
+        apple_hdr=apple_hdr_note(note[2]) if note and note[0] in (BYTE, UNDEFINED) else None,
+    )
+
+
+def apple_hdr_note(note):
+    """A new Apple maker note with only the HDR headroom and gain, or None."""
+    if not note.startswith(APPLE_NOTE):
+        return None
+    table = len(APPLE_NOTE) + 2  # after the header and a byte order mark
+    reader = _Reader(note, byte_order=note[len(APPLE_NOTE):table])
+    count = reader.unpack("H", table)
+    values = []
+    for index in range(count[0] if count else 0):
+        entry = reader.unpack("HHII", table + 2 + 12 * index)
+        if entry is None:
+            return None
+        tag, kind, number, offset = entry
+        if tag in APPLE_HDR_TAGS and kind == SRATIONAL and number == 1:
+            value = reader.unpack("ii", offset)
+            if value is None or value[1] == 0:
+                return None
+            values.append((tag, value))
+    if not values:
+        return None
+    # Big-endian, entries in tag order, values right after the empty next-IFD link.
+    header = APPLE_NOTE + b"MM" + struct.pack(">H", len(values))
+    entries = b"".join(struct.pack(">HHII", tag, SRATIONAL, 1, len(header) + 12 * len(values) + 4 + 8 * n)
+                       for n, (tag, _) in enumerate(values))
+    return header + entries + b"\0" * 4 + b"".join(struct.pack(">ii", *value) for _, value in values)
+
+
+def build(fields):
+    """A minimal big-endian EXIF block holding only `fields`, or b"" if empty."""
+    ifd0, exif_ifd, interop = [], [], []
+    if fields.orientation:
+        ifd0.append((ORIENTATION, SHORT, struct.pack(">H", fields.orientation)))
+    if fields.resolution:
+        (x, y, unit) = fields.resolution
+        ifd0 += [(X_RESOLUTION, RATIONAL, struct.pack(">II", *x)),
+                 (Y_RESOLUTION, RATIONAL, struct.pack(">II", *y)),
+                 (RESOLUTION_UNIT, SHORT, struct.pack(">H", unit))]
+    if fields.color_space is not None:
+        exif_ifd.append((COLOR_SPACE, SHORT, struct.pack(">H", fields.color_space)))
+    if fields.apple_hdr:
+        exif_ifd.append((MAKER_NOTE, UNDEFINED, fields.apple_hdr))
+    if fields.interop_index:
+        interop.append((INTEROP_INDEX, ASCII, fields.interop_index + b"\0"))
+    if not (ifd0 or exif_ifd or interop):
+        return b""
+    # Directories are laid out in order: IFD0, Exif IFD, Interop IFD. Pointer
+    # values do not change a directory's size, so sizes are known up front.
+    layout = [ifd0 + ([(EXIF_POINTER, LONG, None)] if exif_ifd or interop else []),
+              exif_ifd + ([(INTEROP_POINTER, LONG, None)] if interop else []),
+              interop]
+    layout = [entries for entries in layout if entries]
+    offsets = [8]
+    for entries in layout[:-1]:
+        offsets.append(offsets[-1] + _directory_size(entries))
+    blocks = []
+    for index, entries in enumerate(layout):
+        pointer = struct.pack(">I", offsets[index + 1]) if index + 1 < len(layout) else None
+        resolved = [(tag, kind, pointer if value is None else value) for tag, kind, value in entries]
+        blocks.append(_directory(resolved, offsets[index]))
+    return b"MM\0*" + struct.pack(">I", 8) + b"".join(blocks)
+
+
+def _directory_size(entries):
+    extra = sum(len(value) + len(value) % 2 for _, _, value in entries
+                if value is not None and len(value) > 4)
+    return 2 + 12 * len(entries) + 4 + extra
+
+
+def _directory(entries, start):
+    entries = sorted(entries)
+    table, extra = struct.pack(">H", len(entries)), b""
+    data_start = start + 2 + 12 * len(entries) + 4
+    for tag, kind, value in entries:
+        count = len(value) // TYPE_SIZES[kind]
+        if len(value) <= 4:
+            table += struct.pack(">HHI", tag, kind, count) + value.ljust(4, b"\0")
+        else:
+            table += struct.pack(">HHII", tag, kind, count, data_start + len(extra))
+            extra += value + b"\0" * (len(value) % 2)
+    return table + struct.pack(">I", 0) + extra
+
+
+class _Reader:
+    """Bounds-checked access to one TIFF-structured block; problems read as absent."""
+
+    def __init__(self, data, byte_order=None):
+        self.data = data
+        self.order = {b"II": "<", b"MM": ">"}.get(data[:2] if byte_order is None else byte_order)
+
+    def unpack(self, fmt, offset):
+        if self.order is None or offset < 0 or offset + struct.calcsize(self.order + fmt) > len(self.data):
+            return None
+        return struct.unpack_from(self.order + fmt, self.data, offset)
+
+    def first_directory(self):
+        header = self.unpack("HI", 2)
+        return header[1] if header and header[0] == 42 else None
+
+    def directory(self, offset):
+        """{tag: (type, count, value bytes)} for one IFD; {} if unreadable."""
+        count = self.unpack("H", offset) if offset else None
+        if not count:
+            return {}
+        entries = {}
+        for index in range(count[0]):
+            entry = self.unpack("HHII", offset + 2 + 12 * index)
+            if entry is None:
+                return {}
+            tag, kind, number, value = entry
+            size = TYPE_SIZES.get(kind, 0) * number
+            start = offset + 2 + 12 * index + 8 if size <= 4 else value
+            if not size or start + size > len(self.data):
+                continue
+            entries[tag] = (kind, number, self.data[start:start + size])
+        return entries
+
+    def number(self, entry, kind):
+        if entry is None or entry[0] != kind or entry[1] != 1:
+            return None
+        return struct.unpack(self.order + {SHORT: "H", LONG: "I"}[kind], entry[2])[0]
+
+    def pointer(self, entry):
+        if entry is not None and entry[0] == IFD:
+            entry = (LONG,) + entry[1:]
+        return self.number(entry, LONG)
+
+    def rational(self, entry):
+        if entry is None or entry[0] != RATIONAL or entry[1] != 1:
+            return None
+        numerator, denominator = struct.unpack(self.order + "II", entry[2])
+        return (numerator, denominator) if numerator and denominator else None
+
+    def text(self, entry):
+        return entry[2].rstrip(b"\0") if entry and entry[0] == ASCII else None

magicdispel/exiftool.py

@@ -0,0 +1,147 @@
+"""ExifTool as an optional second opinion.
+
+When ExifTool 12.73 or newer is installed, every rebuilt file is read by it
+before being saved. Any warning, any field outside the display allowlist and
+any data ExifTool cannot identify stops the save. ExifTool reads the result
+from a pipe: no file is written, and no path, which Windows would pass in its
+legacy code page and ExifTool might misread, is involved.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+from . import xmp
+from .errors import UserError, VerificationError
+
+# Display fields a clean file may hold, as ExifTool names them. TIFF keeps its
+# decoding tags in the same EXIF group.
+DISPLAY_EXIF = {
+    "Orientation", "ColorSpace", "Gamma", "InteropIndex", "ExifVersion", "FlashpixVersion",
+    "ComponentsConfiguration", "YCbCrPositioning", "XResolution", "YResolution", "ResolutionUnit",
+}
+TIFF_STRUCTURE = {
+    "ImageWidth", "ImageHeight", "BitsPerSample", "Compression", "PhotometricInterpretation",
+    "Thresholding", "FillOrder", "StripOffsets", "SamplesPerPixel", "RowsPerStrip",
+    "StripByteCounts", "PlanarConfiguration", "T4Options", "T6Options", "Group3Options",
+    "Group4Options", "PageNumber", "TransferFunction", "WhitePoint", "PrimaryChromaticities",
+    "ColorMap", "HalftoneHints", "TileWidth", "TileLength", "TileOffsets", "TileByteCounts",
+    "ExtraSamples", "SampleFormat", "SMinSampleValue", "SMaxSampleValue", "MinSampleValue",
+    "MaxSampleValue", "JPEGTables", "JPEGProc", "YCbCrCoefficients", "YCbCrSubSampling",
+    "ReferenceBlackWhite", "Predictor", "InkSet", "NumberOfInks", "NewSubfileType", "SubfileType",
+    # ExifTool's names for the strip offsets of JPEG-compressed TIFF
+    "PreviewImageStart", "PreviewImageLength", "PreviewImage",
+}
+PRIVATE_GROUPS = {"XMP", "IPTC", "MakerNotes", "Photoshop", "GPS", "PLIST"}
+PRIVATE_TAG = re.compile(
+    r"gps|latitude|longitude|location|serialnumber|ownername|"
+    r"^(?:make|model|artist|author|creator|comment|description|imagedescription|"
+    r"copyright|software|datetimeoriginal|createdate|modifydate|creationdate|"
+    r"creationtime|trackcreatedate|trackmodifydate|mediacreatedate|mediamodifydate)$",
+    re.IGNORECASE)
+UNKNOWN_TAG = re.compile(r"^Unknown|_0x[0-9a-f]{4}$", re.IGNORECASE)
+# HEIF/AVIF structure that ExifTool lists as unknown boxes: sequence edit lists,
+# codec settings, color, coding constraints, alternative-image groups, item
+# data and emptied space. formats/heif.py verifies these boxes itself.
+BMFF_STRUCTURE = {"Unknown_" + name for name in ("edts", "av1C", "hvcC", "colr", "ccst", "pasp",
+                                                  "btrt", "free", "altr", "idat")}
+# ExifTool's group names for the XMP namespaces whose HDR fields xmp.py keeps.
+XMP_GROUPS = {"XMP-hdrgm": xmp.ADOBE_GAIN_MAP, "XMP-apdi": xmp.APPLE_PIXEL_DATA,
+              "XMP-HDRGainMap": xmp.APPLE_GAIN_MAP}
+
+
+class ExifToolError(Exception):
+    """ExifTool could not run, or reported a problem with a file."""
+
+
+def find():
+    """The ExifTool executable, or None when it is not installed. An explicit
+    MAGICDISPEL_EXIFTOOL that does not name a program is an error."""
+    configured = os.environ.get("MAGICDISPEL_EXIFTOOL")
+    if configured:
+        candidate = shutil.which(configured) or os.path.expanduser(configured)
+        if Path(candidate).is_file() and os.access(candidate, os.X_OK):
+            return candidate
+        raise UserError("exiftool_misconfigured", path=configured)
+    for candidate in (shutil.which("exiftool"), "/opt/homebrew/bin/exiftool", "/usr/local/bin/exiftool"):
+        if candidate and Path(candidate).is_file() and os.access(candidate, os.X_OK):
+            return candidate
+    return None
+
+
+def version(exiftool):
+    """ExifTool's version, or None if it does not run."""
+    try:
+        return run(exiftool, ["-ver"]).stdout.decode("utf-8", "replace").strip()
+    except (ExifToolError, OSError):
+        return None
+
+
+def usable(found_version):
+    """12.73 is the oldest release that reads recent iPhone files reliably."""
+    match = re.fullmatch(r"(\d+)\.(\d+)(?:_\d+)?", found_version or "")
+    return bool(match) and tuple(map(int, match.groups())) >= (12, 73)
+
+
+def second_opinion(exiftool, data, kind):
+    """Have ExifTool read a rebuilt file; raise VerificationError on anything off."""
+    try:
+        tags = read(exiftool, data)
+    except ExifToolError as error:
+        raise VerificationError("exiftool_problem", detail=str(error))
+    check_tags(tags, kind)
+
+
+def read(exiftool, data):
+    """Every tag ExifTool finds in `data`, keyed "Group0:Group1[:CopyN]:Tag"; a warning raises."""
+    tags = json.loads(run(exiftool, ["-j", "-G0:1:4", "-a", "-s", "-n", "-e", "-u", "-all", "-"],
+                          data).stdout)[0]
+    for key, value in tags.items():
+        if key.split(":")[-1] in ("Error", "Warning"):
+            raise ExifToolError(str(value))
+    return tags
+
+
+def check_tags(tags, kind):
+    """Only structure and display fields may remain, and nothing unidentified."""
+    allowed_exif = DISPLAY_EXIF | (TIFF_STRUCTURE if kind == "TIFF" else set())
+    remaining = []
+    for key, value in tags.items():
+        parts = key.split(":")
+        group, tag = parts[0], parts[-1]
+        # ICC identity data is sanitized and verified as complete profile blocks.
+        if group in ("SourceFile", "ExifTool", "ICC_Profile", "Composite") or parts[:2] == ["File", "System"]:
+            continue
+        if rendering_field(parts, value):
+            continue
+        if (group in PRIVATE_GROUPS or (group == "EXIF" and tag not in allowed_exif)
+                or (group != "EXIF" and PRIVATE_TAG.search(tag)
+                    and value not in (None, "", 0, "0000:00:00 00:00:00"))
+                or (UNKNOWN_TAG.search(tag) and not (group == "QuickTime" and tag in BMFF_STRUCTURE))):
+            remaining.append(key)
+    if remaining:
+        raise VerificationError("metadata_remains", tags=", ".join(remaining))
+
+
+def rendering_field(parts, value):
+    """HDR rendering values: the gain-map XMP fields xmp.py keeps, and Apple's
+    HDR headroom and gain in its maker note."""
+    group, family1, tag = parts[0], parts[1] if len(parts) > 2 else "", parts[-1]
+    if group == "MakerNotes" and family1 == "Apple":
+        return tag in ("HDRHeadroom", "HDRGain") and xmp.numeric(value)
+    if group == "XMP" and family1 in XMP_GROUPS:
+        text = [str(item) for item in value] if isinstance(value, list) else str(value)
+        return xmp.permitted("{%s}%s" % (XMP_GROUPS[family1], tag), text)
+    return False
+
+
+def run(exiftool, arguments, data=None):
+    """ExifTool's output for `arguments`, with `data` as its standard input."""
+    result = subprocess.run([exiftool, "-config", "", "-charset", "filename=UTF8", *arguments],
+                            input=data, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if result.returncode:
+        raise ExifToolError((result.stderr or result.stdout).decode("utf-8", "replace").strip()
+                            or "ExifTool failed")
+    return result

magicdispel/formats/__init__.py

@@ -0,0 +1,36 @@
+"""Image formats rebuilt from an allowlist of the parts needed to show them.
+
+Each format module provides:
+    rebuild(data) -> bytes      a new file holding only the allowlisted parts;
+                                raises FormatError if that cannot be done safely
+    verify(original, rebuilt)   an independent check of the result; raises
+                                VerificationError if anything is off
+"""
+from . import bmp, gif, heif, jpeg, png, tiff, webp
+
+MODULES = {"PNG": png, "APNG": png, "BMP": bmp, "JPEG": jpeg, "WEBP": webp, "GIF": gif,
+           "HEIC": heif, "AVIF": heif, "TIFF": tiff}
+# File name extensions of each format, the first being the default. A source
+# whose extension does not match its content gets the default; BMP becomes PNG.
+SUFFIXES = {"JPEG": (".jpg", ".jpeg", ".jpe"), "PNG": (".png",), "APNG": (".png", ".apng"),
+            "HEIC": (".heic", ".heif", ".hif"), "AVIF": (".avif",), "WEBP": (".webp",),
+            "GIF": (".gif",), "TIFF": (".tiff", ".tif"), "BMP": (".png",)}
+
+
+def identify(data):
+    """The format name from a file's leading bytes, or None for other files."""
+    if data[4:8] == b"ftyp":
+        return heif.brand_format(data)
+    if data.startswith(png.SIGNATURE):
+        return "APNG" if png.is_animated(data) else "PNG"
+    if data[:3] == b"\xff\xd8\xff":
+        return "JPEG"
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "WEBP"
+    if data[:6] in (b"GIF87a", b"GIF89a"):
+        return "GIF"
+    if data[:4] in (b"II*\0", b"MM\0*", b"II+\0", b"MM\0+"):  # the last two are BigTIFF
+        return "TIFF"
+    if data[:2] == b"BM":
+        return "BMP"
+    return None