Feat: Add CLI

Author: adrien-berchet

dir_content_diff/__init__.py

@@ -17,6 +17,7 @@
 import re
 from pathlib import Path
 
+from dir_content_diff.base_comparators import BaseComparator
 from dir_content_diff.base_comparators import DefaultComparator
 from dir_content_diff.base_comparators import IniComparator
 from dir_content_diff.base_comparators import JsonComparator
@@ -29,7 +30,6 @@
 
 __version__ = importlib.metadata.version("dir-content-diff")
 
-
 _DEFAULT_COMPARATORS = {
     None: DefaultComparator(),
     ".cfg": IniComparator(),  # luigi config files
@@ -230,6 +230,28 @@ def export_formatted_file(file, formatted_file, comparator, **kwargs):
         )
 
 
+def pick_comparator(comparator=None, suffix=None, comparators=None):
+    """Pick a comparator based on its name or a file suffix."""
+    if isinstance(comparator, BaseComparator):
+        return comparator
+    if comparators is None:
+        comparators = get_comparators()
+    if comparator is not None:
+        for i in comparators.values():  # pragma: no branch
+            if i.__class__.__name__ == comparator:
+                return i
+        LOGGER.debug(
+            "Could not find the comparator named '%s' in the given comparators",
+            comparator,
+        )
+    if suffix is not None:
+        if suffix in comparators:
+            return comparators.get(suffix)
+        LOGGER.debug("Could not find the comparator for the '%s' suffix", suffix)
+    LOGGER.debug("Returning the default comparator")
+    return _COMPARATORS.get(None)
+
+
 def compare_trees(
     ref_path,
     comp_path,
@@ -290,9 +312,6 @@ def compare_trees(
         difference messages. If the directories are considered as equal, an empty ``dict`` is
         returned.
     """
-    if comparators is None:
-        comparators = _COMPARATORS
-
     ref_path = Path(ref_path)
     comp_path = Path(comp_path)
     formatted_data_path = comp_path.with_name(
@@ -332,12 +351,10 @@ def compare_trees(
                         break
             if specific_file_args is None:
                 specific_file_args = {}
-            comparator = specific_file_args.pop(
-                "comparator",
-                comparators.get(
-                    ref_file.suffix,
-                    _COMPARATORS.get(None),
-                ),
+            comparator = pick_comparator(
+                comparator=specific_file_args.pop("comparator", None),
+                suffix=ref_file.suffix,
+                comparators=comparators,
             )
             comparator_args = specific_file_args.pop("args", [])
             res = compare_files(

dir_content_diff/base_comparators.py

@@ -19,10 +19,11 @@
 from xml.etree import ElementTree
 
 import dictdiffer
+import diff_pdf_visually
 import jsonpath_ng
 import yaml
 from dicttoxml import dicttoxml
-from diff_pdf_visually import pdf_similar
+from diff_pdf_visually import pdfdiff_pages
 
 from dir_content_diff.util import diff_msg_formatter
 
@@ -618,35 +619,114 @@ def diff(self, ref, comp, *args, **kwargs):
 
         Keyword Args:
             threshold (int): The threshold used to compare the images.
-            tempdir (pathlib.Path): Empty directory where the temporary images will be exported.
+            tempdir (pathlib.Path): Directory in which a new ``dir-diff` directory will be created
+                to export the debug images.
             dpi (int): The resolution used to convert the PDF files into images.
             verbosity (int): The log verbosity.
             max_report_pagenos (int): Only this number of the different pages will be logged (only
                 used if the verbosity is greater than 1).
             num_threads (int): If set to 2 (the default), the image conversion are processed in
                 parallel. If set to 1 it is processed sequentially.
         """
+        res = pdfdiff_pages(ref, comp, *args, **kwargs)
+        if not res:
+            return False
+        else:
+            return res
+
+    def __call__(self, ref_file, comp_file, *args, **kwargs):
+        """Process arguments before calling the diff method."""
         tempdir = kwargs.pop("tempdir", None)
         if tempdir is not None:
             relative_parts = []
-            for i, j in zip(ref.parts[::-1], comp.parts[::-1]):  # pragma: no branch
+            for i, j in zip(
+                ref_file.parts[::-1], comp_file.parts[::-1]
+            ):  # pragma: no branch
                 if i != j:
                     break
                 relative_parts.append(i)
+            if relative_parts and relative_parts[-1] == Path(tempdir).root:
+                relative_parts.pop()
             if not relative_parts:
-                relative_parts.append(comp.name)
-            relative_parts[-1] = "diff-pdf-" + relative_parts[-1]
+                relative_parts.append(comp_file.name)
+            relative_parts.append("diff-pdf")
             new_tempdir = Path(tempdir) / Path(*relative_parts[::-1])
 
             # Deduplicate name if needed
+            last_part = str(relative_parts[-1])
             num = 1
             while True:
-                try:
+                root = Path(tempdir) / relative_parts[-1]
+                if not root.exists():
                     new_tempdir.mkdir(parents=True, exist_ok=False)
                     break
-                except FileExistsError:
-                    new_tempdir = new_tempdir.with_name(new_tempdir.name + f"_{num}")
-                    num += 1
+                relative_parts[-1] = last_part + f"_{num}"
+                new_tempdir = Path(tempdir) / Path(*relative_parts[::-1])
+                num += 1
 
             kwargs["tempdir"] = new_tempdir
-        return not pdf_similar(ref, comp, *args, **kwargs)
+
+        try:
+            # Update default verbosity
+            if "verbosity" not in kwargs:
+                current_default_verbosity = int(
+                    diff_pdf_visually.constants.DEFAULT_VERBOSITY
+                )
+                try:
+                    if diff_pdf_visually.diff.pdfdiff_pages.__defaults__[1] is None:
+                        diff_pdf_visually.constants.DEFAULT_VERBOSITY = 0
+                    else:
+                        kwargs["verbosity"] = 0
+                finally:
+                    diff_pdf_visually.constants.DEFAULT_VERBOSITY = (
+                        current_default_verbosity
+                    )
+            return super().__call__(ref_file, comp_file, *args, **kwargs)
+        finally:
+            diff_pdf_visually.constants.DEFAULT_VERBOSITY = current_default_verbosity
+
+    def report(
+        self,
+        ref_file,
+        comp_file,
+        formatted_differences,
+        diff_args,
+        diff_kwargs,
+        load_kwargs=None,
+        format_data_kwargs=None,
+        filter_kwargs=None,
+        format_diff_kwargs=None,
+        sort_kwargs=None,
+        concat_kwargs=None,
+        **kwargs,
+    ):  # pylint: disable=too-many-arguments
+        """Add specific information before calling the default method."""
+        if formatted_differences:
+            if isinstance(formatted_differences, str):
+                formatted_differences = (
+                    "The following pages are the most different: "
+                    + formatted_differences.replace("\n", ", ")
+                )
+            if "tempdir" in diff_kwargs:
+                formatted_differences += (
+                    "\nThe visual differences can be found here: "
+                    + str(diff_kwargs["tempdir"])
+                )
+        return super().report(
+            ref_file,
+            comp_file,
+            formatted_differences,
+            diff_args,
+            diff_kwargs,
+            load_kwargs=load_kwargs,
+            format_data_kwargs=format_data_kwargs,
+            filter_kwargs=filter_kwargs,
+            format_diff_kwargs=format_diff_kwargs,
+            sort_kwargs=sort_kwargs,
+            concat_kwargs=concat_kwargs,
+            **kwargs,
+        )
+
+    def format_diff(self, difference, **kwargs):
+        """Format one element difference."""
+        return str(difference)

dir_content_diff/cli/__init__.py

@@ -0,0 +1,164 @@
+"""Main entry point of the Command Line Interface for the dir-content-diff package."""
+
+# LICENSE HEADER MANAGED BY add-license-header
+# Copyright (c) 2023-2024 Blue Brain Project, EPFL.
+#
+# This file is part of dir-content-diff.
+# See https://github.com/BlueBrain/dir-content-diff for further info.
+#
+# SPDX-License-Identifier: Apache-2.0
+# LICENSE HEADER MANAGED BY add-license-header
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+import click
+from yaml import safe_load
+
+from dir_content_diff import compare_files
+from dir_content_diff import compare_trees
+from dir_content_diff import export_formatted_file
+from dir_content_diff import pick_comparator
+from dir_content_diff.util import LOGGER
+
+
+def setup_logger(level: str = "info"):
+    """Setup application logger."""
+    level = level.lower()
+    levels = {
+        "debug": logging.DEBUG,
+        "info": logging.INFO,
+        "warning": logging.WARNING,
+        "error": logging.ERROR,
+        "critical": logging.CRITICAL,
+    }
+    logging.basicConfig(
+        format="%(levelname)s - %(message)s",
+        # format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        # datefmt="%Y-%m-%dT%H:%M:%S",
+        level=levels[level],
+    )
+
+
+def load_config(ctx, param, value):
+    """Load configuration from the given path."""
+    ctx.config = {}
+    if value is not None:
+        try:
+            ctx.config = json.loads(value)
+        except Exception as json_exc:
+            try:
+                path = Path(value)
+                if not path.exists():
+                    msg = f"The file '{path}' does not exist."
+                    raise FileNotFoundError(msg)
+                with path.open() as f:
+                    ctx.config = safe_load(f.read())
+            except Exception as path_exc:
+                raise path_exc from json_exc
+
+
+@click.command(
+    short_help="Compare the two given inputs",
+    epilog=(
+        "Note: When comparing directories, only the files located in the REFERENCE_INPUT will be "
+        "considered in the COMPARED_INPUT."
+    ),
+)
+@click.argument("reference_input", type=click.Path(dir_okay=True, exists=True))
+@click.argument("compared_input", type=click.Path(dir_okay=True, exists=True))
+@click.option(
+    "-c",
+    "--config",
+    callback=load_config,
+    is_eager=True,
+    expose_value=False,
+    show_default=True,
+    help="Read option defaults from the given JSON string or the specified YAML file.",
+)
+@click.option(
+    "--log-level",
+    type=click.Choice(["debug", "info", "warning", "error", "critical"]),
+    default="info",
+    help="The logger level.",
+)
+@click.option(
+    "-f/-nf",
+    "--export-formatted-files/--no-export-formatted-files",
+    default=False,
+    help="Export the files after they were formatted by the comparators.",
+)
+@click.option(
+    "-s/-ns",
+    "--sort-diffs/--no-sort-diffs",
+    default=False,
+    help="Sort the differences by file name.",
+)
+@click.version_option()
+@click.pass_context
+def main(ctx, *args, **kwargs):
+    """A command line tool for directory or file comparison.
+
+    REFERENCE_INPUT is the file or directory considered as the reference for comparison.
+
+    COMPARED_INPUT is the file or directory considered as the compared input.
+    """
+    log_level = kwargs.pop("log_level", "info")
+
+    setup_logger(log_level)
+
+    LOGGER.debug("Running the following command: %s", " ".join(sys.argv))
+    LOGGER.debug("Running from the following folder: %s", Path.cwd())
+
+    ref = Path(kwargs.pop("reference_input"))
+    comp = Path(kwargs.pop("compared_input"))
+    input_diff(
+        ref,
+        comp,
+        ctx.config,
+        kwargs.pop("export_formatted_files", False),
+        kwargs.pop("sort_diffs", False),
+    )
+
+
+def input_diff(ref, comp, config, export_formatted_files=False, sort_diffs=False):
+    """Compute and display differences from given inputs."""
+    ref = Path(ref)
+    comp = Path(comp)
+    ref_is_dir = ref.is_dir()
+    comp_is_dir = comp.is_dir()
+    if ref_is_dir != comp_is_dir:
+        msg = "The reference and compared inputs must both be either two directories or two files."
+        raise ValueError(msg)
+
+    if ref_is_dir:
+        res = compare_trees(
+            ref,
+            comp,
+            specific_args=config,
+            export_formatted_files=export_formatted_files,
+        )
+        if sort_diffs:
+            res = sorted(res.items(), key=lambda x: x[0])
+    else:
+        comparator_name = config.pop("comparator", None)
+        comparator = pick_comparator(
+            comparator=comparator_name,
+            suffix=ref.suffix,
+        )
+        res = {str(ref): compare_files(ref, comp, comparator, **config)}
+        if export_formatted_files:
+            export_formatted_file(ref, **config)
+            export_formatted_file(comp, **config)
+
+    if res:
+        LOGGER.info(
+            "Differences found between '%s' and '%s':\n\n\n%s",
+            ref,
+            comp,
+            ("\n\n\n".join([i[1] for i in res.items()])),
+        )
+    else:
+        LOGGER.info("No difference found between '%s' and '%s'", ref, comp)

pyproject.toml

@@ -21,6 +21,7 @@ classifiers = [
 ]
 dynamic = ["version", "optional-dependencies"]
 dependencies = [
+    "click>=8",
     "dictdiffer>=0.8",
     "dicttoxml>=1.7.12",
     "diff_pdf_visually>=1.7",
@@ -34,6 +35,9 @@ Homepage = "https://dir-content-diff.readthedocs.io"
 Repository = "https://github.com/BlueBrain/dir-content-diff"
 Tracker = "https://github.com/BlueBrain/dir-content-diff/issues"
 
+[project.scripts]
+dir-content-diff = "dir_content_diff.cli:main"
+
 [project.entry-points.pytest11]
 dir-content-diff = "dir_content_diff.pytest_plugin"