imdiff 0.4.6__tar.gz → 2.0.0__tar.gz

imdiff-2.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: imdiff
+Version: 2.0.0
+Summary: Compare image files in different directories
+Author-email: "John T. Goetz" <theodore.goetz@gmail.com>
+Project-URL: homepage, https://gitlab.com/johngoetz/imdiff
+Keywords: image-diff,directory-comparison,visual-regression,golden-files,test-artifacts,qa
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: Viewers
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: ttkbootstrap
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: basedpyright; extra == "dev"
+Dynamic: license-file
+
+# ImDiff: Compare Directories of Images
+
+ImDiff compares either two image files or two directory trees that contain image
+files with matching relative paths. It is intended for workflows where generated
+images need visual review as part of test development, golden-file updates, or
+artifact triage.
+
+The project exposes the same comparison engine through two interfaces:
+
+- `python -m imdiff LEFT RIGHT` opens a Tk-based review window when the GUI
+  stack is available, or warns and falls back to summary mode when it is not.
+- `python -m imdiff --summary LEFT RIGHT` prints a non-interactive summary and
+  exits with a non-zero status when differences are found without importing any
+  GUI-only modules.
+
+When both arguments are directories, ImDiff walks the union of both directory
+trees, pairs files by relative path, and classifies each entry as:
+
+- `identical`: byte-identical files or text files with no unified diff output
+- `similar`: images whose normalized RMSE is below the project threshold
+- `different`: images or text files whose contents differ materially
+- `different-size`: image pairs with different dimensions
+- `missing` or `new`: a file exists on only one side
+- `failed-to-load`: a file exists but Pillow could not decode it as an image
+
+The interactive directory view combines a file tree, image panes, and file
+operations so a reviewer can inspect left, right, and diff images, switch zoom
+policies, and copy or delete files directly from the comparison session.
+
+This utility requires that the Tk Python packages be installed on the system. Hint for
+those running Ubuntu:
+
+```
+apt install python3-pil python3-pil.imagetk python3-tk
+```
+
+The application also depends on `numpy` and `ttkbootstrap` for image math and
+themed Tk widgets.
+
+## Usage
+
+Compare two image files:
+
+```bash
+python -m imdiff path/to/expected.png path/to/actual.png
+```
+
+Compare two directories and print a CI-friendly summary:
+
+```bash
+python -m imdiff --summary tests/baseline-images tests/generated-images
+```
+
+When the GUI cannot be imported or Tk cannot start, the default interactive
+command warns on `stderr` and continues in the same summary mode used by
+`--summary`. This makes headless CI environments safe without changing the CLI
+command line.
+
+## Repository Layout
+
+- `imdiff/image_comparator.py` contains the lazy comparison model shared by the
+  CLI and GUI.
+- `imdiff/list_files.py` pairs files across directory trees.
+- `imdiff/cli/` contains the command-line entry points and summary printing.
+- `imdiff/gui/` contains the Tk windows, canvases, menus, and directory browser.
+- `developing/architecture.md` describes the component relationships in more
+  detail.

imdiff-2.0.0/README.md

@@ -0,0 +1,67 @@
+# ImDiff: Compare Directories of Images
+
+ImDiff compares either two image files or two directory trees that contain image
+files with matching relative paths. It is intended for workflows where generated
+images need visual review as part of test development, golden-file updates, or
+artifact triage.
+
+The project exposes the same comparison engine through two interfaces:
+
+- `python -m imdiff LEFT RIGHT` opens a Tk-based review window when the GUI
+  stack is available, or warns and falls back to summary mode when it is not.
+- `python -m imdiff --summary LEFT RIGHT` prints a non-interactive summary and
+  exits with a non-zero status when differences are found without importing any
+  GUI-only modules.
+
+When both arguments are directories, ImDiff walks the union of both directory
+trees, pairs files by relative path, and classifies each entry as:
+
+- `identical`: byte-identical files or text files with no unified diff output
+- `similar`: images whose normalized RMSE is below the project threshold
+- `different`: images or text files whose contents differ materially
+- `different-size`: image pairs with different dimensions
+- `missing` or `new`: a file exists on only one side
+- `failed-to-load`: a file exists but Pillow could not decode it as an image
+
+The interactive directory view combines a file tree, image panes, and file
+operations so a reviewer can inspect left, right, and diff images, switch zoom
+policies, and copy or delete files directly from the comparison session.
+
+This utility requires that the Tk Python packages be installed on the system. Hint for
+those running Ubuntu:
+
+```
+apt install python3-pil python3-pil.imagetk python3-tk
+```
+
+The application also depends on `numpy` and `ttkbootstrap` for image math and
+themed Tk widgets.
+
+## Usage
+
+Compare two image files:
+
+```bash
+python -m imdiff path/to/expected.png path/to/actual.png
+```
+
+Compare two directories and print a CI-friendly summary:
+
+```bash
+python -m imdiff --summary tests/baseline-images tests/generated-images
+```
+
+When the GUI cannot be imported or Tk cannot start, the default interactive
+command warns on `stderr` and continues in the same summary mode used by
+`--summary`. This makes headless CI environments safe without changing the CLI
+command line.
+
+## Repository Layout
+
+- `imdiff/image_comparator.py` contains the lazy comparison model shared by the
+  CLI and GUI.
+- `imdiff/list_files.py` pairs files across directory trees.
+- `imdiff/cli/` contains the command-line entry points and summary printing.
+- `imdiff/gui/` contains the Tk windows, canvases, menus, and directory browser.
+- `developing/architecture.md` describes the component relationships in more
+  detail.

{imdiff-0.4.6 → imdiff-2.0.0}/imdiff/__init__.py

@@ -1,4 +1,8 @@
-from .version import __version__, version_info
+"""Public package surface for embedding imdiff in other Python code."""
+
+# pyright: reportUnusedImport=none
+# ruff: noqa: F401
 
 from .directory_comparator import dir_diff
 from .image_comparator import ImageComparator
+from .version import __version__, version_info

{imdiff-0.4.6 → imdiff-2.0.0}/imdiff/__main__.py

@@ -1,7 +1,8 @@
+"""Module entry point for `python -m imdiff`."""
+
 import sys
 
 from .cli.main import main
 
-
 if __name__ == '__main__':
     sys.exit(main())

imdiff-2.0.0/imdiff/_compat.py

@@ -0,0 +1,19 @@
+"""Compatibility helpers for typing features that are optional at runtime."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+F = TypeVar('F', bound=Callable[..., object])
+
+if TYPE_CHECKING:
+    from typing_extensions import override
+else:
+
+    def override(method: F) -> F:
+        """Preserve the decorator shape when `typing_extensions` is unavailable."""
+        return method
+
+
+__all__ = ['override']

imdiff-2.0.0/imdiff/_types.py

@@ -0,0 +1,19 @@
+"""Shared type aliases for the comparison layer."""
+
+from __future__ import annotations
+
+import pathlib
+from os import PathLike
+from typing import Literal, Union
+
+PathInput = Union[str, PathLike[str], pathlib.Path]
+DiffStatus = Literal[
+    'identical',
+    'different-size',
+    'missing',
+    'new',
+    'failed-to-load',
+    'not-found',
+]
+DiffInfo = Union[DiffStatus, float]
+FileEntry = tuple[str, pathlib.Path, pathlib.Path]

imdiff-2.0.0/imdiff/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for file and directory entry points."""

imdiff-2.0.0/imdiff/cli/_gui_runtime.py

@@ -0,0 +1,39 @@
+"""Helpers for lazy GUI startup and headless fallback."""
+
+from __future__ import annotations
+
+
+class GuiUnavailableError(RuntimeError):
+    """Raised when GUI support is unavailable but summary mode can continue."""
+
+
+def format_gui_warning(error: GuiUnavailableError) -> str:
+    """Render a concise warning for stderr when falling back to summary mode."""
+    return f'warning: GUI unavailable ({error}); running in summary mode'
+
+
+def normalize_gui_import_error(error: BaseException) -> GuiUnavailableError | None:
+    """Convert expected GUI import failures into a fallback-friendly error."""
+    if isinstance(error, ModuleNotFoundError):
+        module_name = error.name or str(error)
+        return GuiUnavailableError(f'missing Python module {module_name}')
+
+    if isinstance(error, ImportError):
+        module_name = getattr(error, 'name', None)
+        if module_name:
+            return GuiUnavailableError(f'failed to import Python module {module_name}')
+        return GuiUnavailableError(str(error))
+
+    return None
+
+
+def normalize_gui_startup_error(error: BaseException) -> GuiUnavailableError | None:
+    """Convert expected Tk startup failures into a fallback-friendly error."""
+    error_type = type(error)
+    if error_type.__name__ == 'TclError' and error_type.__module__ in {
+        'tkinter',
+        '_tkinter',
+    }:
+        return GuiUnavailableError(f'Tk startup failed: {error}')
+
+    return None

imdiff-2.0.0/imdiff/cli/dir_diff.py

@@ -0,0 +1,81 @@
+"""CLI adapters for directory comparison modes."""
+
+from __future__ import annotations
+
+import difflib
+import importlib
+import pathlib
+from typing import Optional
+
+from ..image_comparator import ImageComparator
+from ..list_files import is_image, list_files
+from ._gui_runtime import (
+    normalize_gui_import_error,
+    normalize_gui_startup_error,
+)
+
+
+def app(
+    leftdir: Optional[pathlib.Path] = None, rightdir: Optional[pathlib.Path] = None
+) -> None:
+    """Open the directory comparison window for the requested roots."""
+    try:
+        gui_module = importlib.import_module('imdiff.gui')
+        DirDiffMainWindow = gui_module.DirDiffMainWindow
+    except (ImportError, ModuleNotFoundError) as error:
+        gui_error = normalize_gui_import_error(error)
+        assert gui_error is not None
+        raise gui_error from error
+
+    try:
+        win = DirDiffMainWindow()
+    except Exception as error:
+        gui_error = normalize_gui_startup_error(error)
+        if gui_error is not None:
+            raise gui_error from error
+        raise
+
+    win.load(leftdir, rightdir)
+    win.mainloop()
+
+
+def print_diff(leftdir: pathlib.Path, rightdir: pathlib.Path) -> int:
+    """Print a summary of directory differences and return the diff count."""
+    ndiffs = 0
+    assert leftdir.is_dir() and rightdir.is_dir(), 'Items must both be directories'
+
+    rmse_threshold = 0.02
+
+    for subpath, left, right in list_files(leftdir, rightdir):
+        # Summary mode reuses the same comparison rules as the GUI so CI output
+        # matches what a developer will see when opening the same directories.
+        if not left.is_file():
+            ndiffs += 1
+            print(f'Only in {right.parent}: {subpath}')
+        elif not right.is_file():
+            ndiffs += 1
+            print(f'Only in {left.parent}: {subpath}')
+        elif is_image(left) and is_image(right):
+            icmp = ImageComparator(left, right)
+            diff_info = icmp.diff_info
+            if diff_info != 'identical':
+                if isinstance(diff_info, str):
+                    ndiffs += 1
+                    print(f'{diff_info} (as image): {subpath}')
+                elif diff_info > rmse_threshold:
+                    ndiffs += 1
+                    print(f'image difference NRMSE {diff_info:.4f}: {subpath}')
+        else:
+            diff_output = list(
+                difflib.unified_diff(
+                    left.read_text().splitlines(),
+                    right.read_text().splitlines(),
+                    fromfile=str(left),
+                    tofile=str(right),
+                    lineterm='',
+                )
+            )
+            if diff_output:
+                ndiffs += 1
+                print('\n'.join(diff_output))
+    return ndiffs

imdiff-2.0.0/imdiff/cli/image_diff.py

@@ -0,0 +1,75 @@
+"""CLI adapters for single-image comparison modes."""
+
+from __future__ import annotations
+
+import difflib
+import importlib
+import pathlib
+from typing import Optional
+
+from ..image_comparator import ImageComparator
+from ..list_files import is_image
+from ._gui_runtime import (
+    normalize_gui_import_error,
+    normalize_gui_startup_error,
+)
+
+
+def app(
+    left: Optional[pathlib.Path] = None, right: Optional[pathlib.Path] = None
+) -> None:
+    """Open the single-image comparison window for the requested files."""
+    try:
+        gui_module = importlib.import_module('imdiff.gui')
+        ImageDiffMainWindow = gui_module.ImageDiffMainWindow
+    except (ImportError, ModuleNotFoundError) as error:
+        gui_error = normalize_gui_import_error(error)
+        assert gui_error is not None
+        raise gui_error from error
+
+    try:
+        win = ImageDiffMainWindow()
+    except Exception as error:
+        gui_error = normalize_gui_startup_error(error)
+        if gui_error is not None:
+            raise gui_error from error
+        raise
+
+    win.load(left, right)
+    win.mainloop()
+
+
+def print_diff(left: pathlib.Path, right: pathlib.Path) -> int:
+    """Print a summary of a single file comparison and return the diff count."""
+    ndiffs = 0
+    assert left.is_file() and right.is_file(), 'Items must both be files'
+
+    rmse_threshold = 0.02
+    if is_image(left) and is_image(right):
+        icmp = ImageComparator(left, right)
+        diff_info = icmp.diff_info
+        if diff_info != 'identical':
+            ndiffs += 1
+            if diff_info == 'missing':
+                print(f'Only in {left.parent}: {left.name}')
+            elif diff_info == 'new':
+                print(f'Only in {right.parent}: {right.name}')
+            elif isinstance(diff_info, str):
+                print(f'Images {left} and {right} differ ({diff_info})')
+            elif diff_info > rmse_threshold:
+                print(f'Images {left} and {right} differ NRMSE: {diff_info}')
+    else:
+        diff_output = list(
+            difflib.unified_diff(
+                left.read_text().splitlines(),
+                right.read_text().splitlines(),
+                fromfile=str(left),
+                tofile=str(right),
+                lineterm='',
+            )
+        )
+        if diff_output:
+            ndiffs += 1
+            print('\n'.join(diff_output))
+
+    return ndiffs

imdiff-2.0.0/imdiff/cli/main.py

@@ -0,0 +1,91 @@
+"""Command-line dispatch for summary and GUI workflows."""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+from typing import Optional
+
+from ..version import __version__
+from . import dir_diff, image_diff
+from ._gui_runtime import GuiUnavailableError, format_gui_warning
+
+
+class ParsedArgs(argparse.Namespace):
+    """Typed namespace so downstream code can treat parsed paths precisely."""
+
+    summary: bool = False
+    left: pathlib.Path = pathlib.Path('.')
+    right: pathlib.Path = pathlib.Path('.')
+
+
+def parse_args() -> ParsedArgs:
+    """Parse the shared CLI flags for file and directory comparison modes."""
+    parser = argparse.ArgumentParser(
+        prog='imdiff',
+        description='Compare images one by one or directory by directory',
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'%(prog)s {__version__}',
+    )
+    parser.add_argument(
+        '--summary',
+        action='store_true',
+        help=(
+            'Print diff result and exit. Disables the GUI. '
+            'Exits with non-zero if there are differences.'
+        ),
+    )
+    parser.add_argument(
+        'left',
+        default='.',
+        type=pathlib.Path,
+        help='Image or directory of images to compare.',
+    )
+    parser.add_argument(
+        'right',
+        default='.',
+        type=pathlib.Path,
+        help='Image or directory of images to compare.',
+    )
+    return parser.parse_args(namespace=ParsedArgs())
+
+
+def main() -> Optional[int]:
+    """Dispatch to GUI or summary workflows, with summary fallback for headless use."""
+    args = parse_args()
+    if args.left.is_dir():
+        if not args.right.is_dir():
+            raise NotADirectoryError(
+                'Paths must be either both image files or both directories'
+            )
+        if args.summary:
+            ndiffs = dir_diff.print_diff(args.left, args.right)
+            return int(ndiffs > 0)
+        try:
+            dir_diff.app(args.left, args.right)
+            return None
+        except GuiUnavailableError as error:
+            print(format_gui_warning(error), file=sys.stderr)
+            ndiffs = dir_diff.print_diff(args.left, args.right)
+            return int(ndiffs > 0)
+
+    if args.left.is_file():
+        assert args.right.is_file(), (
+            'Paths must be either both image files or both directories'
+        )
+        if args.summary:
+            ndiffs = image_diff.print_diff(args.left, args.right)
+            return int(ndiffs > 0)
+        try:
+            image_diff.app(args.left, args.right)
+            return None
+        except GuiUnavailableError as error:
+            print(format_gui_warning(error), file=sys.stderr)
+            ndiffs = image_diff.print_diff(args.left, args.right)
+            return int(ndiffs > 0)
+
+    raise OSError(f'{args.left} is not a file or directory')

imdiff-2.0.0/imdiff/directory_comparator.py

@@ -0,0 +1,71 @@
+"""Directory-level comparison helpers used by the CLI summary mode."""
+
+from __future__ import annotations
+
+import collections
+import difflib
+import filecmp
+import pathlib
+
+from ._types import PathInput
+from .image_comparator import ImageComparator
+from .list_files import is_image, list_files
+
+
+def dir_diff(
+    leftdir: PathInput, rightdir: PathInput
+) -> collections.defaultdict[str, list[str]]:
+    """Group directory entries by comparison status for summary-style reporting.
+
+    The CLI and any external callers use this function when they need a compact
+    classification of an entire directory tree rather than the richer GUI model.
+    It mirrors the GUI thresholds so command-line output and interactive review
+    describe the same files as identical, similar, or different.
+    """
+    leftdir_path = pathlib.Path(leftdir)
+    rightdir_path = pathlib.Path(rightdir)
+    if not leftdir_path.is_dir():
+        raise FileNotFoundError(leftdir_path)
+    if not rightdir_path.is_dir():
+        raise FileNotFoundError(rightdir_path)
+
+    rmse_threshold = 0.02
+
+    dinfo: collections.defaultdict[str, list[str]] = collections.defaultdict(list)
+    for subpath, left, right in list_files(leftdir_path, rightdir_path):
+        # Files are classified in increasing cost order so exact matches and
+        # obvious presence/absence cases avoid loading image data.
+        if not left.is_file():
+            dinfo['new'].append(subpath)
+        elif not right.is_file():
+            dinfo['missing'].append(subpath)
+        elif filecmp.cmp(left, right, shallow=False):
+            dinfo['identical'].append(subpath)
+        elif is_image(left) and is_image(right):
+            icmp = ImageComparator(left, right)
+            diff_info = icmp.diff_info
+            if isinstance(diff_info, str):
+                dinfo[diff_info].append(subpath)
+            elif diff_info > rmse_threshold:
+                dinfo['different'].append(subpath)
+            else:
+                dinfo['similar'].append(subpath)
+        else:
+            try:
+                diff_output = list(
+                    difflib.unified_diff(
+                        left.read_text().splitlines(),
+                        right.read_text().splitlines(),
+                        fromfile=str(left),
+                        tofile=str(right),
+                        lineterm='',
+                    )
+                )
+                if diff_output:
+                    dinfo['different'].append(subpath)
+                else:
+                    dinfo['identical'].append(subpath)
+            except UnicodeDecodeError:
+                dinfo['different'].append(subpath)
+
+    return dinfo

imdiff-2.0.0/imdiff/gui/__init__.py

@@ -0,0 +1,6 @@
+"""Public GUI entry points exposed to the CLI layer."""
+
+from .dir_diff_main_window import DirDiffMainWindow as DirDiffMainWindow
+from .image_diff_main_window import ImageDiffMainWindow as ImageDiffMainWindow
+
+__all__ = ['DirDiffMainWindow', 'ImageDiffMainWindow']

imdiff-2.0.0/imdiff/gui/_types.py

@@ -0,0 +1,37 @@
+"""GUI-facing type aliases and protocols shared across widgets."""
+
+from __future__ import annotations
+
+import pathlib
+import tkinter as tk
+from typing import Callable, Literal, Optional, Protocol, Union
+
+from PIL import Image
+
+from ..image_comparator import ImageComparator
+from .image_scaling import ImageScaling
+
+CanvasName = Literal['left', 'right', 'diff']
+ImageData = Optional[Image.Image]
+Event = tk.Event[tk.Misc]
+SelectCallback = Callable[[Optional[ImageComparator]], None]
+UpdateItemPath = Union[str, pathlib.Path, None]
+UpdateItemCallback = Callable[[UpdateItemPath, Optional[ImageComparator]], None]
+ActionCallback = Callable[[], None]
+
+
+class ZoomCanvas(Protocol):
+    scaling: ImageScaling
+    scaling_percent: Optional[int]
+
+
+class ZoomParent(Protocol):
+    canvases: dict[CanvasName, ZoomCanvas]
+
+    def zoom(
+        self,
+        mode: ImageScaling.Mode,
+        factor: float = 1,
+        shrink: bool = True,
+        expand: bool = True,
+    ) -> None: ...