prosediff 0.1.0__py3-none-any.whl

prosediff/__init__.py

@@ -0,0 +1,6 @@
+"""Side-by-side HTML diff between two commits of a git repository."""
+
+from prosediff.diff import Comparison, FileDiff, Row, compare, compare_paths
+from prosediff.render import render
+
+__all__ = ["Comparison", "FileDiff", "Row", "compare", "compare_paths", "render"]

prosediff/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from prosediff.cli import main
+
+sys.exit(main())

prosediff/cli.py

@@ -0,0 +1,244 @@
+"""Command line: prosediff REPO BASE [TARGET], or prosediff --files OLD NEW."""
+
+import argparse
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+import git
+
+from prosediff.diff import (
+    CONTEXT,
+    MAX_HIDDEN,
+    MOVE_SIMILARITY,
+    PROSE_CONTEXT,
+    FilterError,
+    compare,
+    compare_paths,
+)
+from prosediff.render import ALIGNMENTS, render
+from prosediff.sources import DOCX_CHANGES, SourceError
+
+PROG = "prosediff"
+
+
+def package_version() -> str:
+    try:
+        return version(PROG)
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog=PROG,
+        description="Write an HTML page showing the differences between two "
+        "commits of a git repository (or a commit and the working tree or the "
+        "index), or between two files or two folders, side by side.",
+        epilog="Examples: prosediff . HEAD~1 HEAD; prosediff . HEAD --untracked; "
+        "prosediff --files draft_v1.docx draft_v2.docx",
+    )
+    ap.add_argument(
+        "repo",
+        metavar="REPO|OLD",
+        help="the repository (or any folder inside it); with --files, the old file or folder",
+    )
+    ap.add_argument(
+        "base",
+        metavar="BASE|NEW",
+        help="the older commit: hash, branch, tag, HEAD~2, ...; with "
+        "--files, the new file or folder",
+    )
+    ap.add_argument(
+        "target",
+        nargs="?",
+        metavar="TARGET",
+        help="the newer commit; without it, BASE is compared with the "
+        "working tree (tracked files only), as git diff BASE does",
+    )
+    ap.add_argument(
+        "--files", action="store_true", help="compare two files or two folders, outside git"
+    )
+    ap.add_argument(
+        "-p",
+        "--path",
+        action="append",
+        dest="paths",
+        default=[],
+        metavar="PATH",
+        help="restrict the diff to this path (repeatable)",
+    )
+    ap.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path("diff.html"),
+        help="output file (default: diff.html)",
+    )
+    lines = ap.add_mutually_exclusive_group()
+    lines.add_argument(
+        "-U",
+        "--context",
+        type=int,
+        default=None,
+        metavar="N",
+        help="unchanged lines shown around each change, in every file (default: "
+        f"{PROSE_CONTEXT} in Markdown files and Word documents, whose lines are "
+        f"paragraphs, {CONTEXT} in the others); the page can reveal the rest",
+    )
+    lines.add_argument("--full", action="store_true", help="show every line of the changed files")
+    ap.add_argument(
+        "--max-hidden",
+        type=int,
+        default=MAX_HIDDEN,
+        metavar="N",
+        help="unchanged lines embedded per gap, for the page to reveal; "
+        f"longer gaps are left out (default: {MAX_HIDDEN:,})",
+    )
+    ap.add_argument(
+        "--align",
+        choices=ALIGNMENTS,
+        default="left",
+        help="alignment of wrapped lines (default: left)",
+    )
+    ap.add_argument(
+        "--md-filter",
+        metavar="COMMAND",
+        help="shell command both versions of every Markdown file are "
+        "piped through before comparing",
+    )
+    ap.add_argument(
+        "--cached",
+        "--staged",
+        action="store_true",
+        help="compare BASE with the index (the staged changes) instead of the working tree",
+    )
+    ap.add_argument(
+        "--untracked",
+        action="store_true",
+        help="include untracked files not excluded by .gitignore (working tree only)",
+    )
+    ap.add_argument(
+        "-w",
+        "--ignore-whitespace",
+        action="store_true",
+        help="ignore whitespace when comparing lines",
+    )
+    ap.add_argument(
+        "--fold-comments",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="in Markdown files and Word documents, show each comment "
+        "as a marker whose tooltip is the comment, and list them in a panel "
+        "(default: on; --no-fold-comments compares the comment markup as text)",
+    )
+    ap.add_argument(
+        "--empty-comments",
+        action="store_true",
+        help="show the comments that have no text too (left out by default)",
+    )
+    ap.add_argument(
+        "--docx-changes",
+        choices=DOCX_CHANGES,
+        default="accept",
+        help="the tracked changes of Word documents: accept them, reject them, "
+        "or show them as markup (default: accept)",
+    )
+    ap.add_argument(
+        "--move-similarity",
+        type=float,
+        default=MOVE_SIMILARITY,
+        metavar="X",
+        help="how alike, above 0 and at most 1, an edited line must be to where it "
+        "reappears to count as moved: the share of its words and punctuation in "
+        f"common, in order (default: {MOVE_SIMILARITY}; 1: only lines moved unchanged)",
+    )
+    ap.add_argument(
+        "--by-sentence",
+        action="store_true",
+        help="compare the prose of Markdown files and Word documents sentence by "
+        "sentence instead of paragraph by paragraph: moved sentences are recognised, "
+        "lines are labelled 12.1, 12.2, ...",
+    )
+    ap.add_argument(
+        "--sentence-language",
+        default="en",
+        metavar="CODE",
+        help="the language whose rules split sentences with --by-sentence "
+        "(default: en; e.g. it, de, fr; others fall back to a simple rule)",
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {package_version()}")
+    args = ap.parse_args(argv)
+
+    if args.context is not None and args.context < 0:
+        ap.error("--context must be 0 or more")
+    if args.max_hidden < 0:
+        ap.error("--max-hidden must be 0 or more")
+    if not 0 < args.move_similarity <= 1:
+        ap.error("--move-similarity must be above 0 and at most 1")
+    if args.files:
+        if args.target:
+            ap.error("--files compares OLD with NEW: give no TARGET")
+        if args.cached or args.untracked:
+            ap.error("--cached and --untracked need a git repository, not --files")
+    if args.cached and args.target:
+        ap.error("--cached compares BASE with the index: give no TARGET")
+    if args.untracked and (args.target or args.cached):
+        ap.error("--untracked needs the working tree: give no TARGET and no --cached")
+
+    options = dict(
+        paths=args.paths,
+        context=None if args.full else ("auto" if args.context is None else args.context),
+        md_filter=args.md_filter,
+        ignore_whitespace=args.ignore_whitespace,
+        fold_comments_md=args.fold_comments,
+        empty_comments=args.empty_comments,
+        max_hidden=args.max_hidden,
+        docx_changes=args.docx_changes,
+        move_similarity=args.move_similarity,
+        by_sentence=args.by_sentence,
+        sentence_language=args.sentence_language,
+    )
+    try:
+        if args.files:
+            comparison = compare_paths(args.repo, args.base, **options)
+        else:
+            comparison = compare(
+                Path(args.repo),
+                args.base,
+                args.target,
+                cached=args.cached,
+                untracked=args.untracked,
+                **options,
+            )
+    except git.InvalidGitRepositoryError:
+        print(
+            f"{PROG}: not a git repository: {args.repo} (use --files to compare files or folders)",
+            file=sys.stderr,
+        )
+        return 1
+    except git.NoSuchPathError:
+        print(f"{PROG}: no such folder: {args.repo}", file=sys.stderr)
+        return 1
+    except (git.BadName, ValueError) as e:
+        print(f"{PROG}: not a commit: {e}", file=sys.stderr)
+        return 1
+    except (FilterError, SourceError) as e:
+        print(f"{PROG}: {e}", file=sys.stderr)
+        return 1
+
+    # newline="\n" keeps the page LF on Windows too.
+    with open(args.output, "w", encoding="utf-8", newline="\n") as f:
+        f.write(render(comparison, args.paths, align=args.align))
+
+    c = comparison
+    files = "file" if len(c.files) == 1 else "files"
+    print(
+        f"{PROG}: {c.base.short}..{c.target.short}: {len(c.files):,} {files}, "
+        f"+{c.additions:,} -{c.deletions:,} -> {args.output}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

prosediff/comments.py

@@ -0,0 +1,206 @@
+"""Pandoc comment spans: folded into markers, and listed in a panel.
+
+pandoc --track-changes=all writes a Word comment as
+[note]{.comment-start id=... author="A" date=...}anchor[]{.comment-end id=...}.
+Folding replaces each comment-start span with one character of the Unicode
+private use area standing for (author, note), and drops comment-end: the
+comment is then compared like a word, the same comment matches on both sides
+even when a new conversion renumbered its id, and a filter cannot cut it in
+two. The characters become markers when the page is built.
+"""
+
+import re
+from dataclasses import dataclass
+
+from markupsafe import Markup
+
+PUA_FIRST, PUA_LAST = 0xE000, 0xF8FF
+PLACEHOLDER = re.compile(f"[{chr(PUA_FIRST)}-{chr(PUA_LAST)}]")
+COMMENT_MARK = "\N{SPEECH BALLOON}"
+# A comment only the new side has: added since the base.
+NEW_COMMENT_MARK = "\N{SQUARED NEW}"
+
+COMMENT_CLASS = re.compile(r"^\{\s*\.(comment-start|comment-end)\b")
+AUTHOR = re.compile(r'\bauthor="((?:[^"\\]|\\.)*)"')
+DATE = re.compile(r'\bdate="(\d{4}-\d\d-\d\d)T(\d\d:\d\d)')
+ESCAPE = re.compile(r"\\([\\`*_{}\[\]()#+\-.!|'\"<>~^$])")
+
+
+@dataclass
+class Comment:
+    author: str
+    text: str
+    date: str = ""  # "YYYY-MM-DD HH:MM", as Word stamped it
+
+    @property
+    def label(self) -> str:
+        """The comment in one line, for screen readers."""
+        who = f"comment by {self.author}" if self.author else "comment"
+        when = f", {self.date}" if self.date else ""
+        return f"{who}{when}: {self.text or '(no text)'}"
+
+
+@dataclass
+class CommentEntry:
+    """One comment of one file, for the comments panel."""
+
+    author: str
+    text: str
+    status: str  # "new", "removed" or "unchanged"
+    path: str
+    anchor: str  # id of the row it sits in
+    line: int | None
+    date: str = ""
+    label: str = ""  # the line as the gutter shows it ("12.3")
+
+    @property
+    def icon(self) -> str:
+        return NEW_COMMENT_MARK if self.status == "new" else COMMENT_MARK
+
+
+class Comments:
+    """The comments folded out of a comparison, each behind one placeholder.
+
+    A comment is identified by its author and text, not by its id: the ids
+    are renumbered each time a document is converted, and the same comment
+    must compare equal on both sides.
+    """
+
+    def __init__(self) -> None:
+        self._by_key: dict[tuple[str, str], str] = {}
+        self._items: list[Comment] = []
+
+    def placeholder(self, author: str, text: str, date: str = "") -> str | None:
+        key = (author, text)
+        if key not in self._by_key:
+            if PUA_FIRST + len(self._items) > PUA_LAST:
+                return None  # out of placeholders: leave the span as it is
+            self._by_key[key] = chr(PUA_FIRST + len(self._items))
+            self._items.append(Comment(author, text, date))
+        return self._by_key[key]
+
+    def get(self, placeholder: str) -> Comment:
+        return self._items[ord(placeholder) - PUA_FIRST]
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+
+def match_bracket(s: str, i: int) -> int:
+    """Index of the ']' closing the '[' at s[i], or -1."""
+    depth = 0
+    j = i
+    while j < len(s):
+        c = s[j]
+        if c == "\\":
+            j += 2
+            continue
+        if c == "[":
+            depth += 1
+        elif c == "]":
+            depth -= 1
+            if depth == 0:
+                return j
+        j += 1
+    return -1
+
+
+def match_attrs(s: str, i: int) -> int:
+    """Index of the '}' closing the attribute block opened at s[i], or -1.
+
+    The block may span lines, but not a blank line.
+    """
+    in_quote = False
+    j = i + 1
+    while j < len(s):
+        c = s[j]
+        if c == "\\":
+            j += 2
+            continue
+        if c == '"':
+            in_quote = not in_quote
+        elif c == "}" and not in_quote:
+            return j
+        elif c == "\n" and not in_quote and s[j + 1 : j + 2] == "\n":
+            return -1
+        j += 1
+    return -1
+
+
+def fold_comments(text: str, comments: Comments, keep_empty: bool = False) -> str:
+    """Replace the pandoc comment spans of a Markdown text with placeholders.
+
+    A comment without text is left out, unless keep_empty.
+    """
+    out = []
+    i = 0
+    while i < len(text):
+        c = text[i]
+        if c == "\\":
+            out.append(text[i : i + 2])
+            i += 2
+            continue
+        if c == "[":
+            close = match_bracket(text, i)
+            if close != -1 and text[close + 1 : close + 2] == "{":
+                end = match_attrs(text, close + 1)
+                attrs = text[close + 1 : end + 1] if end != -1 else ""
+                m = COMMENT_CLASS.match(attrs)
+                if m:
+                    if m[1] == "comment-end":
+                        i = end + 1
+                        continue
+                    author = AUTHOR.search(attrs)
+                    date = DATE.search(attrs)
+                    # Markdown escapes (\[ \* \_ ...) are not part of the comment
+                    note = ESCAPE.sub(r"\1", " ".join(text[i + 1 : close].split()))
+                    if not note and not keep_empty:
+                        # a comment with no text says nothing: left out
+                        i = end + 1
+                        continue
+                    mark = comments.placeholder(
+                        author[1] if author else "",
+                        note,
+                        f"{date[1]} {date[2]}" if date else "",
+                    )
+                    if mark is not None:
+                        out.append(mark)
+                        i = end + 1
+                        continue
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def plain(text: str) -> str:
+    """Text for a tooltip: each folded comment shown as a speech balloon."""
+    return PLACEHOLDER.sub(COMMENT_MARK, text)
+
+
+MARKER = Markup(
+    '<span class="comment{}" tabindex="0" role="note" data-author="{}" data-date="{}" '
+    'data-text="{}" aria-label="{}">{}</span>'
+)
+
+
+def show_comments(markup: Markup, comments: Comments, new: frozenset[str] = frozenset()) -> Markup:
+    """Replace the placeholders of a cell with comment markers.
+
+    The page shows the author, the comment and its date when a marker is
+    hovered or focused. The comments in new (placeholders) were added since
+    the base and get their own icon. Tooltips never hold placeholders (see
+    plain), so every one left in the markup is in the text of the line.
+    """
+
+    def marker(m: re.Match) -> str:
+        c = comments.get(m[0])
+        is_new = m[0] in new
+        label = ("new " if is_new else "") + c.label
+        icon = NEW_COMMENT_MARK if is_new else COMMENT_MARK
+        return str(MARKER.format(" new" if is_new else "", c.author, c.date, c.text, label, icon))
+
+    return Markup(PLACEHOLDER.sub(marker, str(markup)))
+
+
+def placeholders_in(markup: Markup | str) -> list[str]:
+    return PLACEHOLDER.findall(str(markup))