pyDiffTools 0.1.25__tar.gz → 0.1.26__tar.gz

{pydifftools-0.1.25/pyDiffTools.egg-info → pydifftools-0.1.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyDiffTools
-Version: 0.1.25
+Version: 0.1.26
 Summary: Diff tools
 Author: J M Franck
 License: Copyright (c) 2015, jmfranck
@@ -106,6 +106,10 @@ included are (listed in order of fun/utility):
   ``_build``/``_display`` directories; with ``--watch`` it starts the HTTP
   server and automatically rebuilds the staged fragments whenever you edit
   a ``.qmd`` file.
+- `pydifft gd [git diff args...]` shows the same Qt review table as the old
+  ``git_gd_qt.py`` helper before launching ``git difftool`` for a selected
+  file.  Run ``pydifft gd --install`` to add the matching ``git gd`` alias
+  to your global git config.
 - `pydifft qmdinit [directory]` scaffolds a new Quarto-style project using
   the bundled templates and example ``project1`` hierarchy, then downloads
   MathJax into ``_template/mathjax`` so the builder can run immediately.

{pydifftools-0.1.25 → pydifftools-0.1.26}/README.rst

@@ -56,6 +56,10 @@ included are (listed in order of fun/utility):
   ``_build``/``_display`` directories; with ``--watch`` it starts the HTTP
   server and automatically rebuilds the staged fragments whenever you edit
   a ``.qmd`` file.
+- `pydifft gd [git diff args...]` shows the same Qt review table as the old
+  ``git_gd_qt.py`` helper before launching ``git difftool`` for a selected
+  file.  Run ``pydifft gd --install`` to add the matching ``git gd`` alias
+  to your global git config.
 - `pydifft qmdinit [directory]` scaffolds a new Quarto-style project using
   the bundled templates and example ``project1`` hierarchy, then downloads
   MathJax into ``_template/mathjax`` so the builder can run immediately.

{pydifftools-0.1.25 → pydifftools-0.1.26/pyDiffTools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyDiffTools
-Version: 0.1.25
+Version: 0.1.26
 Summary: Diff tools
 Author: J M Franck
 License: Copyright (c) 2015, jmfranck
@@ -106,6 +106,10 @@ included are (listed in order of fun/utility):
   ``_build``/``_display`` directories; with ``--watch`` it starts the HTTP
   server and automatically rebuilds the staged fragments whenever you edit
   a ``.qmd`` file.
+- `pydifft gd [git diff args...]` shows the same Qt review table as the old
+  ``git_gd_qt.py`` helper before launching ``git difftool`` for a selected
+  file.  Run ``pydifft gd --install`` to add the matching ``git gd`` alias
+  to your global git config.
 - `pydifft qmdinit [directory]` scaffolds a new Quarto-style project using
   the bundled templates and example ``project1`` hierarchy, then downloads
   MathJax into ``_template/mathjax`` so the builder can run immediately.

{pydifftools-0.1.25 → pydifftools-0.1.26}/pyDiffTools.egg-info/SOURCES.txt

@@ -57,8 +57,11 @@ pydifftools/continuous.py
 pydifftools/copy_files.py
 pydifftools/diff-doc.js
 pydifftools/doc_contents.py
+pydifftools/git_gd.py
+pydifftools/git_gd_qt.py
 pydifftools/html_comments.py
 pydifftools/html_uncomments.py
+pydifftools/log_example.py
 pydifftools/match_spaces.py
 pydifftools/onewordify.py
 pydifftools/onewordify_undo.py
@@ -79,6 +82,7 @@ pydifftools/notebook/__init__.py
 pydifftools/notebook/fast_build.py
 pydifftools/notebook/tex_to_qmd.py
 tests/test_browser_lifecycle.py
+tests/test_command_line_help.py
 tests/test_continuous_shutdown.py
 tests/test_rrng.py
 tests/test_tex_to_qmd.py

pydifftools-0.1.26/pydifftools/browser_lifecycle.py

@@ -0,0 +1,68 @@
+import os
+import shutil
+import subprocess
+
+def browser_window_is_alive(browser):
+    # Keep all browser liveness checks in one place so watch commands share
+    # the same shutdown behavior when a user closes the browser window.
+    # Do not probe with execute_script here: page navigations can briefly
+    # interrupt script execution even while the window is still open.
+    if browser is None:
+        return False
+    try:
+        handles = browser.window_handles
+        if not handles:
+            return False
+        return True
+    except Exception:
+        return False
+
+
+def close_browser_window(browser):
+    # Close a Selenium browser session and ignore errors from already-closed
+    # windows so cleanup paths stay simple.
+    if browser is None:
+        return
+    try:
+        browser.quit()
+    except Exception:
+        pass
+
+
+def forward_search_in_browser(browser, search_text):
+    # Reuse the same browser-side find logic across cpb and qmdb.
+    if browser is None or not search_text:
+        return False
+    found = browser.execute_script(
+        """
+        var searchText = arguments[0];
+        if (!window.find) {
+            return false;
+        }
+        var didFind = window.find(searchText);
+        if (didFind && window.getSelection) {
+            var selection = window.getSelection();
+            if (selection.rangeCount > 0) {
+                var rect = selection.getRangeAt(0).getBoundingClientRect();
+                window.scrollBy(0, rect.top - window.innerHeight / 3);
+            }
+        }
+        return didFind;
+        """,
+        search_text,
+    )
+    if not found:
+        print("forward search did not find text:", search_text)
+    # Bring the browser window to the foreground in Linux window managers.
+    if os.name == "posix" and shutil.which("wmctrl"):
+        window_title = browser.execute_script("return document.title;")
+        if window_title:
+            # Try common Chromium title forms used by desktop environments.
+            for title_candidate in [
+                window_title,
+                window_title + " - Google Chrome",
+                window_title + " - Chromium",
+                window_title + " - Chrome",
+            ]:
+                subprocess.run(["wmctrl", "-a", title_candidate], check=False)
+    return found

{pydifftools-0.1.25 → pydifftools-0.1.26}/pydifftools/command_line.py

@@ -27,10 +27,16 @@ from .comment_functions import matchingbrackets
 from .copy_files import copy_image_files
 from .searchacro import replace_acros
 from .rearrange_tex import run as rearrange_tex_run
+from .git_gd import gd  # registers git difftool review command
 from .flowchart.watch_graph import wgrph
 from .flowchart.graph import load_graph_yaml
 from .notebook.tex_to_qmd import tex2qmd
-from .notebook.fast_build import qmdb, qmdinit
+from .notebook.fast_build import (
+    qmdb,
+    qmdinit,
+    QMDB_FORWARD_SEARCH_HOST,
+    QMDB_FORWARD_SEARCH_PORT,
+)
 
 from .command_registry import _COMMAND_SPECS, register_command
 
@@ -518,27 +524,48 @@ def fs(arguments):
     "markdown forward search, use with cpb to jump to text in the browser"
 )
 def mfs(text):
-    # Send the requested search text to the cpb socket listener.
-    client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-    try:
-        client.connect((FORWARD_SEARCH_HOST, FORWARD_SEARCH_PORT))
-    except OSError as exc:
-        client.close()
-        # If cpb isn't running yet, choose a markdown file in this directory
-        # that contains the requested search text and start cpb for it.
+    # Normalize markdown-specific markup so search phrases match rendered text.
+    search_text = text
+    marker_match = re.search(r"(?i)@[a-z]{2,4}:", search_text)
+    if marker_match:
+        search_text = search_text[: marker_match.start()]
+    search_text = re.sub(r"\[@[^\]]+\]", " ", search_text)
+    search_text = search_text.replace("**", " ").replace("*", " ")
+    search_text = re.sub(r"\s+", " ", search_text).strip()
+    if not search_text:
+        search_text = text.strip()
+
+    # Try existing cpb and qmdb listeners before launching a new cpb process.
+    socket_addresses = [
+        (FORWARD_SEARCH_HOST, FORWARD_SEARCH_PORT),
+        (QMDB_FORWARD_SEARCH_HOST, QMDB_FORWARD_SEARCH_PORT),
+    ]
+    client = None
+    for address in socket_addresses:
+        candidate = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            candidate.connect(address)
+            client = candidate
+            break
+        except OSError:
+            candidate.close()
+    if client is None:
+        # If no listener is running yet, choose a markdown file in this
+        # directory that contains the requested search text and start cpb for
+        # it.
         matching_files = []
         for filename in sorted(os.listdir(".")):
             if not filename.endswith(".md"):
                 continue
             with open(filename, encoding="utf-8") as fp:
-                if text in fp.read():
+                if search_text in fp.read():
                     matching_files.append(filename)
         if len(matching_files) == 0:
             raise RuntimeError(
-                "Could not connect to cpb forward search socket and "
+                "Could not connect to cpb or qmdb forward search sockets and "
                 "could not find the requested text in any .md file in the "
                 "current directory."
-            ) from exc
+            )
         if len(matching_files) > 1:
             print(
                 "Found search text in multiple markdown files. "
@@ -554,19 +581,23 @@ def mfs(text):
         # Wait up to 20 seconds so the child can bring up the listener,
         # then resend the forward-search text.
         for _ in range(80):
-            client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-            try:
-                client.connect((FORWARD_SEARCH_HOST, FORWARD_SEARCH_PORT))
+            for address in socket_addresses:
+                candidate = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                try:
+                    candidate.connect(address)
+                    client = candidate
+                    break
+                except OSError:
+                    candidate.close()
+            if client is not None:
                 break
-            except OSError:
-                client.close()
-                time.sleep(0.25)
+            time.sleep(0.25)
         else:
             raise RuntimeError(
                 "Started cpb automatically, but the forward search socket "
                 "did not come up within 20 seconds."
             )
-    client.sendall(text.encode("utf-8"))
+    client.sendall(search_text.encode("utf-8"))
     client.close()
 
 
@@ -841,22 +872,11 @@ def build_parser():
             flags = argument["flags"]
             kwargs = dict(argument["kwargs"])
             action = subparser.add_argument(*flags, **kwargs)
-            if (
-                FilesCompleter is not None
-                and name == "wgrph"
-                and action.dest == "yaml"
-            ):
-                # Provide YAML-only completions for the flowchart watcher.
-                action.completer = FilesCompleter(
-                    allowednames=["*.yaml", "*.yml"]
-                )
-            if (
-                FilesCompleter is not None
-                and name == "cpb"
-                and action.dest == "filename"
-            ):
-                # Provide Markdown-only completions for continuous pandoc build.
-                action.completer = FilesCompleter(allowednames=["*.md"])
+            # {{{ attach filename completer
+            allowednames = argument.get("completion_allowednames")
+            if FilesCompleter is not None and allowednames is not None:
+                action.completer = FilesCompleter(allowednames=allowednames)
+            # }}}
             if name == "wgrph" and action.dest == "t":
                 # Offer case-insensitive completions for incomplete task names.
                 action.completer = wgrph_task_completer
@@ -888,9 +908,23 @@ def main(argv=None):
                 file=sys.stderr,
             )
     parser = build_parser()
+    # {{{ run argcomplete
     if argcomplete is not None:
-        # Enable argcomplete integration when the dependency is available.
-        argcomplete.autocomplete(parser)
+        # Only suggest options after the user types '-' so bare
+        # `pydifft <tab>` offers subcommands only.
+        try:
+            argcomplete.autocomplete(
+                parser,
+                always_complete_options=False,
+                exit_method=os._exit,
+                output_stream=None,
+            )
+        except TypeError as exc:
+            if "unexpected keyword argument" not in str(exc):
+                raise
+            # Test stubs may provide a minimal autocomplete(parser) shim only.
+            argcomplete.autocomplete(parser)
+    # }}}
     if not argv:
         parser.print_help()
         return

pydifftools-0.1.26/pydifftools/command_registry.py

@@ -0,0 +1,119 @@
+import argparse
+import inspect
+
+
+class CommandRegistrationError(Exception):
+    """Exception raised when attempting to register a duplicate subcommand."""
+
+
+# Registry that stores all subcommands made available to the CLI dispatcher.
+_COMMAND_SPECS = {}
+
+
+def register_command(
+    help_text,
+    description=None,
+    help=None,
+    filename_extensions=None,
+):
+    """Register a command handler for the CLI dispatcher."""
+
+    def decorator(func):
+        name = func.__name__.replace("_", "-")
+        if name in _COMMAND_SPECS:
+            raise CommandRegistrationError(
+                f"Command '{name}' already registered"
+            )
+        signature = inspect.signature(func)
+        parameters = [
+            parameter
+            for parameter in signature.parameters.values()
+            if parameter.kind
+            not in [
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ]
+        ]
+        # {{{ normalize filename extensions
+        if filename_extensions is None:
+            completion_allowednames = {}
+        else:
+            completion_allowednames = {}
+            for argument_name, extensions in filename_extensions.items():
+                if isinstance(extensions, str):
+                    extensions = [extensions]
+                completion_allowednames[argument_name] = []
+                for extension in extensions:
+                    if (
+                        not isinstance(extension, str)
+                        or len(extension.strip()) == 0
+                    ):
+                        raise CommandRegistrationError(
+                            "filename_extensions must contain non-empty"
+                            " strings"
+                        )
+                    extension = extension.strip()
+                    if extension.startswith("*."):
+                        completion_allowednames[argument_name].append(
+                            extension
+                        )
+                    elif extension.startswith("."):
+                        completion_allowednames[argument_name].append(
+                            "*" + extension
+                        )
+                    else:
+                        completion_allowednames[argument_name].append(
+                            "*." + extension
+                        )
+        # }}}
+        unknown_arguments = sorted(
+            set(completion_allowednames)
+            - {parameter.name for parameter in parameters}
+        )
+        if unknown_arguments:
+            raise CommandRegistrationError(
+                "filename_extensions references unknown arguments: "
+                + ", ".join(unknown_arguments)
+            )
+        _COMMAND_SPECS[name] = {
+            "handler": func,
+            "help": help_text.strip(),
+            "description": (
+                description if description is not None else help_text
+            ).strip(),
+            "arguments": [],
+        }
+        argument_help = help if help is not None else {}
+        for parameter in parameters:
+            flags = []
+            kwargs = {}
+            if parameter.default is inspect._empty:
+                flags.append(parameter.name)
+                if parameter.name == "arguments":
+                    # Most commands accept a raw list of trailing arguments.
+                    kwargs["nargs"] = argparse.REMAINDER
+                    kwargs["help"] = argparse.SUPPRESS
+            else:
+                # Single-letter keywords use a short flag; everything else uses
+                # the long two-dash style expected by the CLI.
+                dash_prefix = "-" if len(parameter.name) == 1 else "--"
+                flags.append(dash_prefix + parameter.name.replace("_", "-"))
+                kwargs["default"] = parameter.default
+                if isinstance(parameter.default, bool):
+                    # Boolean flags toggle on or off without needing a value.
+                    kwargs["action"] = (
+                        "store_false" if parameter.default else "store_true"
+                    )
+                elif parameter.default is not None:
+                    kwargs["type"] = type(parameter.default)
+            if parameter.name in argument_help:
+                kwargs["help"] = argument_help[parameter.name].strip()
+            argument_spec = {"flags": flags, "kwargs": kwargs}
+            if parameter.name in completion_allowednames:
+                argument_spec["completion_allowednames"] = (
+                    completion_allowednames[parameter.name]
+                )
+            _COMMAND_SPECS[name]["arguments"].append(argument_spec)
+        return func
+
+    return decorator

{pydifftools-0.1.25 → pydifftools-0.1.26}/pydifftools/continuous.py

@@ -12,7 +12,11 @@ import queue
 from watchdog.events import FileSystemEventHandler
 from watchdog.observers import Observer
 from .command_registry import register_command
-from .browser_lifecycle import browser_window_is_alive, close_browser_window
+from .browser_lifecycle import (
+    browser_window_is_alive,
+    close_browser_window,
+    forward_search_in_browser,
+)
 
 FORWARD_SEARCH_HOST = "127.0.0.1"
 FORWARD_SEARCH_PORT = 51235
@@ -122,7 +126,11 @@ def run_pandoc(filename, html_file, comments_to_margin=False):
     # into the markdown directory before collecting css/lua/js companion files.
     with open(filename, encoding="utf-8") as fp:
         markdown_text = fp.read()
-    if "<comment>" in markdown_text:
+    if (
+        "<comment>" in markdown_text
+        or "comment-right" in markdown_text
+        or "comment-left" in markdown_text
+    ):
         package_dir = os.path.dirname(os.path.abspath(__file__))
         for asset_name in ["comments.css", "comment_toggle.js"]:
             target_path = os.path.join(source_dir, asset_name)
@@ -139,9 +147,11 @@ def run_pandoc(filename, html_file, comments_to_margin=False):
         ]
         if len(localfiles[k]) == 1:
             localfiles[k] = os.path.join(source_dir, localfiles[k][0])
+        elif len(localfiles[k]) == 0:
+            localfiles[k] = None
         else:
             raise ValueError(
-                f"You have more than one (or no) {k} file in this directory!"
+                f"You have more than one {k} file in this directory!"
                 " Get rid of all but one! of " + "and".join(localfiles[k])
             )
     # Include any css files next to the markdown source in the pandoc output.
@@ -150,8 +160,13 @@ def run_pandoc(filename, html_file, comments_to_margin=False):
     )
     # Include any lua filters next to the markdown source in the pandoc
     # output by passing repeated --lua-filter arguments.
+    lua_priority = {
+        "scholarly-metadata.lua": 0,
+        "author-info-blocks.lua": 1,
+    }
     localfiles["lua"] = sorted(
-        [f for f in os.listdir(source_dir) if f.endswith(".lua")]
+        [f for f in os.listdir(source_dir) if f.endswith(".lua")],
+        key=lambda name: (lua_priority.get(name, 2), name),
     )
     # Include any javascript files next to the markdown source by injecting
     # script tags after pandoc runs. This adds extra javascript and does not
@@ -161,9 +176,6 @@ def run_pandoc(filename, html_file, comments_to_margin=False):
     )
     command = [
         "pandoc",
-        "--bibliography",
-        localfiles["bib"],
-        f"--csl={localfiles['csl']}",
         "--filter",
         "pandoc-crossref",
         "--citeproc",
@@ -175,16 +187,31 @@ def run_pandoc(filename, html_file, comments_to_margin=False):
         html_file,
         filename,
     ]
+    if localfiles["bib"]:
+        command[1:1] = ["--bibliography", localfiles["bib"]]
+    if localfiles["csl"]:
+        command.insert(1, f"--csl={localfiles['csl']}")
     for css_file in localfiles["css"]:
         command.extend(["--css", os.path.join(source_dir, css_file)])
     for lua_file in localfiles["lua"]:
         command.extend(["--lua-filter", os.path.join(source_dir, lua_file)])
     # command = ['pandoc', '-s', '--mathjax', '-o', html_file, filename]
     print("running:", " ".join(command))
-    subprocess.run(
+    completed = subprocess.run(
         command,
     )
+    if getattr(completed, "returncode", 0) != 0:
+        raise RuntimeError(
+            f"Pandoc failed with exit code {completed.returncode} while "
+            f"building {html_file}.\n"
+            f"Command: {' '.join(command)}"
+        )
     print("running:\n", command)
+    if not os.path.exists(html_file):
+        raise RuntimeError(
+            "Pandoc completed but did not create the expected HTML file: "
+            f"{html_file}"
+        )
     if has_local_jax:
         # {{{ for slow internet connection, remove remote files
         with open(html_file, encoding="utf-8") as fp:
@@ -239,14 +266,14 @@ class Handler(FileSystemEventHandler):
         self.filename = filename
         self.comments_to_margin = comments_to_margin
         self.html_file = filename.rsplit(".", 1)[0] + ".html"
-        self.init_firefox()
+        self.init_chrome()
 
-    def init_firefox(self):
+    def init_chrome(self):
         # apparently, selenium breaks stdin/out for tests, so it must be
         # imported here
         from selenium import webdriver
 
-        self.firefox = webdriver.Chrome()
+        self.chrome = webdriver.Chrome()
         run_pandoc(
             self.filename,
             self.html_file,
@@ -255,7 +282,7 @@ class Handler(FileSystemEventHandler):
         if not os.path.exists(self.html_file):
             print("html doesn't exist")
         self.append_autorefresh()
-        self.firefox.get("file://" + os.path.abspath(self.html_file))
+        self.chrome.get("file://" + os.path.abspath(self.html_file))
 
     def on_modified(self, event):
         from selenium.common.exceptions import WebDriverException
@@ -270,14 +297,14 @@ class Handler(FileSystemEventHandler):
             )
             self.append_autorefresh()
             try:
-                self.firefox.refresh()
+                self.chrome.refresh()
             except WebDriverException:
                 print(
                     "I'm quitting!! You probably suspended the computer, which"
                     " seems to freak selenium out.  Just restart"
                 )
-                self.firefox.quit()
-                self.init_firefox()
+                self.chrome.quit()
+                self.init_chrome()
 
     def append_autorefresh(self):
         with open(self.html_file, "r", encoding="utf-8") as fp:
@@ -348,47 +375,10 @@ position
             fp.write(all_data)
 
     def forward_search(self, search_text):
-        # Use the browser's built-in window.find to locate the text.
+        # Reuse shared browser search behavior so cpb and qmdb stay in sync.
         if not search_text:
             return
-        found = self.firefox.execute_script(
-            """
-            var searchText = arguments[0];
-            if (!window.find) {
-                return false;
-            }
-            var didFind = window.find(searchText);
-            if (didFind && window.getSelection) {
-                var selection = window.getSelection();
-                if (selection.rangeCount > 0) {
-                    var rect = selection.getRangeAt(0).getBoundingClientRect();
-                    window.scrollBy(0, rect.top - window.innerHeight / 3);
-                }
-            }
-            return didFind;
-            """,
-            search_text,
-        )
-        if not found:
-            print("forward search did not find text:", search_text)
-        # Bring the browser window to the foreground in Linux window managers.
-        if os.name == "posix" and shutil.which("wmctrl"):
-            window_title = self.firefox.execute_script(
-                "return document.title;"
-            )
-            if window_title:
-                # Try common Chromium title forms used by desktop environments.
-                for title_candidate in [
-                    window_title,
-                    window_title + " - Google Chrome",
-                    window_title + " - Chromium",
-                    window_title + " - Chrome",
-                ]:
-                    subprocess.run(
-                        ["wmctrl", "-a", title_candidate],
-                        check=False,
-                    )
-
+        forward_search_in_browser(self.chrome, search_text)
 
 @register_command(
     "continuous pandoc build.  Like latexmk, but for markdown!",
@@ -399,6 +389,7 @@ position
             "comments filter for printing."
         ),
     },
+    filename_extensions={"filename": ".md"},
 )
 def cpb(filename, comments_to_margin=False):
     observer = Observer()
@@ -420,7 +411,7 @@ def cpb(filename, comments_to_margin=False):
         while True:
             # Exit when the browser window is closed so cpb does not leave a
             # background process running after the user closes Chrome.
-            if not browser_window_is_alive(event_handler.firefox):
+            if not browser_window_is_alive(event_handler.chrome):
                 break
             time.sleep(1)
             while not search_queue.empty():
@@ -434,7 +425,7 @@ def cpb(filename, comments_to_margin=False):
         observer.stop()
         observer.join()
         socket_thread.join()
-        close_browser_window(event_handler.firefox)
+        close_browser_window(event_handler.chrome)
 
 
 if __name__ == "__main__":