xml-cmpr 0.2.0__py3-none-any.whl

xml_cmpr/__init__.py

@@ -0,0 +1,76 @@
+"""Comparaison de documents XML issus de deux sources différentes.
+
+Le pipeline se lit en trois étapes indépendantes :
+
+```python
+from xml_cmpr import ReportFormat, render, run_comparison, write_report
+
+summary = run_comparison(source_a, source_b)   # analyse   -> RunSummary
+corps = render(summary, ReportFormat.JSON)     # formatage -> str (JSON ou Markdown)
+write_report(summary, sortie, "md")            # écriture  -> Path (facultatif)
+```
+
+`render` retourne une chaîne : elle peut aussi bien partir dans une réponse HTTP
+que vers le traitement suivant, sans jamais toucher au disque.
+
+Les trois exceptions du paquet sont exportées ici : `ExcludeError` (XPath d'exclusion
+invalide) et `ArchiveError` (source illisible, ou `ArchiveSizeError` pour une archive au-delà de
+`MAX_EXTRACTED_SIZE` ou de `MAX_ENTRIES`) viennent de ce que l'appelant a fourni ;
+`CanonicalError` ne traverse pas `run_comparison`, la campagne la reporte fichier par
+fichier.
+"""
+
+from .archive import (
+    MAX_ENTRIES,
+    MAX_EXTRACTED_SIZE,
+    ArchiveError,
+    ArchiveSizeError,
+    as_directory,
+    is_archive,
+)
+from .campaign import run_comparison
+from .canonical import CanonicalError, Canonicalizer, ExcludeError
+from .diff import diff_documents
+from .discovery import discover
+from .model import Difference, FileResult, Kind, Node, RunSummary, Status
+from .report import (
+    DEFAULT_FORMATS,
+    FILENAMES,
+    ReportFormat,
+    parse_format,
+    render,
+    render_json,
+    render_markdown,
+    write_report,
+    write_reports,
+)
+
+__all__ = [
+    "DEFAULT_FORMATS",
+    "FILENAMES",
+    "MAX_ENTRIES",
+    "MAX_EXTRACTED_SIZE",
+    "ArchiveError",
+    "ArchiveSizeError",
+    "CanonicalError",
+    "Canonicalizer",
+    "Difference",
+    "ExcludeError",
+    "FileResult",
+    "Kind",
+    "Node",
+    "ReportFormat",
+    "RunSummary",
+    "Status",
+    "as_directory",
+    "diff_documents",
+    "discover",
+    "is_archive",
+    "parse_format",
+    "render",
+    "render_json",
+    "render_markdown",
+    "run_comparison",
+    "write_report",
+    "write_reports",
+]

xml_cmpr/archive.py

@@ -0,0 +1,176 @@
+"""Sources fournies sous forme d'archive ZIP.
+
+Une source peut être un répertoire ou un fichier ZIP. Le ZIP est extrait dans un
+répertoire temporaire, supprimé à la fin de la campagne, et le reste du pipeline
+travaille sur ce répertoire comme sur n'importe quel autre : l'archive ne change
+rien à la découverte, à la canonicalisation ni au diff.
+
+L'extraction est bornée : une archive dont le contenu décompressé dépasse
+`MAX_EXTRACTED_SIZE`, ou qui compte plus de `MAX_ENTRIES` entrées, est refusée avant
+qu'un seul octet ne soit écrit. Chaque borne se lève explicitement (`size_limit=None`,
+`entry_limit=None`), jamais par défaut.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import zipfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path, PurePosixPath
+from typing import Literal
+
+#: Taille décompressée maximale d'une archive, par source : 1 Gio.
+MAX_EXTRACTED_SIZE = 1024**3
+
+#: Nombre maximal d'entrées (fichiers et répertoires) d'une archive, par source.
+MAX_ENTRIES = 100_000
+
+
+class ArchiveError(Exception):
+    """L'archive est illisible, corrompue, ou contient des chemins suspects."""
+
+
+class ArchiveSizeError(ArchiveError):
+    """L'archive dépasse une borne : volume décompressé ou nombre d'entrées.
+
+    `measure` dit laquelle (`"bytes"` ou `"entries"`) ; `size` et `limit` sont exprimés
+    dans cette unité.
+    """
+
+    def __init__(
+        self, message: str, size: int, limit: int, measure: Literal["bytes", "entries"]
+    ) -> None:
+        super().__init__(message)
+        self.size = size
+        self.limit = limit
+        self.measure = measure
+
+
+def is_archive(path: Path) -> bool:
+    """Vrai si `path` est un fichier ZIP lisible."""
+    return path.is_file() and zipfile.is_zipfile(path)
+
+
+@contextmanager
+def as_directory(
+    source: Path,
+    *,
+    label: str = "source",
+    size_limit: int | None = MAX_EXTRACTED_SIZE,
+    entry_limit: int | None = MAX_ENTRIES,
+) -> Iterator[Path]:
+    """Donne un répertoire à comparer, que `source` soit un répertoire ou un ZIP.
+
+    Pour un ZIP, l'extraction a lieu dans un répertoire temporaire supprimé à la
+    sortie du contexte ; pour un répertoire, le chemin est rendu tel quel.
+
+    `size_limit` borne, en octets, le contenu décompressé d'un ZIP, et `entry_limit` son
+    nombre d'entrées (`ArchiveSizeError` au-delà) ; `None` lève la borne concernée. Un
+    répertoire n'est jamais concerné : rien n'est copié.
+    """
+    if source.is_dir():
+        yield source
+        return
+    if is_archive(source):
+        with _extracted(
+            source, label=label, size_limit=size_limit, entry_limit=entry_limit
+        ) as root:
+            yield root
+        return
+    if source.is_file():
+        raise ArchiveError(f"n'est ni un répertoire ni une archive ZIP : {source}")
+    raise ArchiveError(f"répertoire ou archive introuvable : {source}")
+
+
+@contextmanager
+def _extracted(
+    archive_path: Path, *, label: str, size_limit: int | None, entry_limit: int | None
+) -> Iterator[Path]:
+    with tempfile.TemporaryDirectory(prefix=f"xml-cmpr-{label}-") as tmp:
+        root = Path(tmp)
+        try:
+            with zipfile.ZipFile(archive_path) as archive:
+                _check_members(archive_path, archive)
+                _check_limits(archive_path, archive, size_limit, entry_limit)
+                archive.extractall(root)
+        except (zipfile.BadZipFile, OSError) as err:
+            raise ArchiveError(f"archive illisible : {archive_path} ({err})") from err
+        yield _strip_single_root(root)
+
+
+def _check_members(archive_path: Path, archive: zipfile.ZipFile) -> None:
+    """Refuse les entrées qui sortiraient du répertoire d'extraction.
+
+    `extractall` neutralise déjà ces chemins, mais silencieusement : mieux vaut
+    une erreur explicite qu'une extraction dont il manque des fichiers.
+    """
+    for name in archive.namelist():
+        pure = PurePosixPath(name)
+        if pure.is_absolute() or name.startswith("\\") or ".." in pure.parts:
+            raise ArchiveError(f"chemin d'entrée suspect dans {archive_path} : {name}")
+
+
+def _check_limits(
+    archive_path: Path,
+    archive: zipfile.ZipFile,
+    size_limit: int | None,
+    entry_limit: int | None,
+) -> None:
+    """Refuse l'archive au-delà de `entry_limit` entrées ou de `size_limit` octets.
+
+    Les deux bornes se complètent : des millions de fichiers vides pèsent zéro octet et
+    épuisent pourtant les inodes du répertoire temporaire.
+
+    Les tailles viennent de l'annuaire central, donc sans rien décompresser. Une
+    archive qui sous-déclare ses tailles ne passe pas pour autant : `zipfile` ne
+    produit jamais plus d'octets que la taille déclarée d'une entrée, et le CRC de
+    l'entrée tronquée échoue (`BadZipFile`, donc `ArchiveError`).
+    """
+    infos = archive.infolist()
+    if entry_limit is not None and len(infos) > entry_limit:
+        raise ArchiveSizeError(
+            f"archive aux entrées trop nombreuses : {archive_path} — {_count(len(infos))} "
+            f"entrées, pour une limite de {_count(entry_limit)}",
+            len(infos),
+            entry_limit,
+            "entries",
+        )
+    size = sum(info.file_size for info in infos)
+    if size_limit is not None and size > size_limit:
+        raise ArchiveSizeError(
+            f"archive trop volumineuse : {archive_path} — {_human(size)} une fois "
+            f"décompressée, pour une limite de {_human(size_limit)}",
+            size,
+            size_limit,
+            "bytes",
+        )
+
+
+def _count(n: int) -> str:
+    """`100000` -> `"100 000"`, avec une espace fine insécable comme séparateur."""
+    return f"{n:_}".replace("_", "\u202f")
+
+
+def _human(size: int) -> str:
+    """`1610612736` -> `"1,5 Gio"` : une taille lisible dans un message d'erreur."""
+    value = float(size)
+    for unit in ("o", "Kio", "Mio", "Gio"):
+        if value < 1024 or unit == "Gio":
+            break
+        value /= 1024
+    text = f"{value:.0f}" if value == int(value) else f"{value:.1f}".replace(".", ",")
+    return f"{text} {unit}"
+
+
+def _strip_single_root(root: Path) -> Path:
+    """Descend dans l'unique répertoire de tête d'une archive, s'il y en a un.
+
+    Un ZIP enveloppe souvent son contenu dans un répertoire dont le nom diffère
+    d'une chaîne de production à l'autre ; le garder ferait échouer l'appariement,
+    qui se fait sur le chemin relatif à la racine de la source.
+    """
+    entries = [entry for entry in root.iterdir() if entry.name != "__MACOSX"]
+    if len(entries) == 1 and entries[0].is_dir():
+        return entries[0]
+    return root

xml_cmpr/campaign.py

@@ -0,0 +1,77 @@
+"""L'analyse : comparer deux répertoires et produire le bilan de la campagne.
+
+Première étape du pipeline `analyse -> formatage -> écriture`. Rien ici ne connaît
+le format du rapport ni le système de fichiers de sortie : `run_comparison` rend un
+`RunSummary`, que l'appelant formate (`report.render`) et écrit s'il le souhaite
+(`report.write_report`).
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from .canonical import CanonicalError, Canonicalizer
+from .diff import diff_documents
+from .discovery import discover
+from .model import FileResult, RunSummary, Status
+
+
+def run_comparison(
+    source_a: Path,
+    source_b: Path,
+    *,
+    pattern: str = "*.xml",
+    recursive: bool = True,
+    keep_whitespace: bool = False,
+    exclude_xpaths: list[str] | None = None,
+    max_diffs_per_file: int = 50,
+    verbose: bool = False,
+    label_a: Path | None = None,
+    label_b: Path | None = None,
+) -> RunSummary:
+    """Compare les deux répertoires et retourne le bilan de la campagne.
+
+    `label_a` / `label_b` remplacent les chemins affichés au rapport, pour nommer
+    l'archive d'origine plutôt que le répertoire temporaire où elle a été extraite.
+    """
+    pairing = discover(source_a, source_b, pattern=pattern, recursive=recursive)
+    summary = RunSummary(
+        source_a=label_a or source_a, source_b=label_b or source_b, skipped=pairing.skipped
+    )
+
+    with Canonicalizer(
+        keep_whitespace=keep_whitespace,
+        exclude_xpaths=exclude_xpaths,
+    ) as canon:
+        for relative, path_a, path_b in pairing.matched:
+            if verbose:
+                print(f"… {relative}", file=sys.stderr)
+            summary.results.append(
+                _compare_one(canon, relative, path_a, path_b, max_diffs_per_file)
+            )
+    return summary
+
+
+def _compare_one(
+    canon: Canonicalizer,
+    relative: str,
+    path_a: Path,
+    path_b: Path,
+    max_diffs: int,
+) -> FileResult:
+    try:
+        tree_a, fingerprint_a = canon.load(path_a)
+        tree_b, fingerprint_b = canon.load(path_b)
+    except CanonicalError as err:
+        return FileResult(relative, Status.ERROR, error=str(err))
+
+    if fingerprint_a == fingerprint_b:
+        return FileResult(relative, Status.IDENTICAL)
+
+    differences = diff_documents(tree_a, tree_b)
+    truncated = 0
+    if 0 < max_diffs < len(differences):
+        truncated = len(differences) - max_diffs
+        differences = differences[:max_diffs]
+    return FileResult(relative, Status.DIFFERENT, differences=differences, truncated=truncated)

xml_cmpr/canonical.py

@@ -0,0 +1,111 @@
+"""Mise sous forme canonique des documents XML, via Saxon.
+
+Un unique `PySaxonProcessor` et une unique compilation de `normalize.xsl` servent toute
+la campagne : leur initialisation coûte bien plus cher qu'une transformation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from contextlib import suppress
+from importlib.resources import files
+from pathlib import Path
+from types import TracebackType
+
+from saxonche import PySaxonApiError, PySaxonProcessor, PyXPathProcessor, PyXsltExecutable
+
+from .model import Node
+
+
+class CanonicalError(Exception):
+    """Le document n'a pas pu être lu ou normalisé (XML malformé, entité absente…)."""
+
+
+class ExcludeError(Exception):
+    """L'expression XPath d'exclusion (`--exclude`) est invalide."""
+
+
+class Canonicalizer:
+    """Transforme un fichier XML en son arbre canonique et son empreinte."""
+
+    def __init__(
+        self,
+        *,
+        keep_whitespace: bool = False,
+        exclude_xpaths: list[str] | None = None,
+    ) -> None:
+        self._keep_whitespace = keep_whitespace
+        self._exclude_expr = "(" + ")|(".join(exclude_xpaths) + ")" if exclude_xpaths else None
+        self._processor: PySaxonProcessor | None = None
+        self._executable: PyXsltExecutable | None = None
+        self._xpath_processor: PyXPathProcessor | None = None
+
+    def __enter__(self) -> Canonicalizer:
+        self._processor = PySaxonProcessor(license=False)
+        self._processor.__enter__()
+        stylesheet = files("xml_cmpr.resources").joinpath("normalize.xsl").read_text("utf-8")
+        xslt = self._processor.new_xslt30_processor()
+        self._executable = xslt.compile_stylesheet(stylesheet_text=stylesheet)
+        self._executable.set_parameter(
+            "keep-whitespace", self._processor.make_boolean_value(self._keep_whitespace)
+        )
+        if self._exclude_expr is not None:
+            self._xpath_processor = self._processor.new_xpath_processor()
+            probe = self._processor.parse_xml(xml_text="<x/>")
+            self._xpath_processor.set_context(xdm_item=probe)
+            try:
+                self._xpath_processor.evaluate(self._exclude_expr)
+            except PySaxonApiError as err:
+                raise ExcludeError(_clean_message(err)) from err
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        if self._processor is not None:
+            self._processor.__exit__(exc_type, exc, tb)
+            self._processor = None
+            self._executable = None
+            self._xpath_processor = None
+
+    def canonical_json(self, path: Path) -> str:
+        """Forme canonique du document, en JSON. Deux documents sémantiquement
+        identiques donnent exactement la même chaîne."""
+        if self._executable is None or self._processor is None:
+            raise RuntimeError("Canonicalizer doit être utilisé comme context manager")
+        try:
+            node = self._processor.parse_xml(xml_file_name=str(path))
+            if node is None:
+                raise CanonicalError(f"document illisible : {path}")
+            if self._exclude_expr is not None and self._xpath_processor is not None:
+                self._xpath_processor.set_context(xdm_item=node)
+                excluded = self._xpath_processor.evaluate(self._exclude_expr)
+                if excluded is None:
+                    # `remove_parameter` lève KeyError si le paramètre n'a pas encore
+                    # été posé — malgré sa docstring, qui annonce un retour booléen.
+                    with suppress(KeyError):
+                        self._executable.remove_parameter("excluded")
+                else:
+                    self._executable.set_parameter("excluded", excluded)
+            result = self._executable.transform_to_string(xdm_node=node)
+        except PySaxonApiError as err:
+            raise CanonicalError(_clean_message(err)) from err
+        if result is None:
+            raise CanonicalError(f"transformation sans résultat : {path}")
+        return result
+
+    def load(self, path: Path) -> tuple[Node, str]:
+        """Retourne l'arbre canonique et l'empreinte du document."""
+        canonical = self.canonical_json(path)
+        fingerprint = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+        return Node.from_json(json.loads(canonical)), fingerprint
+
+
+def _clean_message(err: PySaxonApiError) -> str:
+    """Les messages Saxon sont multilignes ; on garde la première ligne utile."""
+    text = " ".join(str(err).split())
+    return text or err.__class__.__name__