gitpane 1.0.0__py3-none-any.whl

gitpane/ui/setting/ssh_widget.py

@@ -0,0 +1,232 @@
+"""Present an editable SSH candidate separately from accepted tool preferences."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import QDialog, QDialogButtonBox, QFileDialog, QGridLayout, QGroupBox, QLabel, QLineEdit, QPushButton, QScrollArea, QVBoxLayout, QWidget
+
+from gitpane.account.ssh import SSH_UNAVAILABLE_TEXT, SshConfiguration, SshVerification
+from gitpane.account.ssh_prompt import SshQuestion
+from gitpane.config import ERROR_HEIGHT, ERROR_WIDTH, SETTING_MIN_HEIGHT, SETTING_MIN_WIDTH, fit_window
+from gitpane.text.typed_path import session_typed_path, typed_path_value
+from gitpane.ui.widget.result_label import ResultLabel
+from gitpane.ui.window_control.button_focus import set_button_enabled
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class SshWidget(QGroupBox):
+    """Show exact paths and asynchronous verification without saving from the widget."""
+
+    draft_changed = Signal()
+    verification_requested = Signal()
+
+    def __init__(self, configuration: SshConfiguration, effective_filename: str = "", effective_source: str = "", parent: QWidget | None = None, *,
+                 typed_path: Callable[[str], str] = session_typed_path) -> None:
+        """Keep browse controls aligned and long values scrollable in Settings.
+
+        configuration is the saved setting, the only value the form can save back; the client operations really use
+        and where it comes from are shown apart, so a detected client never lands in the editable field. ``typed_path``
+        reads ``~`` in both paths where that is the usage; tests hand their own system and home folder.
+        """
+        super().__init__("SSH client", parent)
+        self.typed_path = typed_path
+        self.request_id = ""
+        self.verified_configuration: SshConfiguration | None = None
+        self.effective_filename = ""
+        layout = QGridLayout(self)
+        label_column, value_column, browse_column = 0, 1, 2
+        executable_row, utility_row, source_row, effective_row, action_row, status_row = range(6)
+        self.path_edit = QLineEdit(configuration.ssh_filename)
+        self.utility_edit = QLineEdit(configuration.utility_dir if os.name == "nt" else "")
+        self.browse_button = QPushButton("Browse…")
+        self.utility_browse_button = QPushButton("Browse…")
+        for row, label_text, edit, button in ((executable_row, "Executable", self.path_edit, self.browse_button),
+                                               (utility_row, "Git utilities directory (Windows)", self.utility_edit, self.utility_browse_button)):
+            label = QLabel(label_text)
+            label.setBuddy(edit)
+            edit.setAccessibleName(label_text)
+            button.setAccessibleName("Browse for " + label_text)
+            layout.addWidget(label, row, label_column)
+            layout.addWidget(edit, row, value_column)
+            layout.addWidget(button, row, browse_column)
+            edit.textChanged.connect(self._changed)
+        self.utility_edit.setEnabled(os.name == "nt")
+        self.utility_browse_button.setEnabled(os.name == "nt")
+        self.utility_edit.setPlaceholderText("Optional" if os.name == "nt" else "Not applicable on this operating system")
+        self.source_label = QLabel()
+        self.effective_edit = QLineEdit()
+        self.effective_edit.setReadOnly(True)
+        self.effective_edit.setAccessibleName("Effective SSH executable")
+        effective_label = QLabel("Effective value")
+        effective_label.setBuddy(self.effective_edit)
+        layout.addWidget(self.source_label, source_row, label_column, 1, 3)
+        layout.addWidget(effective_label, effective_row, label_column)
+        layout.addWidget(self.effective_edit, effective_row, value_column, 1, 2)
+        self.verify_button = QPushButton("Verify SSH client")
+        self.verify_button.clicked.connect(self.verification_requested)
+        layout.addWidget(self.verify_button, action_row, value_column)
+        self.status_label = ResultLabel("")
+        layout.addWidget(self.status_label, status_row, label_column, 1, 3)
+        layout.setColumnStretch(value_column, 1)
+        self.browse_button.clicked.connect(self._browse)
+        self.utility_browse_button.clicked.connect(self._browse_utility)
+        self.show_effective(effective_filename, effective_source)
+
+    def show_effective(self, filename: str, source: str) -> None:
+        """Show the client operations use and where it comes from; ask for one only when there is none.
+
+        A verification result already shown stays: it still describes the saved executable. The client is kept so that
+        Verify can check it while Executable is empty.
+        """
+        self.effective_filename = filename
+        self._update_verify_button()
+        self.source_label.setText("Source: " + source)
+        self.effective_edit.setText(filename or "No SSH client configured")
+        if not filename:
+            self.status_label.setText(SSH_UNAVAILABLE_TEXT)
+        elif self.status_label.text() == SSH_UNAVAILABLE_TEXT:
+            self.status_label.clear()
+
+    def configuration(self) -> SshConfiguration:
+        """Capture the draft without the blanks around each typed path, its inside untouched, and with ``~`` read as the home folder.
+
+        Verify and Save both read this, so a client pasted with a space around it is checked and saved as the path
+        itself, and a check made on it still counts for Save. ``~`` is read where that is the usage, so the saved value
+        is the full path. The Git utilities directory is only used on Windows, where ``~`` stays as typed; it follows the
+        same reading so that every path field has the same rule.
+        """
+        return SshConfiguration(typed_path_value(self.path_edit.text(), self.typed_path), typed_path_value(self.utility_edit.text(), self.typed_path))
+
+    def verification_configuration(self) -> SshConfiguration:
+        """Name what Verify checks: the typed Executable when there is one, otherwise the client operations use now.
+
+        A typed or saved choice wins over the detected client, as it does for operations; checking the detected client
+        never puts it in the editable field, so Save still writes nothing for it.
+        """
+        draft = self.configuration()
+        if draft.ssh_filename:
+            return draft
+        return SshConfiguration(self.effective_filename, draft.utility_dir)
+
+    def set_verifying(self) -> None:
+        """Keep edits possible while showing that the captured candidate is being checked."""
+        set_button_enabled(self.verify_button, False)
+        self.status_label.setText("Verifying SSH client…")
+
+    def show_result(self, result: SshVerification) -> None:
+        """Publish a version only when it still describes what Verify would check now.
+
+        Only a check of the draft itself counts as verifying it for Save: a check of the detected client leaves the
+        draft unverified, so it can never make Save write a path.
+        """
+        self.request_id = ""
+        self._update_verify_button()
+        if result.configuration != self.verification_configuration():
+            self.status_label.show_failure("SSH path changed during verification. Verify the current executable.")
+            return
+        self.verified_configuration = result.configuration if result.succeeded and result.configuration == self.configuration() else None
+        if result.succeeded:
+            self.status_label.setText(result.version)
+        else:
+            self.status_label.show_failure(result.cause)
+
+    def _changed(self) -> None:
+        self.verified_configuration = None
+        self._update_verify_button()
+        self.status_label.clear()
+        self.draft_changed.emit()
+
+    def _update_verify_button(self) -> None:
+        """Offer Verify when there is a client to check and no check is already running."""
+        set_button_enabled(self.verify_button, bool(self.verification_configuration().ssh_filename) and not self.request_id)
+
+    def _browse(self) -> None:
+        """Choose the SSH client without changing the draft when cancelled.
+
+        The chooser starts from the typed path without the blanks around it and with ``~`` read, the value every other
+        check of the field uses.
+        """
+        start_filename = typed_path_value(self.path_edit.text(), self.typed_path)
+        filename, _ = QFileDialog.getOpenFileName(self, "SSH executable", start_filename)
+        if filename:
+            self.path_edit.setText(filename)
+        self.path_edit.setFocus()
+
+    def _browse_utility(self) -> None:
+        """Choose the Git utilities directory without changing the draft when cancelled.
+
+        The chooser starts from the typed directory without the blanks around it and with ``~`` read, the value every
+        other check of the field uses.
+        """
+        start_dir = typed_path_value(self.utility_edit.text(), self.typed_path)
+        utility_dir = QFileDialog.getExistingDirectory(self, "Git utilities directory (Windows)", start_dir)
+        if utility_dir:
+            self.utility_edit.setText(utility_dir)
+        self.utility_edit.setFocus()
+
+
+class SshPromptDialog(QDialog):
+    """Ask explicitly about a host key or accept a masked private passphrase asynchronously."""
+
+    def __init__(self, question: SshQuestion, parent: QWidget | None = None) -> None:
+        """Show captured operation text as plain text and never retain the accepted secret."""
+        super().__init__(parent)
+        self.question = question
+        self.answered = False
+        self.setWindowTitle("SSH host key" if question.confirmation else "SSH authentication")
+        self.resize(ERROR_WIDTH, ERROR_HEIGHT)
+        layout = QVBoxLayout(self)
+        description_label = QLabel(question.description)
+        description_label.setTextFormat(Qt.TextFormat.PlainText)
+        layout.addWidget(description_label)
+        scroll = QScrollArea()
+        scroll.setWidgetResizable(True)
+        label = QLabel(question.text)
+        label.setTextFormat(Qt.TextFormat.PlainText)
+        label.setWordWrap(True)
+        label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+        scroll.setWidget(label)
+        layout.addWidget(scroll)
+        self.answer_edit = QLineEdit()
+        self.answer_edit.setEchoMode(QLineEdit.EchoMode.Password)
+        self.answer_edit.setAccessibleName("SSH passphrase or password")
+        label.setBuddy(self.answer_edit)
+        self.answer_edit.setVisible(not question.confirmation)
+        layout.addWidget(self.answer_edit)
+        buttons = QDialogButtonBox(QDialogButtonBox.StandardButton.Yes | QDialogButtonBox.StandardButton.No if question.confirmation
+                                   else QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        buttons.accepted.connect(self.accept)
+        buttons.rejected.connect(self.reject)
+        if question.confirmation:
+            buttons.button(QDialogButtonBox.StandardButton.Yes).clicked.connect(self.accept)
+            buttons.button(QDialogButtonBox.StandardButton.No).clicked.connect(self.reject)
+            buttons.button(QDialogButtonBox.StandardButton.No).setDefault(True)
+            buttons.button(QDialogButtonBox.StandardButton.No).setFocus()
+        else:
+            self.answer_edit.setFocus()
+        layout.addWidget(buttons)
+        fit_window(self, SETTING_MIN_WIDTH, SETTING_MIN_HEIGHT)
+
+    def accept(self) -> None:
+        """Send the answer directly to its private socket and immediately clear the field."""
+        if self.answered:
+            return
+        self.answered = True
+        # Sent exactly as typed, blanks included, unlike the other typed values: a space may be part of a passphrase.
+        answer = "yes" if self.question.confirmation else self.answer_edit.text()
+        self.answer_edit.clear()
+        self.question.answer(answer)
+        super().accept()
+
+    def reject(self) -> None:
+        """Refuse an unapproved question without retaining its entered credential."""
+        if not self.answered:
+            self.answered = True
+            self.answer_edit.clear()
+            self.question.answer("no" if self.question.confirmation else None)
+        super().reject()

gitpane/ui/setting/utility_page.py

@@ -0,0 +1,240 @@
+"""Show the Settings page that puts a GitPane shortcut on the user's desktop.
+
+The page saves nothing: its button acts at once, so it never counts as unsaved work and the bottom Save and Cancel
+keep applying to the other pages. The shortcut is written on a worker thread, since gio or PowerShell may take a
+while, and its report comes back to the page through a queued signal. The report gives one line per file written or
+tried, each in the colour of what happened to that file, then the command the shortcut starts in ordinary text.
+
+Each time the page is shown, it reads on another worker thread whether the desktop can show a desktop icon at all; when
+it cannot, a note in ordinary text under the result lines says why and gives the steps that would let it. The result
+lines follow the facts last read: the report shown is drawn again when new facts arrive. Both worker threads always
+answer the page; an error nobody expects gives no note, or a failure line for the shortcut, and is written to the
+``--log`` journal, since it shows a defect of GitPane rather than something about the desktop.
+"""
+
+from __future__ import annotations
+
+import threading
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtWidgets import QHBoxLayout, QPushButton, QVBoxLayout, QWidget
+
+from gitpane.account.credential_manager import ignore_line
+from gitpane.config import SPACING_MD, control_height
+from gitpane.system.desktop_icon_support import desktop_icon_note, report_for_desktop
+from gitpane.system.desktop_shortcut import ShortcutOutcome, ShortcutOutcomeKind, ShortcutReport, ShortcutStatus
+from gitpane.thread.weak_signal import hand_over_to_the_page, weak_signal_emitter
+from gitpane.ui.setting.setting_block import block_group
+from gitpane.ui.widget.result_label import ResultLabel, ResultTone
+from gitpane.ui.window_control.button_focus import set_button_enabled
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QShowEvent
+
+    from gitpane.system.desktop_icon_support import DesktopIconFacts
+
+SHORTCUT_THREAD_NAME = "gitpane-desktop-shortcut"
+DESKTOP_ICON_FACT_THREAD_NAME = "gitpane-desktop-icon-facts"
+DESKTOP_ICON_FACT_READ_FAILURE_LOG_TEMPLATE = "Reading whether the desktop can show a desktop icon failed unexpectedly: {error_class}: {error}"
+DESKTOP_SHORTCUT_CREATION_FAILURE_LOG_TEMPLATE = "Creating the desktop shortcut failed unexpectedly: {error_class}: {error}"
+# The detail of the red line of a creation that failed on an error nobody expects: its class says more than its
+# message alone, which can be empty or a bare key.
+UNEXPECTED_CREATION_ERROR_DETAIL_TEMPLATE = "{error_class}: {error}"
+# The colour of each kind of result line: a file written is green, a file that could not be written for want of its
+# folder is orange, a refused write is red.
+RESULT_TONE_BY_OUTCOME_KIND = {
+    ShortcutOutcomeKind.WRITTEN: ResultTone.SUCCESS,
+    ShortcutOutcomeKind.NOT_POSSIBLE: ResultTone.WARNING,
+    ShortcutOutcomeKind.FAILED: ResultTone.FAILURE,
+}
+
+
+class UtilityPageText(Enum):
+    """Texts the Utilities page shows, one member per text so a misspelt name is an error."""
+
+    PAGE_NAME = "Utilities"
+    DESKTOP_SHORTCUT = "Desktop shortcut"
+    """The title of the block holding the shortcut button."""
+    CREATE_DESKTOP_SHORTCUT = "Create desktop shortcut"
+    CREATING = "Creating desktop shortcut…"
+    STARTS = "Starts: {command}"
+    """The ordinary line under the result lines that names the program the shortcut starts and its arguments."""
+
+
+def run_shortcut_creation(create_shortcut: Callable[[], ShortcutReport], hand_over: Callable[[ShortcutReport], None], log_line: Callable[[str], None] = ignore_line) -> None:
+    """Create the shortcut on the worker thread and hand its report over to the page's thread.
+
+    A creator that fails on the file system or on a helper still gives one line. Any other error also gives one red
+    line, and is written through ``log_line``, since it shows a defect of GitPane, not of the system. The report is
+    handed over in every case, so the page always enables its button again.
+    """
+    # The answer left when even an exit of the worker itself ends the creator: the button is enabled again all the same.
+    report = ShortcutReport((ShortcutOutcome(ShortcutStatus.WRITE_FAILED),))
+    try:
+        report = create_shortcut()
+    except (OSError, ValueError, RuntimeError) as error:
+        report = ShortcutReport((ShortcutOutcome(ShortcutStatus.WRITE_FAILED, str(error)),))
+    except Exception as error:  # noqa: BLE001 -- the worker must always answer the page; the error is written to the --log journal
+        report = ShortcutReport((ShortcutOutcome(ShortcutStatus.WRITE_FAILED, UNEXPECTED_CREATION_ERROR_DETAIL_TEMPLATE.format(error_class=type(error).__name__, error=error)),))
+        log_line(DESKTOP_SHORTCUT_CREATION_FAILURE_LOG_TEMPLATE.format(error_class=type(error).__name__, error=error))
+    finally:
+        hand_over_to_the_page(hand_over, report)
+
+
+def run_fact_read(read_facts: Callable[[], DesktopIconFacts], hand_over: Callable[[DesktopIconFacts | None], None], log_line: Callable[[str], None] = ignore_line) -> None:
+    """Read the desktop icon facts on the worker thread and hand them over to the page's thread, or None when the read failed.
+
+    A failed read gives no note, so the page never says something about the desktop it could not read. The page
+    always gets an answer, so its next read starts again. An error nobody expects shows a defect of GitPane, not of
+    the desktop: it is written through ``log_line``.
+    """
+    facts: DesktopIconFacts | None = None
+    try:
+        facts = read_facts()
+    except (OSError, ValueError, RuntimeError):
+        facts = None
+    except Exception as error:  # noqa: BLE001 -- the worker must always answer the page; the error is written to the --log journal
+        facts = None
+        log_line(DESKTOP_ICON_FACT_READ_FAILURE_LOG_TEMPLATE.format(error_class=type(error).__name__, error=error))
+    finally:
+        hand_over_to_the_page(hand_over, facts)
+
+
+class UtilityPage(QWidget):
+    """The Utilities page: one button that puts a GitPane shortcut on the desktop, then one line per file saying how it went, the line naming what the shortcut starts, and a note when the desktop cannot show the icon."""
+
+    shortcut_finished = Signal(object)
+    facts_read = Signal(object)
+
+    def __init__(self, create_shortcut: Callable[[], ShortcutReport], read_desktop_icon_facts: Callable[[], DesktopIconFacts], parent: QWidget | None = None, *,
+                 log_line: Callable[[str], None] = ignore_line) -> None:
+        """Build the page around ``create_shortcut``, which writes the shortcut, and ``read_desktop_icon_facts``, which reads the session; both run off the window's thread.
+
+        ``log_line`` writes one line to the ``--log`` journal, from any thread, when either worker meets an error
+        nobody expects; without a journal it writes nothing. ``last_report`` is the report the lines show, kept so
+        that facts arriving later draw it again; it is None while no report is shown.
+        """
+        super().__init__(parent)
+        self.create_shortcut = create_shortcut
+        self.read_desktop_icon_facts = read_desktop_icon_facts
+        self.log_line = log_line
+        self.creating = False
+        self.reading_facts = False
+        self.desktop_icon_facts: DesktopIconFacts | None = None
+        self.last_report: ShortcutReport | None = None
+        self.result_labels: list[ResultLabel] = []
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(SPACING_MD)
+        group, group_layout = block_group(UtilityPageText.DESKTOP_SHORTCUT.value)
+        self.create_button = QPushButton(UtilityPageText.CREATE_DESKTOP_SHORTCUT.value)
+        self.create_button.clicked.connect(self.start_creation)
+        button_layout = QHBoxLayout()
+        button_layout.addWidget(self.create_button)
+        button_layout.addStretch()
+        group_layout.addLayout(button_layout)
+        # The wait line, shown only while a creation runs, so an empty label never adds a gap above the result lines.
+        self.status_label = ResultLabel()
+        self.status_label.hide()
+        group_layout.addWidget(self.status_label)
+        self.result_layout = QVBoxLayout()
+        self.result_layout.setContentsMargins(0, 0, 0, 0)
+        self.result_layout.setSpacing(group_layout.spacing())
+        group_layout.addLayout(self.result_layout)
+        # The note under the result lines, shown only when the desktop cannot show the icon.
+        self.note_label = ResultLabel()
+        self.note_label.hide()
+        group_layout.addWidget(self.note_label)
+        layout.addWidget(group)
+        layout.addStretch()
+        self.shortcut_finished.connect(self.show_report, Qt.ConnectionType.QueuedConnection)
+        self.facts_read.connect(self.show_facts, Qt.ConnectionType.QueuedConnection)
+        self.refresh_metrics()
+
+    def start_creation(self) -> None:
+        """Start writing the shortcut on a worker thread, unless a creation is still running."""
+        if self.creating:
+            return
+        self.creating = True
+        set_button_enabled(self.create_button, False)
+        # A report no longer shown is never drawn again by facts that arrive during this creation.
+        self.last_report = None
+        self.remove_result_labels()
+        self.status_label.setText(UtilityPageText.CREATING.value)
+        self.status_label.show()
+        hand_over = weak_signal_emitter(self, lambda page: page.shortcut_finished)
+        thread = threading.Thread(target=run_shortcut_creation, args=(self.create_shortcut, hand_over, self.log_line), name=SHORTCUT_THREAD_NAME, daemon=True)
+        thread.start()
+
+    def showEvent(self, event: QShowEvent) -> None:
+        """Read again whether the desktop can show the icon each time the page is shown, since the user may have followed the note meanwhile."""
+        super().showEvent(event)
+        self.start_fact_read()
+
+    def start_fact_read(self) -> None:
+        """Start reading the desktop icon facts on a worker thread, unless a read is still running."""
+        if self.reading_facts:
+            return
+        self.reading_facts = True
+        hand_over = weak_signal_emitter(self, lambda page: page.facts_read)
+        thread = threading.Thread(target=run_fact_read, args=(self.read_desktop_icon_facts, hand_over, self.log_line), name=DESKTOP_ICON_FACT_THREAD_NAME, daemon=True)
+        thread.start()
+
+    def show_facts(self, facts: DesktopIconFacts | None) -> None:
+        """Keep the facts read, show the note they give under the result lines, or hide it when they give none or could not be read, and draw the report shown again with them.
+
+        The facts can arrive after the click, or change while a report is shown when the page is shown again: drawing
+        the report again keeps the colour of the shortcut's line in agreement with the note.
+        """
+        self.reading_facts = False
+        self.desktop_icon_facts = facts
+        note = desktop_icon_note(facts) if facts is not None else ""
+        self.note_label.setText(note)
+        self.note_label.setVisible(bool(note))
+        if self.last_report is not None:
+            self.show_report_lines(self.last_report)
+
+    def remove_result_labels(self) -> None:
+        """Take away the result lines of the previous click."""
+        for label in self.result_labels:
+            self.result_layout.removeWidget(label)
+            label.hide()
+            label.deleteLater()
+        self.result_labels = []
+
+    def add_result_label(self, text: str, tone: ResultTone) -> None:
+        """Add one selectable result line under the previous ones, in ``tone``."""
+        label = ResultLabel()
+        label.show_result(text, tone)
+        self.result_layout.addWidget(label)
+        self.result_labels.append(label)
+
+    def show_report(self, report: ShortcutReport) -> None:
+        """Let the button be clicked again, end the wait line, then keep ``report`` and show its lines."""
+        self.creating = False
+        set_button_enabled(self.create_button, True)
+        self.status_label.clear()
+        self.status_label.hide()
+        self.last_report = report
+        self.show_report_lines(report)
+
+    def show_report_lines(self, report: ShortcutReport) -> None:
+        """Show one line per file of ``report`` in the colour of what happened to it, by the facts last read, then the command the shortcut starts.
+
+        A desktop shortcut written that the desktop will not show is shown in orange; the note stays under these
+        lines. The facts can arrive after the click or change while the report is shown: drawing it from the writer's
+        report with the latest facts keeps the shortcut's line in agreement with the note.
+        """
+        self.remove_result_labels()
+        for outcome in report_for_desktop(report, self.desktop_icon_facts).file_outcomes:
+            self.add_result_label(outcome.line(), RESULT_TONE_BY_OUTCOME_KIND[outcome.status.outcome_kind])
+        if report.start_command_line:
+            self.add_result_label(UtilityPageText.STARTS.value.format(command=report.start_command_line), ResultTone.NEUTRAL)
+
+    def refresh_metrics(self) -> None:
+        """Give the button the height of the other Settings controls for the current font."""
+        self.create_button.setMinimumHeight(control_height(self.create_button.fontMetrics().height()))