gitpane 1.0.0__py3-none-any.whl

gitpane/system/desktop_icon_support.py

@@ -0,0 +1,270 @@
+"""Decide whether the user's desktop can show a desktop icon, with the steps that would let it.
+
+Every function is pure: it receives the facts it judges (system, desktop, distribution, extension state, desktop
+folder), read elsewhere, so each case can be checked from any system. A desktop that needs an extension to show icons
+is one row of the desktop table, and the command that installs that extension on a distribution is one row of the
+distribution table: adding a desktop or a distribution adds a row, without touching Settings or the shortcut writer.
+The commands the note shows come only from these tables, and the desktop folder only through the system's quoting;
+nothing read from the machine ever becomes a command.
+"""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from gitpane.config import LINUX_PLATFORM
+from gitpane.system.desktop_shortcut import ShortcutOutcome, ShortcutReport, ShortcutStatus
+from gitpane.system.installed_launcher import command_line
+from gitpane.system.linux_distribution import DistributionFamily, distribution_family
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+DESKTOP_ICONS_EXTENSION_UUID = "ding@rastersoft.com"
+DESKTOP_ICONS_EXTENSION_NAME = "Desktop Icons NG"
+GNOME_EXTENSIONS_PROGRAM = "gnome-extensions"
+GNOME_EXTENSIONS_ENABLE_ARGUMENT = "enable"
+GNOME_DESKTOP_NAME = "gnome"
+MKDIR_PROGRAM = "mkdir"
+NOTE_LINE_END = "\n"
+# The note's layout: each step indented under the introduction, its command alone on the next line, aligned under the
+# step's text, so a beginner copies exactly one command.
+NOTE_STEP_INDENT = "  "
+NOTE_COMMAND_INDENT = "       "
+NOTE_STEP_TEMPLATE = "{indent}{number}. {text}"
+FIRST_STEP_NUMBER = 1
+APPLICATIONS_LIST_PLACE_TEMPLATE = " ({place})"
+
+
+class ExtensionState(Enum):
+    """What GitPane knows of a GNOME Shell extension; UNKNOWN when it could not read it."""
+
+    UNKNOWN = "unknown"
+    NOT_INSTALLED = "not installed"
+    INSTALLED_NOT_LOADED = "installed, not loaded"
+    """Its files are on the disk, but the Shell only reads its extension folders when the session starts."""
+    INACTIVE = "inactive"
+    ACTIVE = "active"
+
+
+# The states in which an installed or missing extension keeps desktop icons from showing; UNKNOWN is never one of
+# them, so a state GitPane could not read never gives a note.
+ICON_HIDING_EXTENSION_STATE_SET = frozenset({ExtensionState.NOT_INSTALLED, ExtensionState.INSTALLED_NOT_LOADED, ExtensionState.INACTIVE})
+
+
+@dataclass(frozen=True)
+class DesktopIconRule:
+    """How one desktop shows icons from the desktop folder: through an extension to install then enable, and where it lists applications."""
+
+    desktop_label: str
+    extension_uuid: str
+    extension_name: str
+    enable_command: str
+    applications_list_place: str
+
+
+# A desktop missing from this table shows its desktop icons itself or is not known: it gets no extension note. The
+# name is the first, most specific one of XDG_CURRENT_DESKTOP, lowercased: Ubuntu's GNOME declares "ubuntu:GNOME" and
+# runs the extension through its own session mode, so it has no row.
+DESKTOP_ICON_RULE_BY_DESKTOP_NAME = {
+    GNOME_DESKTOP_NAME: DesktopIconRule("GNOME", DESKTOP_ICONS_EXTENSION_UUID, DESKTOP_ICONS_EXTENSION_NAME,
+                                        shlex.join((GNOME_EXTENSIONS_PROGRAM, GNOME_EXTENSIONS_ENABLE_ARGUMENT, DESKTOP_ICONS_EXTENSION_UUID)), "the search of Activities"),
+}
+
+
+@dataclass(frozen=True)
+class DistributionRule:
+    """The command that installs each extension from one distribution's packages; an extension it does not list is installed in words."""
+
+    install_command_by_extension_uuid: Mapping[str, str]
+
+
+# One row per family of distributions, the family os-release describes; a family without a row gets the default row.
+DISTRIBUTION_RULE_BY_FAMILY: dict[DistributionFamily, DistributionRule] = {
+    DistributionFamily.DEBIAN: DistributionRule({DESKTOP_ICONS_EXTENSION_UUID: "sudo apt install gnome-shell-extension-desktop-icons-ng"}),
+}
+DEFAULT_DISTRIBUTION_RULE = DistributionRule({})
+
+
+@dataclass(frozen=True)
+class DesktopIconFacts:
+    """What the desktop icon decision judges, read from the session: system, first desktop name, os-release, extension state and desktop folder.
+
+    ``desktop_name`` is empty outside Linux or when the session declares no desktop, and ``desktop_dir`` is empty when
+    the system names no desktop folder.
+    """
+
+    platform: str
+    desktop_name: str
+    os_release_by_key: Mapping[str, str]
+    extension_state: ExtensionState
+    desktop_dir: str
+    desktop_dir_exists: bool
+
+
+class DesktopIconNoteText(Enum):
+    """Texts of the note that says why no desktop icon can show and how to get one; ``{desktop}``, ``{extension}``, ``{folder}`` and ``{place}`` are filled in."""
+
+    NOT_INSTALLED_REASON = "{desktop} shows no icons on the desktop without the {extension} extension, which is not installed."
+    NOT_LOADED_REASON = "{desktop} shows no icons on the desktop without the {extension} extension, which is installed but not loaded yet."
+    INACTIVE_REASON = "{desktop} shows no icons on the desktop without the {extension} extension, which is installed but not enabled."
+    DESKTOP_FOLDER_MISSING_REASON = "The desktop folder {folder} does not exist, and GitPane never creates it."
+    DESKTOP_FOLDER_UNNAMED_REASON = "The system names no desktop folder."
+    STEPS_INTRO = "To get a GitPane icon on the desktop:"
+    RUN_IN_TERMINAL = "In a terminal, run:"
+    LOG_OUT_AND_BACK_IN = "Log out, then log back in."
+    INSTALL_FROM_DISTRIBUTION = "Install the {extension} extension of your distribution."
+    CLICK_AGAIN = "Click the button above again."
+    FALLBACK_AFTER_STEPS = "Without these steps, the button above still adds GitPane to the applications list{place}."
+    FALLBACK_WITHOUT_STEPS = "The button above still adds GitPane to the applications list{place}."
+    CANNOT_SHOW_ICONS = "{desktop} cannot show desktop icons without the {extension} extension"
+    """The detail of the orange line of a shortcut written that the desktop will not show yet."""
+
+
+@dataclass(frozen=True)
+class NoteStep:
+    """One numbered step of the note: what to do, and the command to type alone on the next line when there is one."""
+
+    text: str
+    command: str = ""
+
+
+def distribution_rule(os_release_by_key: Mapping[str, str]) -> DistributionRule:
+    """Return the row of the family of distributions os-release describes, otherwise the default row.
+
+    The family comes from ``gitpane.system.linux_distribution``, which reads ID then each word of ID_LIKE: Ubuntu,
+    Linux Mint and a derivative that only says ``ID_LIKE=ubuntu`` all find Debian's row.
+    """
+    return DISTRIBUTION_RULE_BY_FAMILY.get(distribution_family(os_release_by_key), DEFAULT_DISTRIBUTION_RULE)
+
+
+def desktop_icon_rule(platform: str, desktop_name: str) -> DesktopIconRule | None:
+    """Return the row of a Linux desktop that needs an extension to show desktop icons, or None for any other desktop or system."""
+    if platform != LINUX_PLATFORM:
+        return None
+    return DESKTOP_ICON_RULE_BY_DESKTOP_NAME.get(desktop_name)
+
+
+def extension_keeps_icons_hidden(facts: DesktopIconFacts) -> bool:
+    """Tell whether the desktop of ``facts`` needs an extension that is missing, not loaded yet or not enabled, so it shows no desktop icon."""
+    return desktop_icon_rule(facts.platform, facts.desktop_name) is not None and facts.extension_state in ICON_HIDING_EXTENSION_STATE_SET
+
+
+def extension_reason_text(extension_state: ExtensionState) -> DesktopIconNoteText:
+    """Return the sentence that says why the extension shows no icons, for a state that keeps them hidden."""
+    if extension_state is ExtensionState.INACTIVE:
+        return DesktopIconNoteText.INACTIVE_REASON
+    if extension_state is ExtensionState.INSTALLED_NOT_LOADED:
+        return DesktopIconNoteText.NOT_LOADED_REASON
+    return DesktopIconNoteText.NOT_INSTALLED_REASON
+
+
+def extension_install_step(rule: DesktopIconRule, distribution: DistributionRule) -> NoteStep:
+    """Return the step that installs the extension: the distribution's command, or the same request in words when its row has none."""
+    install_command = distribution.install_command_by_extension_uuid.get(rule.extension_uuid, "")
+    if install_command:
+        return NoteStep(DesktopIconNoteText.RUN_IN_TERMINAL.value, install_command)
+    return NoteStep(DesktopIconNoteText.INSTALL_FROM_DISTRIBUTION.value.format(extension=rule.extension_name))
+
+
+def extension_steps(extension_state: ExtensionState, rule: DesktopIconRule, distribution: DistributionRule) -> list[NoteStep]:
+    """Return the steps left before the extension shows icons: install, log out and back in, then enable, keeping only what its state still needs.
+
+    The Shell reads its extension folders only when the session starts, so an extension installed during the session
+    can only be enabled after logging out and back in; once enabled, the Shell runs it at once.
+    """
+    enable_step = NoteStep(DesktopIconNoteText.RUN_IN_TERMINAL.value, rule.enable_command)
+    if extension_state is ExtensionState.INACTIVE:
+        return [enable_step]
+    log_out_step = NoteStep(DesktopIconNoteText.LOG_OUT_AND_BACK_IN.value)
+    if extension_state is ExtensionState.INSTALLED_NOT_LOADED:
+        return [log_out_step, enable_step]
+    return [extension_install_step(rule, distribution), log_out_step, enable_step]
+
+
+def desktop_folder_reason_and_steps(facts: DesktopIconFacts) -> tuple[str, list[NoteStep]] | None:
+    """Return why the desktop folder keeps a shortcut from being written, with the steps that would let it, or None when the folder is there.
+
+    The folder is quoted the way the system's own shell reads it back, so a path with spaces or quotes stays one
+    command; GitPane only shows that command and never runs it.
+    """
+    if not facts.desktop_dir:
+        return DesktopIconNoteText.DESKTOP_FOLDER_UNNAMED_REASON.value, []
+    if facts.desktop_dir_exists:
+        return None
+    create_step = NoteStep(DesktopIconNoteText.RUN_IN_TERMINAL.value, command_line((MKDIR_PROGRAM, facts.desktop_dir), facts.platform))
+    return DesktopIconNoteText.DESKTOP_FOLDER_MISSING_REASON.value.format(folder=facts.desktop_dir), [create_step, NoteStep(DesktopIconNoteText.CLICK_AGAIN.value)]
+
+
+def numbered_step_lines(steps: list[NoteStep]) -> list[str]:
+    """Write the steps as one numbered list, each command alone on the line under its step."""
+    lines = []
+    for number, step in enumerate(steps, start=FIRST_STEP_NUMBER):
+        lines.append(NOTE_STEP_TEMPLATE.format(indent=NOTE_STEP_INDENT, number=number, text=step.text))
+        if step.command:
+            lines.append(NOTE_COMMAND_INDENT + step.command)
+    return lines
+
+
+def desktop_icon_note(facts: DesktopIconFacts) -> str:
+    """Write the note that says why no desktop icon can show and how to get one, or an empty text when nothing keeps one from showing.
+
+    One sentence per cause, the extension first and the desktop folder next, then the steps of both in one numbered
+    list. On Linux, a last sentence says that the button still adds GitPane to the applications list. The note and the
+    orange line of the report ask the same rule, ``extension_keeps_icons_hidden``, so they never disagree.
+    """
+    reasons = []
+    steps: list[NoteStep] = []
+    rule = desktop_icon_rule(facts.platform, facts.desktop_name)
+    # Whether the extension hides the icons is the question the orange line asks too; ``rule is not None`` stays only so
+    # that the rule's labels can be read below.
+    if rule is not None and extension_keeps_icons_hidden(facts):
+        reasons.append(extension_reason_text(facts.extension_state).value.format(desktop=rule.desktop_label, extension=rule.extension_name))
+        steps.extend(extension_steps(facts.extension_state, rule, distribution_rule(facts.os_release_by_key)))
+    folder_reason_and_steps = desktop_folder_reason_and_steps(facts)
+    if folder_reason_and_steps is not None:
+        folder_reason, folder_steps = folder_reason_and_steps
+        reasons.append(folder_reason)
+        steps.extend(folder_steps)
+    if not reasons:
+        return ""
+    lines = list(reasons)
+    if steps:
+        lines.append(DesktopIconNoteText.STEPS_INTRO.value)
+        lines.extend(numbered_step_lines(steps))
+    if facts.platform == LINUX_PLATFORM:
+        place = APPLICATIONS_LIST_PLACE_TEMPLATE.format(place=rule.applications_list_place) if rule is not None else ""
+        fallback = DesktopIconNoteText.FALLBACK_AFTER_STEPS if steps else DesktopIconNoteText.FALLBACK_WITHOUT_STEPS
+        lines.append(fallback.value.format(place=place))
+    return NOTE_LINE_END.join(lines)
+
+
+def report_for_desktop(report: ShortcutReport, facts: DesktopIconFacts | None) -> ShortcutReport:
+    """Return the shortcut report as the desktop will show it: a desktop shortcut written that the desktop keeps hidden becomes an orange line pointing at the note.
+
+    The orange line says only what is true of this click: it says GitPane is added to the applications list only when
+    the same report holds the line of that entry written, so it never contradicts a red entry line under it. Every
+    other line and the command stay as the writer gave them; with no facts read, or facts that hide nothing, the
+    report is returned unchanged.
+    """
+    if facts is None or not extension_keeps_icons_hidden(facts):
+        return report
+    rule = desktop_icon_rule(facts.platform, facts.desktop_name)
+    if rule is None:
+        return report
+    hidden_detail = DesktopIconNoteText.CANNOT_SHOW_ICONS.value.format(desktop=rule.desktop_label, extension=rule.extension_name)
+    entry_added = False
+    for outcome in report.file_outcomes:
+        if outcome.status is ShortcutStatus.APPLICATION_ENTRY_ADDED:
+            entry_added = True
+    hidden_status = ShortcutStatus.CREATED_NOT_SHOWN if entry_added else ShortcutStatus.CREATED_NOT_SHOWN_ENTRY_FAILED
+    file_outcomes = []
+    for outcome in report.file_outcomes:
+        if outcome.status is ShortcutStatus.CREATED:
+            file_outcomes.append(ShortcutOutcome(hidden_status, hidden_detail))
+        else:
+            file_outcomes.append(outcome)
+    return replace(report, file_outcomes=tuple(file_outcomes))