pyDiffTools 0.1.36__tar.gz → 0.1.38__tar.gz

{pydifftools-0.1.36/pyDiffTools.egg-info → pydifftools-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyDiffTools
-Version: 0.1.36
+Version: 0.1.38
 Summary: Diff tools
 Author: J M Franck
 License: Copyright (c) 2015, jmfranck
@@ -109,6 +109,15 @@ included are (listed in order of fun/utility):
   Python file operations and Qt dialogs. Its automated runtime checks have
   been performed on Linux, not on Windows.
 
+  Comment bubbles use author tags such as ``<JFcom>…</JFcom>`` and
+  ``<JFcom-left>…</JFcom-left>``. Block comments can use Markdown Div classes
+  such as ``::: {.JFcom-left}``. Add a quoted six-digit hex color to the YAML
+  header (for example, ``JFcolor: '#5aa0ff'``) to enable that author's tags.
+  Before the first build, ``cpb`` offers to migrate legacy ``<comment>`` tags
+  and ``.comment-left/right`` blocks, and resolves author tags without a
+  matching color. New authors choose a hue in a Qt picker; ``cpb`` adds their
+  ``XXcolor`` field to the header.
+
   Declare a single local ``.bib`` file with ``bibliography: references.bib``
   in the Markdown YAML header; relative paths are resolved beside the
   Markdown file. Without that declaration, ``cpb`` uses a single adjacent

{pydifftools-0.1.36 → pydifftools-0.1.38}/README.rst

@@ -54,6 +54,15 @@ included are (listed in order of fun/utility):
   Python file operations and Qt dialogs. Its automated runtime checks have
   been performed on Linux, not on Windows.
 
+  Comment bubbles use author tags such as ``<JFcom>…</JFcom>`` and
+  ``<JFcom-left>…</JFcom-left>``. Block comments can use Markdown Div classes
+  such as ``::: {.JFcom-left}``. Add a quoted six-digit hex color to the YAML
+  header (for example, ``JFcolor: '#5aa0ff'``) to enable that author's tags.
+  Before the first build, ``cpb`` offers to migrate legacy ``<comment>`` tags
+  and ``.comment-left/right`` blocks, and resolves author tags without a
+  matching color. New authors choose a hue in a Qt picker; ``cpb`` adds their
+  ``XXcolor`` field to the header.
+
   Declare a single local ``.bib`` file with ``bibliography: references.bib``
   in the Markdown YAML header; relative paths are resolved beside the
   Markdown file. Without that declaration, ``cpb`` uses a single adjacent

{pydifftools-0.1.36 → pydifftools-0.1.38/pyDiffTools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyDiffTools
-Version: 0.1.36
+Version: 0.1.38
 Summary: Diff tools
 Author: J M Franck
 License: Copyright (c) 2015, jmfranck
@@ -109,6 +109,15 @@ included are (listed in order of fun/utility):
   Python file operations and Qt dialogs. Its automated runtime checks have
   been performed on Linux, not on Windows.
 
+  Comment bubbles use author tags such as ``<JFcom>…</JFcom>`` and
+  ``<JFcom-left>…</JFcom-left>``. Block comments can use Markdown Div classes
+  such as ``::: {.JFcom-left}``. Add a quoted six-digit hex color to the YAML
+  header (for example, ``JFcolor: '#5aa0ff'``) to enable that author's tags.
+  Before the first build, ``cpb`` offers to migrate legacy ``<comment>`` tags
+  and ``.comment-left/right`` blocks, and resolves author tags without a
+  matching color. New authors choose a hue in a Qt picker; ``cpb`` adds their
+  ``XXcolor`` field to the header.
+
   Declare a single local ``.bib`` file with ``bibliography: references.bib``
   in the Markdown YAML header; relative paths are resolved beside the
   Markdown file. Without that declaration, ``cpb`` uses a single adjacent

{pydifftools-0.1.36 → pydifftools-0.1.38}/pyDiffTools.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ pydifftools/citation_dialog.py
 pydifftools/command_line.py
 pydifftools/command_registry.py
 pydifftools/comment_functions.py
+pydifftools/comment_migration.py
 pydifftools/comment_tags.lua
 pydifftools/comment_tags_margin.lua
 pydifftools/comment_tags_no_comments.lua
@@ -97,6 +98,7 @@ tests/test_bibliography.py
 tests/test_browser_lifecycle.py
 tests/test_check_single_use.py
 tests/test_command_line_help.py
+tests/test_comment_migration.py
 tests/test_continuous_shutdown.py
 tests/test_forward_search.py
 tests/test_git_gd_history.py

pydifftools-0.1.38/pydifftools/comment_migration.py

@@ -0,0 +1,401 @@
+"""Pre-build migration of legacy and unregistered comment authors."""
+
+import colorsys
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import textwrap
+
+import yaml
+
+_FRONT_MATTER_RE = re.compile(
+    r"\A(\ufeff?---[ \t]*\r?\n)(.*?)(\r?\n(?:---|\.\.\.)[ \t]*(?:\r?\n|$))",
+    re.DOTALL,
+)
+_LEGACY_TAG_RE = re.compile(
+    r"(?P<closing></?)comment(?P<side>-(?:left|right))?>", re.I
+)
+_LEGACY_CLASS_RE = re.compile(r"(?<=\.)comment-(left|right)(?=[\s}])")
+_AUTHOR_TAG_RE = re.compile(
+    r"</?([A-Za-z]{2})com(?:-(?:left|right))?>", re.I
+)
+_AUTHOR_CLASS_RE = re.compile(
+    r"\.([A-Za-z]{2})com(?:-(?:left|right))?(?=[\s}])", re.I
+)
+_HEX_RE = re.compile(r"^#[0-9a-fA-F]{6}$")
+_SEED_COLOR = "#5aa0ff"
+
+
+def _front_matter(text):
+    match = _FRONT_MATTER_RE.match(text)
+    if not match:
+        if re.match(r"\A\ufeff?---[ \t]*(?:\r?\n|$)", text):
+            raise ValueError(
+                "YAML front matter starts with '---' but has no closing "
+                "delimiter"
+            )
+        return None, {}, {}
+    try:
+        metadata = yaml.safe_load(match.group(2)) or {}
+    except yaml.YAMLError as exc:
+        raise ValueError(f"invalid YAML front matter: {exc}") from exc
+    if not isinstance(metadata, dict):
+        raise ValueError("YAML front matter must contain a mapping")
+    colors = {}
+    for key, value in metadata.items():
+        initials = re.fullmatch(r"([A-Z]{2})color", str(key))
+        if not initials:
+            continue
+        if not isinstance(value, str) or not _HEX_RE.fullmatch(value):
+            raise ValueError(f"{key} must be a six-digit hex color")
+        colors[initials.group(1)] = value.lower()
+    return match, metadata, colors
+
+
+def _most_distant_hue(colors):
+    """Return the midpoint of the largest gap between existing hues."""
+    def hue(color):
+        red, green, blue = (
+            int(color[index:index + 2], 16) / 255 for index in (1, 3, 5)
+        )
+        return colorsys.rgb_to_hsv(red, green, blue)[0] * 360
+
+    if not colors:
+        return hue(_SEED_COLOR)
+    hues = sorted({hue(color) % 360 for color in colors})
+    gaps = [
+        (
+            (hues[index + 1] if index + 1 < len(hues) else hues[0] + 360)
+            - hue,
+            hue,
+        )
+        for index, hue in enumerate(hues)
+    ]
+    gap_size, start = max(gaps, key=lambda gap: (gap[0], -gap[1]))
+    return (start + gap_size / 2) % 360
+
+
+def _migration_dialog(filename, colors, legacy):
+    """Ask Qt for all migrations and return decisions without editing files."""
+    script = r"""
+import colorsys
+import json
+import re
+import sys
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtGui import (
+    QColor, QIcon, QLinearGradient, QPainter, QPen, QPixmap,
+)
+from PySide6.QtWidgets import (
+    QApplication, QComboBox, QDialog, QDialogButtonBox, QLabel,
+    QLineEdit, QMessageBox, QVBoxLayout, QWidget,
+)
+
+payload = json.loads(sys.argv[1])
+with open(sys.argv[2], encoding="utf-8", newline="") as fp:
+    text = fp.read()
+colors = payload["colors"]
+app = QApplication(sys.argv[:1])
+result = {"accepted": True, "replacements": {}, "colors": {}}
+
+def color_hue(color):
+    rgb = [int(color[i:i+2], 16) / 255 for i in (1, 3, 5)]
+    return colorsys.rgb_to_hsv(*rgb)[0] * 360
+
+def most_distant_hue(used_colors):
+    if not used_colors:
+        return color_hue("#5aa0ff")
+    hues = sorted(set(color_hue(color) % 360 for color in used_colors))
+    gaps = [
+        ((hues[i + 1] if i + 1 < len(hues) else hues[0] + 360) - hue, hue)
+        for i, hue in enumerate(hues)
+    ]
+    gap, start = max(gaps, key=lambda item: (item[0], -item[1]))
+    return (start + gap / 2) % 360
+
+class HueBar(QWidget):
+    hueChanged = Signal(int)
+    def __init__(self, hue):
+        super().__init__()
+        self.hue = int(round(hue)) % 360
+        self.setMinimumWidth(300)
+        self.setMinimumHeight(34)
+    def paintEvent(self, event):
+        painter = QPainter(self)
+        gradient = QLinearGradient(0, 0, self.width(), 0)
+        for hue in range(0, 361, 30):
+            gradient.setColorAt(hue / 360, QColor.fromHsv(hue % 360, 165, 255))
+        painter.fillRect(0, 7, self.width(), 20, gradient)
+        x = round(self.hue / 359 * (self.width() - 1))
+        painter.setPen(QPen(Qt.GlobalColor.black, 2))
+        painter.drawLine(x, 2, x, 31)
+    def mousePressEvent(self, event):
+        self.set_hue(event.position().x() / max(1, self.width() - 1) * 359)
+    def mouseMoveEvent(self, event):
+        if event.buttons() & Qt.MouseButton.LeftButton:
+            self.set_hue(event.position().x() / max(1, self.width() - 1) * 359)
+    def set_hue(self, hue):
+        self.hue = max(0, min(359, int(round(hue))))
+        self.update()
+        self.hueChanged.emit(self.hue)
+
+def ask_hue(initial):
+    dlg = QDialog()
+    dlg.setWindowTitle("Create comment user")
+    layout = QVBoxLayout(dlg)
+    layout.addWidget(QLabel("Choose a hue for this comment user."))
+    bar = HueBar(initial)
+    layout.addWidget(bar)
+    preview = QLabel()
+    preview.setAlignment(Qt.AlignmentFlag.AlignCenter)
+    preview.setMinimumHeight(48)
+    layout.addWidget(preview)
+    def update_preview():
+        # Match the saturation and opacity of the existing hard-coded blue.
+        color = QColor.fromHsv(bar.hue, 165, 255, 255).name()
+        preview.setText(color)
+        preview.setStyleSheet("background-color: " + color)
+        bar.update()
+    bar.hueChanged.connect(update_preview)
+    update_preview()
+    buttons = QDialogButtonBox(
+        QDialogButtonBox.StandardButton.Ok
+        | QDialogButtonBox.StandardButton.Cancel
+    )
+    buttons.accepted.connect(dlg.accept)
+    buttons.rejected.connect(dlg.reject)
+    layout.addWidget(buttons)
+    if dlg.exec() != QDialog.DialogCode.Accepted:
+        return None
+    return QColor.fromHsv(bar.hue, 165, 255, 255).name()
+
+def ask_legacy_initials():
+    while True:
+        dlg = QDialog()
+        dlg.setWindowTitle("Migrate legacy comments")
+        layout = QVBoxLayout(dlg)
+        layout.addWidget(QLabel(
+            "Legacy comment tags and blocks were found. Enter the two "
+            "initials to use for all of them."
+        ))
+        field = QLineEdit()
+        field.setMaxLength(2)
+        field.setPlaceholderText("JF")
+        layout.addWidget(field)
+        buttons = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Ok
+            | QDialogButtonBox.StandardButton.Cancel
+        )
+        buttons.accepted.connect(dlg.accept)
+        buttons.rejected.connect(dlg.reject)
+        layout.addWidget(buttons)
+        if dlg.exec() != QDialog.DialogCode.Accepted:
+            return None
+        initials = field.text().upper()
+        if re.fullmatch(r"[A-Z]{2}", initials):
+            return initials
+        QMessageBox.warning(None, "Invalid initials", "Enter two letters.")
+
+legacy = payload["legacy"]
+if legacy:
+    initials = ask_legacy_initials()
+    legacy_occurrences = len(re.findall(
+        r"</?comment(?:-(?:left|right))?>", text, re.I
+    )) + len(re.findall(
+        r"\.comment-(?:left|right)(?=[\s}])", text, re.I
+    ))
+    if initials is None:
+        result["accepted"] = False
+    elif not QMessageBox.question(
+        None, "Replace legacy comments",
+        "Replace " + str(legacy_occurrences)
+        + " legacy tag or block-class occurrences with "
+        + initials + "com markup?",
+        QMessageBox.StandardButton.Yes | QMessageBox.StandardButton.No,
+        QMessageBox.StandardButton.No,
+    ) == QMessageBox.StandardButton.Yes:
+        result["accepted"] = False
+    else:
+        result["replacements"]["legacy"] = initials
+
+if result["accepted"]:
+    authors = sorted(set(
+        initials.upper() for initials in re.findall(
+            r"</?([A-Za-z]{2})com(?:-(?:left|right))?>", text, re.I
+        )
+    ) | set(
+        initials.upper() for initials in re.findall(
+            r"\.([A-Za-z]{2})com(?:-(?:left|right))?(?=[\s}])",
+            text, re.I
+        )
+    ))
+    if result["replacements"].get("legacy"):
+        authors.append(result["replacements"]["legacy"])
+        authors = sorted(set(authors))
+    for author in authors:
+        if author in colors:
+            continue
+        box = QMessageBox()
+        box.setWindowTitle("Unknown comment author")
+        box.setText(
+            author + "com tags or block classes have no matching "
+            + author + "color field."
+        )
+        selector = QComboBox()
+        for existing in sorted(colors):
+            selector.addItem(existing + "  " + colors[existing], existing)
+            swatch = QPixmap(14, 14)
+            swatch.fill(QColor(colors[existing]))
+            selector.setItemIcon(selector.count() - 1, QIcon(swatch))
+        create = "Create " + author + " as a new comment user"
+        selector.addItem(create, "__create__")
+        selector.setCurrentIndex(selector.count() - 1)
+        box.layout().addWidget(selector, 1, 0, 1, box.layout().columnCount())
+        box.setStandardButtons(
+            QMessageBox.StandardButton.Cancel
+            | QMessageBox.StandardButton.Ok
+        )
+        box.setDefaultButton(QMessageBox.StandardButton.Ok)
+        if box.exec() != QMessageBox.StandardButton.Ok:
+            result["accepted"] = False
+            break
+        target = selector.currentData()
+        if target == "__create__":
+            seed = colors.get(author)
+            if seed is None:
+                used = [*colors.values(), *result["colors"].values()]
+                seed_hue = most_distant_hue(used)
+                seed = QColor.fromHsv(round(seed_hue), 165, 255).name()
+            color = ask_hue(QColor(seed).hue())
+            if color is None:
+                result["accepted"] = False
+                break
+            result["colors"][author] = color
+            colors[author] = color
+        elif target:
+            result["replacements"][author] = target
+
+print(json.dumps(result))
+"""
+    completed = subprocess.run(
+        # the dialog reads the document from its file, since the text of a
+        # large document exceeds the operating system's argument limit
+        [sys.executable, "-c", textwrap.dedent(script),
+         json.dumps({"colors": colors, "legacy": legacy}), filename],
+        capture_output=True, text=True,
+    )
+    if completed.returncode:
+        detail = completed.stderr.strip()
+        message = "cpb comment migration dialog failed"
+        if detail:
+            message += f": {detail}"
+        else:
+            message += "."
+        raise RuntimeError(message)
+    try:
+        return json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            "cpb comment migration dialog returned invalid data"
+        ) from exc
+
+
+def prepare_comment_source(filename):
+    """Migrate comment tags and author colors before a build, if requested."""
+    with open(filename, encoding="utf-8", newline="") as fp:
+        original = fp.read()
+    has_legacy = bool(
+        _LEGACY_TAG_RE.search(original) or _LEGACY_CLASS_RE.search(original)
+    )
+    if not (has_legacy or _AUTHOR_TAG_RE.search(original)
+            or _AUTHOR_CLASS_RE.search(original)):
+        return original
+    _, _, colors = _front_matter(original)
+    authors = {
+        initials.upper()
+        for initials in _AUTHOR_TAG_RE.findall(original)
+    } | {
+        initials.upper()
+        for initials in _AUTHOR_CLASS_RE.findall(original)
+    }
+    if not has_legacy and authors.issubset(colors):
+        return original
+    decisions = _migration_dialog(filename, colors, has_legacy)
+    if not decisions.get("accepted"):
+        raise RuntimeError("cpb comment migration was canceled")
+    updated = original
+    for tag_author, target in decisions.get("replacements", {}).items():
+        if tag_author == "legacy":
+            updated = _LEGACY_TAG_RE.sub(
+                lambda found: (
+                    found.group("closing") + target + "com"
+                    + (found.group("side") or "") + ">"
+                ),
+                updated,
+            )
+            updated = _LEGACY_CLASS_RE.sub(
+                lambda found: target + "com-" + found.group(1), updated
+            )
+        else:
+            pattern = re.compile(
+                r"(?P<closing></?)" + re.escape(tag_author)
+                + r"com(?P<side>-(?:left|right))?>",
+                re.I,
+            )
+            updated = pattern.sub(
+                lambda found: (
+                    found.group("closing") + target + "com"
+                    + (found.group("side") or "") + ">"
+                ),
+                updated,
+            )
+            class_pattern = re.compile(
+                r"\." + re.escape(tag_author)
+                + r"com(?P<side>-(?:left|right))?(?=[\s}])", re.I
+            )
+            updated = class_pattern.sub(
+                lambda found: "." + target + "com"
+                + (found.group("side") or ""), updated
+            )
+    additions = decisions.get("colors", {})
+    if additions:
+        # {{{ add chosen author colors to the YAML front matter
+        match, _, _ = _front_matter(updated)
+        color_lines = [
+            f'{author}color: "{color}"'
+            for author, color in sorted(additions.items())
+        ]
+        if match:
+            body = match.group(2)
+            newline = "\r\n" if "\r\n" in updated else "\n"
+            if body and not body.endswith("\n"):
+                body += newline
+            body += newline.join(color_lines)
+            updated = (
+                updated[:match.start(2)] + body + updated[match.end(2):]
+            )
+        else:
+            newline = "\r\n" if "\r\n" in updated else "\n"
+            header = (
+                "---" + newline + newline.join(color_lines)
+                + newline + "---" + newline
+            )
+            updated = header + updated
+        # }}}
+    if updated != original:
+        directory = os.path.dirname(os.path.abspath(filename))
+        fd, temp_path = tempfile.mkstemp(
+            prefix=".cpb-comments-", dir=directory
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="") as fp:
+                fp.write(updated)
+            os.chmod(temp_path, os.stat(filename).st_mode)
+            os.replace(temp_path, filename)
+        finally:
+            if os.path.exists(temp_path):
+                os.unlink(temp_path)
+    return updated

{pydifftools-0.1.36 → pydifftools-0.1.38}/pydifftools/comment_tags.lua

@@ -32,6 +32,7 @@ local OPENERS = {
   ["<comment-right>"] = { side = "comment-right", close = "</comment-right>" },
   ["<comment-left>"] = { side = "comment-left", close = "</comment-left>" },
 }
+local AUTHOR_COLORS = {}
 
 local comment_id = 0
 local function next_id()
@@ -39,8 +40,15 @@ local function next_id()
   return "c" .. tostring(comment_id)
 end
 
-local function make_inline_comment(side, content_inlines)
-  local inner = pandoc.Span(content_inlines, pandoc.Attr("", { side }, {}))
+local function make_inline_comment(side, content_inlines, spec)
+  local attributes = {}
+  if spec and spec.color then
+    attributes["style"] = "--comment-accent-color: " .. spec.color .. ";"
+    attributes["data-comment-author"] = spec.author
+  end
+  local inner = pandoc.Span(
+    content_inlines, pandoc.Attr("", { side }, attributes)
+  )
   return pandoc.Span(pandoc.List({ inner }), pandoc.Attr("", { "comment-pin" }, {}))
 end
 
@@ -50,11 +58,16 @@ local function make_block_anchor(id)
     '<span class="comment-pin comment-pin-block" data-comment-id="' .. id .. '"></span>')
 end
 
-local function make_block_overlay(side, id, content_blocks)
+local function make_block_overlay(side, id, content_blocks, spec)
   -- Div can contain BulletList/Para/etc. JS will position this overlay.
   return pandoc.Div(
     content_blocks,
-    pandoc.Attr("", { "comment-overlay", side }, { ["data-comment-id"] = id })
+    pandoc.Attr("", { "comment-overlay", side }, {
+      ["data-comment-id"] = id,
+      ["data-comment-author"] = spec and spec.author or nil,
+      ["style"] = spec and spec.color
+        and ("--comment-accent-color: " .. spec.color .. ";") or nil,
+    })
   )
 end
 
@@ -263,7 +276,7 @@ function Inlines(inlines)
       end
 
       if found then
-        out:insert(make_inline_comment(spec.side, buf))
+        out:insert(make_inline_comment(spec.side, buf, spec))
         i = j + 1
       else
         -- unmatched: leave literal
@@ -353,7 +366,7 @@ function Blocks(blocks)
         if not merged_with_inline_anchor then
           out:insert(make_block_anchor(id))
         end
-        out:insert(make_block_overlay(spec.side, id, buf))
+        out:insert(make_block_overlay(spec.side, id, buf, spec))
 
         -- Keep trailing content after the closer in main flow.
         for after_index = 1, #after_close_blocks do
@@ -370,3 +383,54 @@ function Blocks(blocks)
 
   return out
 end
+
+function Div(el)
+  for index, class_name in ipairs(el.classes) do
+    local author, side = class_name:match("^([A-Za-z][A-Za-z])com%-(left)$")
+    if not author then
+      author, side = class_name:match("^([A-Za-z][A-Za-z])com%-(right)$")
+    end
+    if not author then
+      author = class_name:match("^([A-Za-z][A-Za-z])com$")
+      side = "right"
+    end
+    author = author and author:upper() or nil
+    local color = author and AUTHOR_COLORS[author] or nil
+    if color then
+      el.classes[index] = "comment-" .. side
+      local style = el.attributes.style or ""
+      if #style > 0 and not style:match(";%s*$") then
+        style = style .. ";"
+      end
+      el.attributes.style = style .. "--comment-accent-color: " .. color .. ";"
+      el.attributes["data-comment-author"] = author
+    end
+  end
+  return el
+end
+
+function Pandoc(doc)
+  for key, value in pairs(doc.meta) do
+    local initials = tostring(key):match("^([A-Za-z][A-Za-z])color$")
+    local color = pandoc.utils.stringify(value)
+    if initials and color:match("^#%x%x%x%x%x%x$") then
+      initials = initials:upper()
+      color = color:lower()
+      AUTHOR_COLORS[initials] = color
+      for suffix, side in pairs({
+        ["com"] = "comment-right",
+        ["com-left"] = "comment-left",
+        ["com-right"] = "comment-right",
+      }) do
+        local tag = "<" .. initials:lower() .. suffix .. ">"
+        OPENERS[tag] = {
+          side = side,
+          close = "</" .. initials:lower() .. suffix .. ">",
+          color = color,
+          author = initials,
+        }
+      end
+    end
+  end
+  return doc:walk({ Inlines = Inlines, Blocks = Blocks, Div = Div })
+end