gitpane 1.0.0__py3-none-any.whl

gitpane/controller/reference_read_controller.py

@@ -0,0 +1,242 @@
+"""Read the references a repository window or a reference form shows."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QTimer
+from shiboken6 import isValid
+
+from gitpane.config import FORM_OPENING_CHECK_TIMEOUT_MS, SharedText
+from gitpane.history.file_history import WindowCapability
+from gitpane.operation.diagnostic import Diagnostic
+from gitpane.reference.stash_list import STASH_LIST_REFTABLE_CAUSE
+from gitpane.ui.reference.form_opening import close_unseen_form, refuse_form_opening
+from gitpane.ui.widget.refresh_advice import refresh_advice_text
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtWidgets import QWidget
+
+    from gitpane.controller.operation_policy import OperationPolicy
+    from gitpane.controller.session_registry import SessionRegistry
+    from gitpane.history.repository import GitRepository
+    from gitpane.history.repository_value import RepositoryContext, RequestIdentity
+    from gitpane.operation.diagnostic import DiagnosticLog
+    from gitpane.reference.reference_edit import ReferenceService
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+
+# How many times in a row a reference form is opened again because its window was refreshed before its opening check
+# answered: a third refresh in a row means the repository keeps changing, and the form is refused with the advice to
+# refresh instead of opening again for ever.
+FORM_OPENING_RESTART_LIMIT = 2
+# Operation named in the --log file when the stash list of a window could not be read.
+STASH_LIST_DIAGNOSTIC_OPERATION = "Read stash list"
+
+
+class ReferenceReadController:
+    """The reference reads of every window: the branch list and the stash list of a window, the references a form opens on, and the history built from the same capture."""
+
+    def __init__(self, *, session_registry_controller: SessionRegistry, operation_policy_controller: OperationPolicy, repository: GitRepository, reference: ReferenceService, diagnostic_log: DiagnosticLog | None) -> None:
+        """Receive the services and the lower controllers the reads use; the wiring builds it once the --log file is known, and the opening, the refresh, the replay, the stash and the forms read through it."""
+        self.session_registry_controller = session_registry_controller
+        self.operation_policy_controller = operation_policy_controller
+        self.repository = repository
+        self.reference = reference
+        self.diagnostic_log = diagnostic_log
+        self.reference_snapshot_by_session: dict[str, ReferenceSnapshot] = {}
+        self.reference_read_generation_by_session: dict[str, int] = {}
+        # The stash list cause last written to the --log file for a window: a cause that stays the same over many
+        # reference reads is written once, not on every refresh.
+        self.logged_stash_cause_by_session: dict[str, str] = {}
+        # What waits for the next reference capture of a window: the history that is built from that same capture.
+        self.reference_continuation_by_session: dict[str, Callable[[ReferenceSnapshot | None, Exception | None], None]] = {}
+        # How many times in a row the reference form being opened again in a window was restarted because its window
+        # moved on before its check answered; set only for the time of that new opening.
+        self.form_restart_count_by_session: dict[str, int] = {}
+
+    def read_references(self, session_id: str, *, previous: ReferenceSnapshot | None = None,
+                        on_complete: Callable[[ReferenceSnapshot | None, Exception | None], None] | None = None) -> None:
+        """Refresh branch choices without replacing an already opened checkout intention.
+
+        A previous capture is shown again only after its reference files are checked unchanged. A continuation waits
+        for the capture this read, or a newer read of the same window, publishes; a newer continuation replaces it.
+        Every read, a reused one included, makes any older read of the window still in flight unable to publish.
+        Every read also reads the stash list again for the left panel, a reused capture included.
+        """
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE):
+            return
+        session = self.session_registry_controller.session_by_id[session_id]
+        window = self.session_registry_controller.window_by_session[session_id]
+        generation = session.generation
+        read_generation = self.reference_read_generation_by_session.get(session_id, 0) + 1
+        self.reference_read_generation_by_session[session_id] = read_generation
+        if on_complete is not None:
+            self.reference_continuation_by_session[session_id] = on_complete
+        window.branch_selector.show_loading()
+
+        def complete(snapshot: ReferenceSnapshot | None, error: Exception | None) -> None:
+            """Discard late reads after closure or a newer history generation."""
+            if (session.is_closed or session.generation != generation or not isValid(window)
+                    or self.reference_read_generation_by_session.get(session_id) != read_generation):
+                return
+            continuation = self.reference_continuation_by_session.pop(session_id, None)
+            if error is None and not self._publish_reference_snapshot(session_id, generation, read_generation, snapshot):
+                snapshot = None
+                error = ValueError("Git or the repository changed while reading references; refresh again")
+            if error is not None:
+                window.branch_selector.show_error(str(error))
+                window.statusBar().showMessage(str(error))
+            if continuation is not None:
+                continuation(snapshot, error)
+
+        if previous is None:
+            self.reference.read(session.repository_context, self.repository.git_filename, generation, complete, with_stash_list=True)
+            return
+        self.reference.read_display(session.repository_context, self.repository.git_filename, generation, complete, previous=previous, with_stash_list=True)
+
+    def read_form_references(self, session_id: str, dialog: QWidget, context: RepositoryContext, generation: int, complete: Callable, *,
+                             menu_capture: ReferenceSnapshot | None, reopen: Callable[[ReferenceSnapshot | None], object]) -> None:
+        """Read the references a form opens on, showing the window's own capture again while its files are unchanged.
+
+        The window capture only draws the form: every submission captures its references again and checks them when
+        Git starts, so reusing it here never authorizes a write.
+
+        Any refresh of the window starts a new generation, and a form opened on an older one can no longer write. When
+        such a refresh, or a change of Git or of the management right, comes before the answer, the form, not shown
+        yet, is closed and opened again through ``reopen`` on the menu's capture moved to the window's new generation,
+        so it gets its own new check; ``complete`` is not called. Such refreshes come from GitPane itself (another
+        program moved HEAD, an operation finished in another window), never from a hand quick enough to beat the check,
+        so the user is shown nothing about them. The new check still compares the references with the menu's capture,
+        so a refresh that found them changed refuses the form as usual. Past FORM_OPENING_RESTART_LIMIT restarts in a
+        row, the form is refused with the advice to refresh instead of opening again.
+
+        Every check ends: ``complete`` shows the form or refuses it, a form it leaves hidden (its filling raised, or it
+        stopped being current) is closed unseen, and a check with no answer within FORM_OPENING_CHECK_TIMEOUT_MS
+        refuses the form, so the next click opens a new one. A second click while the form waits gives back the waiting
+        form and starts no other check: the wait lasts one reference read, and a second form or read would only cross
+        the first.
+        """
+        git_filename = self.repository.git_filename
+        restart_count = self.form_restart_count_by_session.pop(session_id, 0)
+        check_answered = False
+
+        def answered(snapshot: ReferenceSnapshot | None, error: Exception | None) -> None:
+            """Open again a form not shown yet whose window moved on; otherwise hand the answer to the form's own checks."""
+            nonlocal check_answered
+            check_answered = True
+            session = self.session_registry_controller.session_by_id.get(session_id)
+            if (isValid(dialog) and not dialog.closed and session is not None and not session.is_closed
+                    and not self._form_authority_kept(session_id, generation, context, git_filename)):
+                restart(session.generation)
+                return
+            try:
+                complete(snapshot, error)
+            finally:
+                if form_waits():
+                    close_unseen_form(dialog)
+
+        def restart(current_generation: int) -> None:
+            """Close the outdated form unseen and open it again under the window's current generation, within the restart limit."""
+            if restart_count >= FORM_OPENING_RESTART_LIMIT:
+                refuse_form_opening(dialog, refresh_advice_text(SharedText.REFERENCE_CHANGED_DURING_READING))
+                return
+            close_unseen_form(dialog)
+            capture = replace(menu_capture, generation=current_generation) if menu_capture is not None else None
+            self.form_restart_count_by_session[session_id] = restart_count + 1
+            try:
+                reopen(capture)
+            finally:
+                # An opening that stops before its own check (the right to manage lost meanwhile) leaves no count behind.
+                self.form_restart_count_by_session.pop(session_id, None)
+
+        def form_waits() -> bool:
+            """Tell whether the form is still alive and open without ever having been shown."""
+            return isValid(dialog) and not dialog.closed and not dialog.isVisible()
+
+        def give_up() -> None:
+            """Refuse a form whose check gave no answer within its limit."""
+            if not check_answered and form_waits():
+                refuse_form_opening(dialog, SharedText.FORM_CHECK_UNANSWERED.value)
+
+        # The form is the timer's context object: the timer dies with the form, and a form closed meanwhile is left as it is.
+        QTimer.singleShot(FORM_OPENING_CHECK_TIMEOUT_MS, dialog, give_up)
+        self.reference.read_display(context, git_filename, generation, answered, previous=self.reference_snapshot_by_session.get(session_id))
+
+    def form_is_current(self, session_id: str, generation: int, dialog: QWidget, dialog_by_session: dict[str, QWidget],
+                        context: RepositoryContext, git_filename: str) -> bool:
+        """Tell whether a result read for one opened form may still reach it.
+
+        The form must be alive and still be this window's form, and the window must keep the generation, repository,
+        Git and management authority the form was opened with.
+        """
+        session = self.session_registry_controller.session_by_id.get(session_id)
+        return (isValid(dialog) and not dialog.closed and dialog_by_session.get(session_id) is dialog and session is not None and not session.is_closed
+                and self._form_authority_kept(session_id, generation, context, git_filename))
+
+    def _form_authority_kept(self, session_id: str, generation: int, context: RepositoryContext, git_filename: str) -> bool:
+        """Tell whether an open window still has the generation, repository, Git and management right a form was opened with."""
+        session = self.session_registry_controller.session_by_id[session_id]
+        return (session.generation == generation and session.repository_context == context and self.repository.git_filename == git_filename
+                and self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE))
+
+    def _publish_reference_snapshot(self, session_id: str, generation: int, read_generation: int, snapshot: ReferenceSnapshot) -> bool:
+        """Show one reference capture in its window, only while that window, its authority and this very read are current.
+
+        The capture must belong to the window's repository, to the Git in use and to the generation the read was made
+        for; otherwise nothing is shown and the caller reports the read as failed. The branch list and the Stashes node
+        of the left panel are updated together from the same capture.
+        """
+        session = self.session_registry_controller.session_by_id.get(session_id)
+        window = self.session_registry_controller.window_by_session.get(session_id)
+        if (session is None or window is None or session.is_closed or not isValid(window) or not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE)
+                or session.generation != generation or self.reference_read_generation_by_session.get(session_id) != read_generation
+                or snapshot.context != session.repository_context or snapshot.git_filename != self.repository.git_filename
+                or snapshot.generation != generation):
+            return False
+        self.reference_snapshot_by_session[session_id] = snapshot
+        window.branch_selector.populate(snapshot)
+        if snapshot.stash_list is not None:
+            window.show_stashes(snapshot.stash_list)
+            self._log_stash_list_cause(session_id, snapshot)
+        return True
+
+    def _log_stash_list_cause(self, session_id: str, snapshot: ReferenceSnapshot) -> None:
+        """Write why a window's stash list could not be read to the --log file, once per new cause.
+
+        The reftable format is supported, not a failure, so its cause stays on the Stashes node only. Repeating the
+        same cause on every refresh would bury the real Git failures the log is read for.
+        """
+        cause = snapshot.stash_list.cause if snapshot.stash_list is not None else ""
+        previous_cause = self.logged_stash_cause_by_session.get(session_id, "")
+        self.logged_stash_cause_by_session[session_id] = cause
+        if not cause or cause == STASH_LIST_REFTABLE_CAUSE or cause == previous_cause or self.diagnostic_log is None:
+            return
+        self.diagnostic_log.write(Diagnostic(STASH_LIST_DIAGNOSTIC_OPERATION, snapshot.context.repository_dir, "", [], cause).prepare())
+
+    def read_history_with_references(self, session_id: str, identity: RequestIdentity, committed_parent_oid: str | None = None, *,
+                                     previous: ReferenceSnapshot | None = None,
+                                     before_history: Callable[[ReferenceSnapshot | None, Exception | None], None] | None = None) -> None:
+        """Read the branch list, then build the history of this request from that very capture.
+
+        A window that cannot manage its repository has no branch list, so its history reads its own references. When
+        the reference capture fails, the branch list shows the error and the history still reads its own references,
+        so an empty graph is never the result of a failed branch list. ``previous`` is a capture that may be shown
+        again after its files are checked unchanged; ``before_history`` decides, from the capture, what else the
+        refresh must read before the history starts.
+        """
+        if not self.operation_policy_controller.allows(session_id, WindowCapability.MANAGE):
+            self.repository.read_snapshot(identity, committed_parent_oid)
+            return
+
+        def start_history(snapshot: ReferenceSnapshot | None, error: Exception | None) -> None:
+            """Start the history only for the request that asked for it, never for a replaced one."""
+            if self.session_registry_controller.identity_by_session.get(session_id) != identity:
+                return
+            if before_history is not None:
+                before_history(snapshot, error)
+            self.repository.read_snapshot(identity, committed_parent_oid, reference_snapshot=snapshot if error is None else None)
+
+        self.read_references(session_id, previous=previous, on_complete=start_history)