htmlcmp 1.3.0__tar.gz → 2.1.0__tar.gz

{htmlcmp-1.3.0 → htmlcmp-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlcmp
-Version: 1.3.0
+Version: 2.1.0
 Summary: Compare HTML files by rendered output
 Author: Andreas Stefl
 Maintainer-email: Andreas Stefl <stefl.andreas@gmail.com>
@@ -9,12 +9,13 @@ Project-URL: source, https://github.com/opendocument-app/compare-html
 Project-URL: download, https://pypi.org/project/pyodr/#files
 Project-URL: tracker, https://github.com/opendocument-app/compare-html/issues
 Project-URL: release notes, https://github.com/opendocument-app/compare-html/releases
-Requires-Python: >=3.7
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: pillow
 Requires-Dist: selenium
 Requires-Dist: flask
 Requires-Dist: watchdog
+Requires-Dist: rich
 
 # htmlcmp
 

{htmlcmp-1.3.0 → htmlcmp-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "htmlcmp"
-version = "1.3.0"
+version = "2.1.0"
 description = "Compare HTML files by rendered output"
 classifiers = []
 authors = [
@@ -9,7 +9,7 @@ authors = [
 maintainers = [
     {name = "Andreas Stefl", email="stefl.andreas@gmail.com"},
 ]
-requires-python = ">=3.7"
+requires-python = ">=3.10"
 readme = "README.md"
 license = {file = "LICENSE.txt"}
 dependencies = [
@@ -17,10 +17,11 @@ dependencies = [
     "selenium",
     "flask",
     "watchdog",
+    "rich",
 ]
 
 [project.scripts]
-"compare-html" = "htmlcmp.compare_output:main"
+"compare-html" = "htmlcmp.compare_output_cli:main"
 "compare-html-server" = "htmlcmp.compare_output_server:main"
 "html-render-diff" = "htmlcmp.html_render_diff:main"
 "html-tidy" = "htmlcmp.tidy_output:main"

htmlcmp-2.1.0/src/htmlcmp/common.py

@@ -0,0 +1,135 @@
+import sys
+import json
+import logging
+import filecmp
+from pathlib import Path
+
+from htmlcmp.html_render_diff import get_browser, html_render_diff
+
+
+class bcolors:
+    HEADER = "\033[95m"
+    OKBLUE = "\033[94m"
+    OKCYAN = "\033[96m"
+    OKGREEN = "\033[92m"
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+
+
+def parse_json(path: Path) -> dict:
+    if not isinstance(path, Path):
+        raise TypeError(f"Expected Path, got {type(path)}")
+    if not path.is_file():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    with open(path) as f:
+        return json.load(f)
+
+
+def compare_json(a: Path, b: Path) -> bool:
+    if not isinstance(a, Path) or not isinstance(b, Path):
+        raise TypeError("Both arguments must be of type Path")
+    if not a.is_file() or not b.is_file():
+        raise FileNotFoundError("Both arguments must be files")
+
+    json_a = json.dumps(parse_json(a), sort_keys=True)
+    json_b = json.dumps(parse_json(b), sort_keys=True)
+    return json_a == json_b
+
+
+def compare_html(a: Path, b: Path, browser=None, diff_output: Path = None) -> bool:
+    if not isinstance(a, Path) or not isinstance(b, Path):
+        raise TypeError("Both arguments must be of type Path")
+    if not a.is_file() or not b.is_file():
+        raise FileNotFoundError("Both arguments must be files")
+
+    if browser is None:
+        browser = get_browser("firefox")
+    diff, (image_a, image_b) = html_render_diff(a, b, browser=browser)
+    result = diff.getbbox() is None
+    if diff_output is not None and not result:
+        diff_output.mkdir(parents=True, exist_ok=True)
+        image_a.save(diff_output / "a.png")
+        image_b.save(diff_output / "b.png")
+        diff.save(diff_output / "diff.png")
+    return result
+
+
+def compare_files(a: Path, b: Path, **kwargs) -> bool:
+    if not isinstance(a, Path) or not isinstance(b, Path):
+        raise TypeError("Both arguments must be of type Path")
+    if not a.is_file() or not b.is_file():
+        raise FileNotFoundError("Both arguments must be files")
+
+    if filecmp.cmp(a, b, shallow=False):
+        return True
+    if a.suffix == ".json":
+        return compare_json(a, b)
+    if a.suffix == ".html":
+        if kwargs.get("browser") is None:
+            # No browser available (e.g. --driver none): the files already
+            # differ at the byte level and we cannot render to check for visual
+            # equality, so report them as different rather than spinning up a
+            # browser here.
+            return False
+        return compare_html(a, b, **kwargs)
+    return False
+
+
+def comparable_file(path: Path) -> bool:
+    if not isinstance(path, Path):
+        raise TypeError(f"Expected Path, got {type(path)}")
+    if not path.is_file():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    if path.suffix == ".json":
+        return True
+    if path.suffix == ".html":
+        return True
+    return False
+
+
+def verbosity_to_level(verbosity: int) -> int:
+    if verbosity >= 3:
+        return logging.DEBUG
+    elif verbosity == 2:
+        return logging.INFO
+    elif verbosity == 1:
+        return logging.WARNING
+    else:
+        return logging.ERROR
+
+
+def setup_logging(
+    verbosity: int, log_file: Path = None, log_file_verbosity: int = None
+) -> None:
+    level = verbosity_to_level(verbosity)
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+    root_logger.handlers.clear()
+
+    formatter = logging.Formatter(
+        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+    root_logger.addHandler(console_handler)
+
+    if log_file is not None:
+        file_level = (
+            verbosity_to_level(log_file_verbosity)
+            if log_file_verbosity is not None
+            else level
+        )
+
+        file_handler = logging.FileHandler(log_file, mode="a", encoding="utf-8")
+        file_handler.setLevel(file_level)
+        file_handler.setFormatter(formatter)
+        root_logger.addHandler(file_handler)

htmlcmp-2.1.0/src/htmlcmp/compare_output_cli.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+import logging
+import argparse
+import threading
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+from rich.console import Console
+from rich.markup import escape
+from rich.progress import (
+    Progress,
+    SpinnerColumn,
+    BarColumn,
+    TextColumn,
+    MofNCompleteColumn,
+    TimeElapsedColumn,
+    TimeRemainingColumn,
+)
+
+from htmlcmp.html_render_diff import get_browser
+from htmlcmp.common import comparable_file, compare_files, setup_logging
+
+logger = logging.getLogger(__name__)
+
+
+class Config:
+    thread_local = threading.local()
+
+
+class Task:
+    """A single file comparison between the reference (A) and monitored (B) tree."""
+
+    def __init__(self, rel: Path, a: Path, b: Path, diff_output: Path = None):
+        self.rel = rel
+        self.a = a
+        self.b = b
+        self.diff_output = diff_output
+
+
+class Failure:
+    """A file that differs, is missing on one side, or errored while comparing.
+
+    ``kind`` is one of "different", "missing", or "error".
+    """
+
+    def __init__(self, rel: Path, kind: str, reason: str):
+        self.rel = rel
+        self.kind = kind
+        self.reason = reason
+
+
+def collect_tasks(
+    a: Path, b: Path, root: Path = None, diff_output: Path = None
+) -> tuple[list[Task], list[Failure]]:
+    """Walk both trees once and return (comparable tasks, structural failures).
+
+    Structural failures are files/directories present on only one side; they are
+    known to differ up-front and never get submitted to the executor.
+    """
+    if not isinstance(a, Path) or not isinstance(b, Path):
+        raise TypeError("Both arguments must be of type Path")
+    if not a.is_dir() or not b.is_dir():
+        raise FileNotFoundError("Both arguments must be directories")
+
+    if root is None:
+        root = a
+
+    tasks: list[Task] = []
+    failures: list[Failure] = []
+
+    left = sorted(p.name for p in a.iterdir())
+    right = sorted(p.name for p in b.iterdir())
+
+    left_files = {
+        name for name in left if (a / name).is_file() and comparable_file(a / name)
+    }
+    right_files = {
+        name for name in right if (b / name).is_file() and comparable_file(b / name)
+    }
+
+    for name in sorted(left_files | right_files):
+        rel = (a / name).relative_to(root)
+        if name in left_files and name in right_files:
+            tasks.append(
+                Task(
+                    rel,
+                    a / name,
+                    b / name,
+                    None if diff_output is None else diff_output / name,
+                )
+            )
+        elif name in left_files:
+            failures.append(Failure(rel, "missing", "missing in monitored (B)"))
+        else:
+            failures.append(Failure(rel, "missing", "missing in reference (A)"))
+
+    left_dirs = {name for name in left if (a / name).is_dir()}
+    right_dirs = {name for name in right if (b / name).is_dir()}
+
+    for name in sorted(left_dirs & right_dirs):
+        sub_tasks, sub_failures = collect_tasks(
+            a / name,
+            b / name,
+            root=root,
+            diff_output=None if diff_output is None else diff_output / name,
+        )
+        tasks.extend(sub_tasks)
+        failures.extend(sub_failures)
+
+    for name in sorted(left_dirs - right_dirs):
+        failures.append(
+            Failure((a / name).relative_to(root), "missing", "missing in monitored (B)")
+        )
+    for name in sorted(right_dirs - left_dirs):
+        failures.append(
+            Failure((b / name).relative_to(root), "missing", "missing in reference (A)")
+        )
+
+    return tasks, failures
+
+
+def run_task(task: Task) -> bool:
+    logger.debug("Comparing %s", task.rel)
+    browser = getattr(Config.thread_local, "browser", None)
+    return compare_files(task.a, task.b, browser=browser, diff_output=task.diff_output)
+
+
+def make_executor(max_workers: int, driver: str | None) -> ThreadPoolExecutor:
+    def initializer():
+        # One browser per worker thread. Without a driver we only ever compare
+        # JSON / byte-identical files, so no browser is needed.
+        if driver is not None:
+            if getattr(Config.thread_local, "browser", None) is None:
+                logger.info("Starting %s browser for worker thread", driver)
+                Config.thread_local.browser = get_browser(driver=driver)
+
+    logger.info("Creating executor with %d worker(s)", max_workers)
+    return ThreadPoolExecutor(max_workers=max_workers, initializer=initializer)
+
+
+def github_error(rel: Path, reason: str) -> None:
+    """Emit a GitHub Actions error annotation so failures surface in the UI."""
+    # https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions
+    print(f"::error file={rel}::{reason}")
+
+
+def _resolve(task: Task, future, failures: list[Failure], github: bool):
+    """Resolve a finished future into an optional Failure. Returns it or None."""
+    try:
+        same = future.result()
+    except Exception as exc:  # noqa: BLE001 - surface any comparison error as a failure
+        logger.exception("Error comparing %s", task.rel)
+        failure = Failure(task.rel, "error", f"error: {exc}")
+    else:
+        if same:
+            logger.debug("Match: %s", task.rel)
+            return None
+        logger.info("Difference: %s", task.rel)
+        failure = Failure(task.rel, "different", "different")
+
+    failures.append(failure)
+    if github:
+        github_error(failure.rel, failure.reason)
+    return failure
+
+
+def _run_live(future_to_task, console, failures, github):
+    progress = Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TimeElapsedColumn(),
+        TimeRemainingColumn(),
+        console=console,
+        transient=True,
+    )
+    with progress:
+        bar = progress.add_task("comparing…", total=len(future_to_task))
+        for future in as_completed(future_to_task):
+            task = future_to_task[future]
+            # Transient line shows what's flowing through; only failures persist.
+            progress.update(bar, description=str(task.rel))
+            failure = _resolve(task, future, failures, github)
+            if failure is not None:
+                progress.console.print(
+                    f"[red]✘[/red] {escape(str(failure.rel))} "
+                    f"[red]— {escape(failure.reason)}[/red]"
+                )
+            progress.advance(bar)
+
+
+def _run_plain(future_to_task, console, failures, github):
+    # No live region in CI / non-TTY: print failures as they happen plus a
+    # periodic heartbeat so long runs still show they're alive.
+    total = len(future_to_task)
+    step = max(1, total // 20)
+    done = 0
+    for future in as_completed(future_to_task):
+        task = future_to_task[future]
+        failure = _resolve(task, future, failures, github)
+        if failure is not None:
+            console.print(
+                f"[red]✘[/red] {escape(str(failure.rel))} "
+                f"[red]— {escape(failure.reason)}[/red]"
+            )
+        done += 1
+        if done % step == 0 or done == total:
+            console.print(f"[dim]  … {done}/{total} compared[/dim]")
+
+
+def _print_summary(console, total: int, failures: list[Failure]) -> None:
+    console.rule("[bold]Summary")
+
+    n_diff = sum(1 for f in failures if f.kind == "different")
+    n_error = sum(1 for f in failures if f.kind == "error")
+    n_missing = sum(1 for f in failures if f.kind == "missing")
+    matched = total - n_diff - n_error
+
+    if not failures:
+        console.print(f"[green]✓ All {total} file(s) match.[/green]")
+        return
+
+    parts = [f"[green]{matched} matched[/green]"]
+    if n_diff:
+        parts.append(f"[red]{n_diff} different[/red]")
+    if n_missing:
+        parts.append(f"[red]{n_missing} missing[/red]")
+    if n_error:
+        parts.append(f"[red]{n_error} error[/red]")
+    console.print(", ".join(parts))
+
+    console.print("\n[red bold]Failures:[/red bold]")
+    for f in sorted(failures, key=lambda f: (f.kind, str(f.rel))):
+        console.print(
+            f"  [red]{escape(str(f.rel))}[/red] [dim]— {escape(f.reason)}[/dim]"
+        )
+
+
+def run(
+    a: Path,
+    b: Path,
+    *,
+    driver: str | None,
+    max_workers: int,
+    diff_output: Path | None,
+    console: Console,
+    live: bool,
+    github: bool,
+) -> int:
+    console.print(
+        f"[bold]Comparing[/bold] {escape(str(a))} [dim]→[/dim] {escape(str(b))}"
+    )
+
+    tasks, failures = collect_tasks(a, b, diff_output=diff_output)
+    logger.info(
+        "Collected %d comparable file(s), %d structural difference(s)",
+        len(tasks),
+        len(failures),
+    )
+
+    # Report structural failures (missing files/dirs) up-front.
+    for f in sorted(failures, key=lambda f: str(f.rel)):
+        console.print(
+            f"[red]✘[/red] {escape(str(f.rel))} [red]— {escape(f.reason)}[/red]"
+        )
+        if github:
+            github_error(f.rel, f.reason)
+
+    total = len(tasks)
+    if total == 0:
+        console.print("[dim]No comparable files to compare.[/dim]")
+    else:
+        executor = make_executor(max_workers, driver)
+        try:
+            future_to_task = {executor.submit(run_task, t): t for t in tasks}
+            if live:
+                _run_live(future_to_task, console, failures, github)
+            else:
+                _run_plain(future_to_task, console, failures, github)
+        finally:
+            executor.shutdown(wait=True)
+
+    _print_summary(console, total, failures)
+
+    return 1 if failures else 0
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="compare-html",
+        description="Compare two directory trees of rendered HTML/JSON files.",
+    )
+    parser.add_argument("a", type=Path, help="Reference directory (A)")
+    parser.add_argument("b", type=Path, help="Monitored directory (B)")
+    parser.add_argument(
+        "--driver",
+        choices=["chrome", "firefox", "none"],
+        default="firefox",
+        help="Browser used to render HTML diffs; 'none' compares only "
+        "JSON and byte-identical files (default: firefox)",
+    )
+    parser.add_argument(
+        "--diff-output", type=Path, help="Directory to write diff images for mismatches"
+    )
+    parser.add_argument(
+        "-j",
+        "--max-workers",
+        type=int,
+        default=1,
+        help="Number of parallel comparison workers (default: 1)",
+    )
+    parser.add_argument(
+        "--no-progress",
+        action="store_true",
+        help="Disable the live progress bar (forced off when not a TTY / in CI)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v, -vv, -vvv)",
+    )
+    parser.add_argument("--log-file", type=Path, help="Path to log file")
+    parser.add_argument(
+        "--log-file-verbosity", type=int, help="Log file verbosity level"
+    )
+    args = parser.parse_args()
+
+    setup_logging(args.verbose, args.log_file, args.log_file_verbosity)
+
+    if not args.a.is_dir() or not args.b.is_dir():
+        print(f"Both arguments must be directories: {args.a} {args.b}", file=sys.stderr)
+        return 2
+
+    driver = None if args.driver == "none" else args.driver
+
+    console = Console()
+    github = os.environ.get("GITHUB_ACTIONS") == "true"
+    in_ci = bool(os.environ.get("CI"))
+    live = console.is_terminal and not in_ci and not args.no_progress
+
+    return run(
+        args.a,
+        args.b,
+        driver=driver,
+        max_workers=args.max_workers,
+        diff_output=args.diff_output,
+        console=console,
+        live=live,
+        github=github,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{htmlcmp-1.3.0 → htmlcmp-2.1.0}/src/htmlcmp/compare_output_server.py

@@ -15,7 +15,11 @@ from flask import Flask, send_from_directory, send_file
 import watchdog.observers
 import watchdog.events
 
-from htmlcmp.compare_output import comparable_file, compare_files
+from htmlcmp.common import (
+    comparable_file,
+    compare_files,
+    setup_logging,
+)
 from htmlcmp.html_render_diff import get_browser, html_render_diff
 
 logger = logging.getLogger(__name__)
@@ -28,6 +32,10 @@ class Config:
     observer = None
     comparator = None
     browser = None
+    # Serializes access to the single shared ``browser`` above: Flask serves
+    # requests from a thread pool and Selenium drivers are not thread-safe, so
+    # concurrent /image_diff requests would otherwise interleave on one driver.
+    browser_lock = threading.Lock()
     thread_local = threading.local()
     log_file: Path = None
 
@@ -718,11 +726,12 @@ def image_diff(path: str):
     if not (Config.path_a / path).is_file() or not (Config.path_b / path).is_file():
         return "Image diff not available: file missing on one side", 404
 
-    diff, _ = html_render_diff(
-        Config.path_a / path,
-        Config.path_b / path,
-        Config.browser,
-    )
+    with Config.browser_lock:
+        diff, _ = html_render_diff(
+            Config.path_a / path,
+            Config.path_b / path,
+            Config.browser,
+        )
     tmp = io.BytesIO()
     diff.save(tmp, "JPEG", quality=70)
     tmp.seek(0)
@@ -775,49 +784,6 @@ def update_ref(path: str):
     return "Reference updated", 200
 
 
-def verbosity_to_level(verbosity: int) -> int:
-    if verbosity >= 3:
-        return logging.DEBUG
-    elif verbosity == 2:
-        return logging.INFO
-    elif verbosity == 1:
-        return logging.WARNING
-    else:
-        return logging.ERROR
-
-
-def setup_logging(
-    verbosity: int, log_file: Path = None, log_file_verbosity: int = None
-) -> None:
-    level = verbosity_to_level(verbosity)
-
-    root_logger = logging.getLogger()
-    root_logger.setLevel(level)
-    root_logger.handlers.clear()
-
-    formatter = logging.Formatter(
-        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-        datefmt="%Y-%m-%d %H:%M:%S",
-    )
-
-    console_handler = logging.StreamHandler(sys.stderr)
-    console_handler.setLevel(level)
-    console_handler.setFormatter(formatter)
-    root_logger.addHandler(console_handler)
-
-    if log_file is not None:
-        file_level = (
-            verbosity_to_level(log_file_verbosity)
-            if log_file_verbosity is not None
-            else level
-        )
-
-        file_handler = logging.FileHandler(log_file, mode="a", encoding="utf-8")
-        file_handler.setLevel(file_level)
-        file_handler.setFormatter(formatter)
-        root_logger.addHandler(file_handler)
-
-
 def main():
     parser = argparse.ArgumentParser()
     parser.add_argument("ref", type=Path, help="Path to the reference directory")
@@ -825,6 +791,11 @@ def main():
     parser.add_argument("--driver", choices=["chrome", "firefox"])
     parser.add_argument("--max-workers", type=int, default=1)
     parser.add_argument("--compare", action="store_true")
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Host/interface to bind the server to (default: 0.0.0.0)",
+    )
     parser.add_argument("--port", type=int, default=5000)
     parser.add_argument(
         "-v",
@@ -859,7 +830,7 @@ def main():
         Config.observer = Observer()
         Config.observer.start()
 
-    app.run(host="0.0.0.0", port=args.port)
+    app.run(host=args.host, port=args.port)
 
     if args.compare:
         Config.observer.stop()

{htmlcmp-1.3.0 → htmlcmp-2.1.0}/src/htmlcmp/html_render_diff.py

@@ -108,8 +108,8 @@ def main():
     parser.add_argument("a", type=Path, help="Path to the first HTML file")
     parser.add_argument("b", type=Path, help="Path to the second HTML file")
     parser.add_argument("--driver", choices=["chrome", "firefox"], default="firefox")
-    parser.add_argument("--max-width", default=1000)
-    parser.add_argument("--max-height", default=10000)
+    parser.add_argument("--max-width", type=int, default=1000)
+    parser.add_argument("--max-height", type=int, default=10000)
     args = parser.parse_args()
 
     browser = get_browser(args.driver, args.max_width, args.max_height)