gitpane 1.0.0__py3-none-any.whl

gitpane/tool/mergetool_recipe.py

@@ -0,0 +1,84 @@
+"""Keep the merge tool recipe, literal process arguments included, independent of comparison tools."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from dataclasses import dataclass
+
+from PySide6.QtCore import QProcess
+
+from gitpane.config import SHELL_SCRIPT_EXTENSION_SET
+from gitpane.system.linux_distribution import DistributionFamily, DistributionRelease
+from gitpane.tool.kdiff3 import tool_program_usable
+from gitpane.tool.kdiff3_install import with_kdiff3_install_line
+
+MERGETOOL_FILENAME_PREFERENCE_KEY = "mergetool_filename"
+MERGETOOL_COMMAND_PREFERENCE_KEY = "mergetool_command"
+MERGETOOL_DEFAULT_COMMAND = '"$BASE" "$LOCAL" "$REMOTE" -o "$MERGED"'
+MERGETOOL_TOKENS = ("$BASE", "$LOCAL", "$REMOTE", "$MERGED")
+MERGETOOL_DEFAULT_BY_KEY = {MERGETOOL_FILENAME_PREFERENCE_KEY: "", MERGETOOL_COMMAND_PREFERENCE_KEY: MERGETOOL_DEFAULT_COMMAND}
+TOKEN_PATTERN = r"\$[A-Za-z_][A-Za-z_0-9]*|\$\{[^}]*\}|\$"
+
+
+@dataclass(frozen=True)
+class MergetoolRecipe:
+    """Retain the selected executable and the complete four-input argument template."""
+
+    program_filename: str
+    command: str = MERGETOOL_DEFAULT_COMMAND
+
+    def validate(self, *, optional: bool = False, platform: str = sys.platform, family: DistributionFamily = DistributionFamily.UNKNOWN,
+                 release: DistributionRelease = DistributionRelease.OTHER) -> None:
+        """Allow an unset Settings choice only when explicitly requested by its caller.
+
+        The refusal of a missing tool says how to install KDiff3 on ``platform``, and under Linux on the distribution
+        ``family`` and ``release``, all received so each system's message can be checked from any of them.
+        """
+        parse_mergetool_command(self.command, "base", "local", "remote", "merged")
+        if not self.program_filename:
+            if optional:
+                return
+            raise ValueError(with_kdiff3_install_line("External merge tool is not configured. Open Settings and save its executable path before resolving conflicts.", platform, family, release))
+        if not tool_program_usable(self.program_filename):
+            raise ValueError(with_kdiff3_install_line("External merge tool executable is missing or not executable. Choose its full path.", platform, family, release))
+        _program_root, program_extension = os.path.splitext(self.program_filename)
+        if program_extension.casefold() in SHELL_SCRIPT_EXTENSION_SET:
+            raise ValueError("Choose the real external merge executable instead of a shell script launcher.")
+
+
+def parse_mergetool_command(command: str, base_filename: str | None, local_filename: str | None, remote_filename: str | None, merged_filename: str | None,
+                            *, allow_missing_base: bool = False) -> list[str]:
+    """Build literal arguments, removing a standalone absent base only after explicit agreement."""
+    if "\0" in command:
+        raise ValueError("External merge arguments cannot contain a null character.")
+    # Qt uses three quotes for a literal quote, so backslashes cannot balance a quoted argument.
+    if command.replace('"""', '').count('"') % 2:
+        raise ValueError("External merge arguments contain an unclosed double quote.")
+    arguments = QProcess.splitCommand(command)
+    replacement_by_token = dict(zip(MERGETOOL_TOKENS, (base_filename, local_filename, remote_filename, merged_filename), strict=True))
+    token_set: set[str] = set()
+    for argument in arguments:
+        tokens = re.findall(TOKEN_PATTERN, argument)
+        for token in tokens:
+            if token not in replacement_by_token:
+                raise ValueError("External merge arguments contain an unknown parameter. Use $BASE, $LOCAL, $REMOTE and $MERGED only.")
+            token_set.add(token)
+    if token_set != set(MERGETOOL_TOKENS):
+        raise ValueError("External merge arguments must include $BASE, $LOCAL, $REMOTE and $MERGED.")
+    for token, filename in replacement_by_token.items():
+        if filename and "\0" in filename:
+            raise ValueError("External merge filenames cannot contain a null character.")
+        if not filename and token != "$BASE":
+            raise ValueError(f"The {token} filename is missing. Use manual conflict resolution for an absent side.")
+    if not base_filename and not allow_missing_base:
+        raise ValueError("The BASE version is missing. A two-input merge requires confirmation.")
+    results = []
+    for argument in arguments:
+        if not base_filename and "$BASE" in argument:
+            if argument != "$BASE":
+                raise ValueError("Missing BASE can only remove a standalone $BASE argument. This recipe requires manual conflict resolution.")
+            continue
+        results.append(re.sub(TOKEN_PATTERN, lambda match: replacement_by_token[match.group()], argument))
+    return results

gitpane/tool/system_editor_default.py

@@ -0,0 +1,80 @@
+"""Keep the system's plain text editor known, reading it again off the window's thread when asked.
+
+The value is the identifier the system names that editor by: a desktop file name on Linux, an application identifier
+on macOS. The files it is read from may sit in a home folder on a network share that stops answering, so the window
+never waits for them: a read runs on a thread of its own, only one at a time, and until its answer arrives the system
+counts as naming no editor. Settings and Show in text editor use the last value received. A read always answers, so the
+next request reads again; an error nobody expects names no editor and is written to the ``--log`` journal, since it
+shows a defect of GitPane rather than something about the system.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Qt, Signal
+
+from gitpane.account.credential_manager import ignore_line
+from gitpane.thread.weak_signal import hand_over_to_the_page, weak_signal_emitter
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+SYSTEM_EDITOR_THREAD_NAME = "gitpane-system-text-editor"
+SYSTEM_EDITOR_READ_FAILURE_LOG_TEMPLATE = "Reading the system's text editor failed unexpectedly: {error_class}: {error}"
+
+
+def run_system_editor_id_read(read: Callable[[], str], hand_over: Callable[[str], None], log_line: Callable[[str], None] = ignore_line) -> None:
+    """Read the system's editor on the worker thread and hand it over to the holder's thread, an empty text when the read failed.
+
+    A failed read names no editor, so the detection falls back on its rule for no default rather than on a value it could
+    not read. The holder always gets an answer, so ``reading`` falls back and the next request reads again. An error
+    nobody expects shows a defect of GitPane, not of the system: it is written through ``log_line``.
+    """
+    system_editor_id = ""
+    try:
+        system_editor_id = read()
+    except (OSError, ValueError, UnicodeError, RuntimeError):
+        system_editor_id = ""
+    except Exception as error:  # noqa: BLE001 -- the worker must always answer the holder; the error is written to the --log journal
+        system_editor_id = ""
+        log_line(SYSTEM_EDITOR_READ_FAILURE_LOG_TEMPLATE.format(error_class=type(error).__name__, error=error))
+    finally:
+        hand_over_to_the_page(hand_over, system_editor_id)
+
+
+class SystemEditorDefault(QObject):
+    """The identifier the system names its plain text editor by, as last read; empty until a read answers."""
+
+    system_editor_id_read = Signal(object)
+
+    def __init__(self, read_system_editor_id: Callable[[], str], parent: QObject | None = None, *, log_line: Callable[[str], None] = ignore_line) -> None:
+        """Keep ``read_system_editor_id``, which reads the session's files and runs only off the window's thread; nothing is read before a request.
+
+        ``log_line`` writes one line to the ``--log`` journal, from the reading thread, when a read meets an error
+        nobody expects; without a journal it writes nothing.
+        """
+        super().__init__(parent)
+        self.read_system_editor_id = read_system_editor_id
+        self.log_line = log_line
+        self.system_editor_id = ""
+        self.reading = False
+        self.system_editor_id_read.connect(self.keep_system_editor_id, Qt.ConnectionType.QueuedConnection)
+
+    def request_read(self) -> None:
+        """Start reading the system's editor on a worker thread, unless a read is still running."""
+        if self.reading:
+            return
+        self.reading = True
+        # The thread hands its answer to the window thread's relay, never to the holder's own signal: the relay emits it
+        # there only while the holder still exists, so a holder deleted during the read, as GitPane quits, is never
+        # touched from the reading thread.
+        hand_over = weak_signal_emitter(self, lambda holder: holder.system_editor_id_read)
+        thread = threading.Thread(target=run_system_editor_id_read, args=(self.read_system_editor_id, hand_over, self.log_line), name=SYSTEM_EDITOR_THREAD_NAME, daemon=True)
+        thread.start()
+
+    def keep_system_editor_id(self, system_editor_id: str) -> None:
+        """Keep the identifier a read answered, on the holder's thread, and allow the next read."""
+        self.reading = False
+        self.system_editor_id = system_editor_id

gitpane/tool/system_text_editor.py

@@ -0,0 +1,44 @@
+"""Choose, for each system, how GitPane reads the text editor the system opens plain text with.
+
+Linux reads the desktop's mimeapps.list files, macOS the user's LaunchServices handlers. Windows reads nothing: its
+detection keeps Notepad whatever the system names.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from gitpane.config import LINUX_PLATFORM, MACOS_PLATFORM, WINDOWS_PLATFORM
+from gitpane.tool.desktop_text_editor import session_desktop_text_editor_id
+from gitpane.tool.editor_recipe import editor_platform
+from gitpane.tool.launch_services_text_editor import session_launch_services_text_editor_id
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+def read_no_system_text_editor() -> str:
+    """Read nothing and name no editor, for a system whose detection does not follow a default text editor."""
+    return ""
+
+
+SYSTEM_TEXT_EDITOR_READER_BY_PLATFORM: dict[str, Callable[[], str]] = {
+    LINUX_PLATFORM: session_desktop_text_editor_id,
+    MACOS_PLATFORM: session_launch_services_text_editor_id,
+    WINDOWS_PLATFORM: read_no_system_text_editor,
+}
+
+
+def system_text_editor_reader(platform: str) -> Callable[[], str]:
+    """Answer the reader of the default text editor of ``platform``, in the vocabulary of the editor presets, so any other Unix system reads as Linux."""
+    return SYSTEM_TEXT_EDITOR_READER_BY_PLATFORM[editor_platform(platform)]
+
+
+def session_system_text_editor_id() -> str:
+    """Answer the identifier this system names its default text editor by, read from the session's files.
+
+    It may read a home folder on a network share that stops answering: call it on a thread of its own only, never on the
+    window's thread.
+    """
+    return system_text_editor_reader(sys.platform)()