gitpane 1.0.0__py3-none-any.whl

gitpane/text/typed_path.py

@@ -0,0 +1,75 @@
+"""Turn a path the user typed into the path GitPane uses, expanding ~ to the home folder where that is the usage."""
+
+from __future__ import annotations
+
+import os
+
+# Only Linux and macOS expand ~, and both write their paths the POSIX way: posixpath gives the same answer when the
+# tests of these two systems run on Windows, where os.path would be ntpath.
+import posixpath
+import sys
+from typing import TYPE_CHECKING
+
+from gitpane.config import LINUX_PLATFORM, MACOS_PLATFORM
+from gitpane.text.typed_text import typed_value
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+HOME_SHORTHAND = "~"
+HOME_SHORTHAND_SEPARATOR = "/"
+HOME_SHORTHAND_PLATFORM_SET = frozenset({LINUX_PLATFORM, MACOS_PLATFORM})
+
+
+def expanded_typed_path(path: str, platform: str, home_dir: str) -> str:
+    """Return the path to use for ``path`` as typed on ``platform``, ``~`` alone or ``~/`` at its start standing for ``home_dir``.
+
+    A shell on Linux and macOS reads ``~`` as the home folder, so a path copied from a terminal works as typed. Windows
+    keeps the text as typed: ``~`` is not the usage there, and ``~`` is a valid character of a folder name. ``~name``,
+    the home folder of another user, stays as typed: expanding it would mean reading the system's user database. A
+    ``~`` anywhere else than at the start, an unknown system, and a home folder that is empty or not absolute leave the
+    path as typed too, so nothing is ever guessed. ``~``, ``~/`` and ``~//`` give the home folder as it is, without a
+    trailing separator, so a Clone destination typed ``~/`` is saved as the same folder typed without the ``/``.
+    """
+    if platform not in HOME_SHORTHAND_PLATFORM_SET:
+        return path
+    if not home_dir or not posixpath.isabs(home_dir):
+        return path
+    if path == HOME_SHORTHAND:
+        return home_dir
+    if not path.startswith(HOME_SHORTHAND + HOME_SHORTHAND_SEPARATOR):
+        return path
+    rest = path[len(HOME_SHORTHAND):].lstrip(HOME_SHORTHAND_SEPARATOR)
+    if not rest:
+        return home_dir
+    return posixpath.join(home_dir, rest)
+
+
+def session_typed_path(path: str) -> str:
+    """Return the path to use for ``path`` as typed in this session, on this system and with this user's home folder."""
+    return expanded_typed_path(path, sys.platform, os.path.expanduser(HOME_SHORTHAND))
+
+
+def typed_path_value(text: str, typed_path: Callable[[str], str]) -> str:
+    """Return the value a path field hands to its action: ``text`` without the blanks around it, then read by ``typed_path``.
+
+    The blanks go first, so that a ``~/`` path pasted with a blank in front still stands for the home folder. Every path
+    field reads its text through here, so the blanks and ``~`` are read in one place for all of them. ``typed_path`` is
+    asked for, never taken by default: each window hands its injected reading, which the tests replace with their own
+    system and home folder. Nothing is read from the disk.
+    """
+    return typed_path(typed_value(text))
+
+
+def typed_start_dir(text: str, typed_path: Callable[[str], str]) -> str:
+    """Return the folder a chooser next to a path field starts from: the path the field stands for, when it is absolute.
+
+    The field's value is read like its action reads it, blanks dropped and ``~`` read where that is the usage, so the
+    chooser opens where the typed path points. A value that is not absolute on this system gives an empty folder, and
+    the chooser then starts from its own folder, or from the fallback the window gives; a remote address is never
+    absolute, so it never names a start folder. Nothing is read from the disk.
+    """
+    value = typed_path_value(text, typed_path)
+    if not os.path.isabs(value):
+        return ""
+    return value

gitpane/text/typed_text.py

@@ -0,0 +1,17 @@
+"""What GitPane uses of a text the user typed: the text without the blanks around it."""
+
+from __future__ import annotations
+
+
+def typed_value(text: str) -> str:
+    """Return the typed text without the blanks around it, its inside untouched.
+
+    Spaces, tabs, line ends and no-break spaces go from both ends; inner spaces, lines and blank lines stay exactly as
+    typed, and a text made only of blanks becomes empty, so it counts as an empty field. A name, a path or an address
+    pasted with a space around it would otherwise be refused by Git or open nothing, while a message keeps its inner
+    lines. The field itself is never rewritten: only the value GitPane uses loses its blanks.
+
+    Not for secrets typed as they are (passwords, tokens, answers to an SSH question), where a space may be part of the
+    secret, nor for search fields, where spaces are part of what is searched.
+    """
+    return text.strip()

gitpane/thread/weak_signal.py

@@ -0,0 +1,93 @@
+"""Hand something over from a background thread to the thread of a Qt object, without keeping that object alive."""
+
+from __future__ import annotations
+
+import functools
+import weakref
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QCoreApplication, QObject, Signal, Slot
+from shiboken6 import isValid
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtCore import SignalInstance
+
+
+class SignalRelay(QObject):
+    """A Qt object of the window's thread that background threads signal in place of the window, which then signals the window on that thread.
+
+    A window can be destroyed on its own thread at any moment, for example the user closing a form while a check still
+    runs. A worker that emitted the window's own signal could do so while Qt is destroying it on the other thread, which
+    PySide then refuses with an error raised on the worker, or worse, since touching a Qt object under destruction from
+    another thread is undefined in C++. The worker only ever emits this relay's signal; Qt queues it to the relay's
+    thread, the window's own, where the relay finds out whether the window still exists before emitting its signal.
+    """
+
+    handed_over = Signal(object, object, object)
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.handed_over.connect(self.deliver)
+
+    @Slot(object, object, object)
+    def deliver(self, owner_reference: weakref.ref[QObject], signal_of: Callable[[QObject], SignalInstance], arguments: tuple[object, ...]) -> None:
+        """On the owner's thread, emit the arguments through the owner's signal, or drop them when the owner is gone or being destroyed."""
+        owner = owner_reference()
+        if owner is None or not isValid(owner):
+            return
+        signal_of(owner).emit(*arguments)
+
+
+@functools.cache
+def window_thread_relay() -> SignalRelay:
+    """Return the one relay of the window thread, the application's thread, whichever thread asks for it first.
+
+    One relay serves every window, so opening and closing windows leaves no relay behind. A Qt object belongs to the
+    thread that makes it, so a relay made by a first call on a worker is moved to the application's thread: cached on
+    the worker's thread, it would refuse every window for the rest of the process. Before any application exists there
+    is no such thread, and the relay stays on the thread that made it. It has no Qt parent and this cache keeps it until
+    the interpreter ends: it is never deleted while a worker may still signal it, and never from a worker thread, which
+    dropping the last Python reference of a relay there would do.
+    """
+    relay = SignalRelay()
+    application = QCoreApplication.instance()
+    if application is not None and relay.thread() is not application.thread():
+        relay.moveToThread(application.thread())
+    return relay
+
+
+def weak_signal_emitter[OwnerT: QObject](owner: OwnerT, signal_of: Callable[[OwnerT], SignalInstance]) -> Callable[..., None]:
+    """Return a function a background check calls on its threads to hand something over to the owner's own thread.
+
+    Called on the owner's thread, the window thread. The function emits the relay's signal, never the owner's: the
+    relay emits the owner's signal that ``signal_of`` picks on the owner's thread, where the owner connects it with a
+    queued connection. It holds the owner only weakly: the check, and a thread blocked on a sleeping disk, must not keep
+    a closed window's Python object alive, nor tie it to the check in a cycle only the garbage collector would break.
+    """
+    relay = window_thread_relay()
+    if owner.thread() is not relay.thread():
+        message = "weak_signal_emitter serves Qt objects of the window thread only"
+        raise ValueError(message)
+    owner_reference = weakref.ref(owner)
+
+    def emit(*arguments: object) -> None:
+        """Hand the arguments over to the relay, which emits them through the owner's signal if the owner still exists then."""
+        relay.handed_over.emit(owner_reference, signal_of, arguments)
+
+    return emit
+
+
+def hand_over_to_the_page(hand_over: Callable[[object], None], answer: object) -> None:
+    """Hand ``answer`` over to the thread of the window or page that waits for it, saying nothing when it cannot be handed over.
+
+    A window closed while the worker ran no longer raises anything: the relay drops its answer on the window's thread.
+    The relay itself is only deleted by the clean-up PySide may run as the interpreter ends, while a daemon worker can
+    still answer; Qt then refuses to emit through the deleted relay with ``RuntimeError``, and that answer has no window
+    left to show it either.
+    """
+    try:
+        hand_over(answer)
+    except RuntimeError:
+        pass

gitpane/tool/app_bundle.py

@@ -0,0 +1,164 @@
+"""Read macOS applications (``.app`` folders) with neither Qt nor any child process.
+
+An application on macOS is a folder: its ``Contents/Info.plist`` names the program under ``Contents/MacOS`` and the
+identifier the system knows the application by. GitPane reads it to know which applications are installed and which
+program to start, for terminals and text editors. Reading a few small files costs no process, unlike asking Spotlight,
+which may also be switched off.
+
+Everything a bundle declares is data written by whoever made the bundle, so a declared program is only accepted when it
+is a plain file name that really is an executable file inside the bundle.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import xml.parsers.expat
+from dataclasses import dataclass
+
+BUNDLE_SUFFIX = ".app"
+CONTENTS_DIR_BASENAME = "Contents"
+INFO_PLIST_BASENAME = "Info.plist"
+MACOS_DIR_BASENAME = "MacOS"
+# Keys of Info.plist: the name of the program under Contents/MacOS, and the identifier that names the application
+# whatever its folder is called.
+BUNDLE_EXECUTABLE_KEY = "CFBundleExecutable"
+BUNDLE_IDENTIFIER_KEY = "CFBundleIdentifier"
+# TextEdit returns as soon as the file is open, so it is recognised by its identifier, which a renamed folder keeps.
+TEXTEDIT_BUNDLE_IDENTIFIER = "com.apple.TextEdit"
+# Where applications are installed, searched in this order: the shared folder, the applications macOS ships, its
+# utilities (Terminal), then the user's own folder, where JetBrains Toolbox puts its IDEs.
+SHARED_APPLICATIONS_DIR = "/Applications"
+SYSTEM_APPLICATIONS_DIR = "/System/Applications"
+APPLICATION_SEARCH_DIRS = (
+    SHARED_APPLICATIONS_DIR,
+    SYSTEM_APPLICATIONS_DIR,
+    os.path.join(SYSTEM_APPLICATIONS_DIR, "Utilities"),
+    os.path.expanduser(os.path.join("~", "Applications")),
+)
+# What plistlib raises on a file it cannot read: a missing or unreadable file, a broken or truncated XML or binary plist,
+# and an XML plist that declares an entity, which plistlib refuses on purpose.
+PLIST_READ_ERRORS = (OSError, ValueError, plistlib.InvalidFileException, xml.parsers.expat.ExpatError)
+
+
+@dataclass(frozen=True)
+class AppBundle:
+    """An application folder with the program it starts and the identifier it declares (empty when it declares none)."""
+
+    bundle_dir: str
+    executable_filename: str
+    identifier: str
+
+
+def _is_executable_file(filename: str) -> bool:
+    """Tell whether ``filename`` is a regular file this user may run; a folder never is."""
+    return os.path.isfile(filename) and os.access(filename, os.X_OK)
+
+
+def _is_plain_name(name: object) -> bool:
+    """Tell whether ``name`` is a non-empty file name with no folder in it and is neither ``.`` nor ``..``."""
+    if not isinstance(name, str) or not name:
+        return False
+    if name in (os.curdir, os.pardir):
+        return False
+    for separator in (os.sep, os.altsep):
+        if separator and separator in name:
+            return False
+    return True
+
+
+def read_bundle(bundle_dir: str) -> AppBundle | None:
+    """Read the program and identifier a ``.app`` folder declares, or None when it is not a readable application.
+
+    Both XML and binary Info.plist files are read. The declared program must be a plain name, since it comes from the
+    bundle, and must be an executable file under ``Contents/MacOS``; anything else gives None instead of raising, so a
+    broken or crafted application is simply not offered.
+    """
+    try:
+        with open(os.path.join(bundle_dir, CONTENTS_DIR_BASENAME, INFO_PLIST_BASENAME), "rb") as stream:
+            info_by_key = plistlib.load(stream)
+    except PLIST_READ_ERRORS:
+        return None
+    if not isinstance(info_by_key, dict):
+        return None
+    executable_basename = info_by_key.get(BUNDLE_EXECUTABLE_KEY)
+    if not _is_plain_name(executable_basename):
+        return None
+    executable_filename = os.path.join(bundle_dir, CONTENTS_DIR_BASENAME, MACOS_DIR_BASENAME, executable_basename)
+    if not _is_executable_file(executable_filename):
+        return None
+    identifier = info_by_key.get(BUNDLE_IDENTIFIER_KEY)
+    if not isinstance(identifier, str):
+        identifier = ""
+    return AppBundle(bundle_dir, executable_filename, identifier)
+
+
+def bundled_program(bundle_dir: str, relative_parts: tuple[str, ...]) -> str:
+    """Return the program at ``relative_parts`` inside ``bundle_dir`` when it is an executable file there, else ``""``.
+
+    Some applications ship their command line tool at a known place other than the declared program (an editor's
+    ``code`` or ``subl``). Those places are written in GitPane's own tables, so a part that is not a plain name is a
+    programming error and raises ValueError, which also keeps the result inside the bundle.
+    """
+    for part in relative_parts:
+        if not _is_plain_name(part):
+            raise ValueError(f"Bundle path part {part!r} is not a plain file name")
+    program_filename = os.path.join(bundle_dir, *relative_parts)
+    if not _is_executable_file(program_filename):
+        return ""
+    return program_filename
+
+
+def find_application(bundle_basenames: tuple[str, ...], search_dirs: tuple[str, ...] = APPLICATION_SEARCH_DIRS) -> AppBundle | None:
+    """Return the first readable application named in ``bundle_basenames``, searching each folder for every name before the next folder.
+
+    The names are known, so no folder is listed: the order comes from the arguments alone, never from the order the
+    file system returns entries in. A missing or unreadable folder, or a candidate that is not a readable application,
+    is passed over.
+    """
+    for search_dir in search_dirs:
+        for bundle_basename in bundle_basenames:
+            bundle_dir = os.path.join(search_dir, bundle_basename)
+            if not os.path.isdir(bundle_dir):
+                continue
+            bundle = read_bundle(bundle_dir)
+            if bundle is not None:
+                return bundle
+    return None
+
+
+def enclosing_bundle_dir(filename: str) -> str:
+    """Return the innermost ``.app`` folder that holds ``filename`` (or is ``filename``), or ``""`` when there is none.
+
+    A program typed by hand may sit inside an application; climbing to that application lets GitPane judge the
+    application, for instance refuse TextEdit, and not only the program.
+    """
+    current_filename = filename
+    while current_filename:
+        if os.path.basename(current_filename).endswith(BUNDLE_SUFFIX):
+            return current_filename
+        parent_filename = os.path.dirname(current_filename)
+        if parent_filename == current_filename:
+            return ""
+        current_filename = parent_filename
+    return ""
+
+
+def is_textedit(bundle: AppBundle) -> bool:
+    """Tell whether ``bundle`` is TextEdit, by its identifier, so a renamed folder neither hides it nor imitates it."""
+    return bundle.identifier == TEXTEDIT_BUNDLE_IDENTIFIER
+
+
+def chosen_application_program(filename: str) -> str:
+    """Return the program a file picked in a file chooser stands for: a readable ``.app`` folder gives the program it declares.
+
+    The macOS file panel returns an application as its folder, which cannot be started as a command. Any other file,
+    and an application GitPane cannot read, is returned as picked, so the usual check of the field reports it.
+    """
+    bundle_dir = filename.rstrip(os.sep) or filename
+    if not bundle_dir.endswith(BUNDLE_SUFFIX):
+        return filename
+    bundle = read_bundle(bundle_dir)
+    if bundle is None:
+        return filename
+    return bundle.executable_filename

gitpane/tool/desktop_text_editor.py

@@ -0,0 +1,156 @@
+"""Name the application the desktop opens for a plain text file, read from its mimeapps.list files only.
+
+The files are read in the order of the freedesktop MIME Applications specification, and only their
+``[Default Applications]`` group counts: it holds what the user, the distribution or the desktop chose. The cache of
+MIME types (``mimeinfo.cache``) is never read: it lists every application that can open a text file, a word processor
+included, so its first entry is not a choice anybody made. The identifier found only picks one of GitPane's known
+editor presets; nothing of the desktop file it names is read or started.
+
+Every function but the last receives the environment, the home folder, the system, the Flatpak installations and the
+file readers it uses, so the rule can be checked from any system without touching the real session; the last one reads
+the session.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+import sys
+from typing import TYPE_CHECKING
+
+from gitpane.config import LINUX_PLATFORM
+from gitpane.system.xdg_session import desktop_names, xdg_config_dirs, xdg_config_home, xdg_data_dirs, xdg_data_home
+from gitpane.tool.editor_recipe import FLATPAK_EXPORTED_APPLICATION_PARTS, editor_platform, flatpak_installation_dirs
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+PLAIN_TEXT_MIME_TYPE = "text/plain"
+DEFAULT_APPLICATIONS_SECTION = "Default Applications"
+MIMEAPPS_BASENAME = "mimeapps.list"
+DESKTOP_MIMEAPPS_SUFFIX = "-mimeapps.list"
+# Not in the specification, but GLib still reads it in the data folders and older distributions ship it.
+DEFAULTS_LIST_BASENAME = "defaults.list"
+APPLICATIONS_DIR_BASENAME = "applications"
+DESKTOP_ID_SEPARATOR = ";"
+MIMEAPPS_ENCODING = "utf-8"
+# A desktop file identifier names a file directly inside an applications folder; one with a slash names nothing there.
+DESKTOP_ID_FORBIDDEN_SEPARATOR = "/"
+
+
+def application_dirs(environment_by_name: Mapping[str, str], home_dir: str) -> list[str]:
+    """List the applications folders of the data folders, the user's first, where desktop files and the deprecated mimeapps.list live."""
+    application_folder_dirs = [os.path.join(xdg_data_home(environment_by_name, home_dir), APPLICATIONS_DIR_BASENAME)]
+    for data_dir in xdg_data_dirs(environment_by_name):
+        application_folder_dirs.append(os.path.join(data_dir, APPLICATIONS_DIR_BASENAME))
+    return application_folder_dirs
+
+
+def desktop_file_dirs(environment_by_name: Mapping[str, str], home_dir: str, flatpak_dirs: tuple[str, ...]) -> list[str]:
+    """List the folders an installed application's desktop file can be in: the applications folders of the data folders, then the one each Flatpak installation exports.
+
+    The session adds the Flatpak export folders to its data folders only when it opens, so an editor installed from
+    Flatpak during the session is not in them yet; its installation already exports its desktop file.
+    """
+    folder_dirs = application_dirs(environment_by_name, home_dir)
+    for flatpak_dir in flatpak_dirs:
+        folder_dirs.append(os.path.join(flatpak_dir, *FLATPAK_EXPORTED_APPLICATION_PARTS))
+    return folder_dirs
+
+
+def mimeapps_filenames(environment_by_name: Mapping[str, str], home_dir: str) -> list[str]:
+    """List the files that can name a default application, most important first.
+
+    The user's configuration folder, then each system configuration folder, then the applications folder of the user's
+    data folder, then that of each system data folder. In each folder, the file of each desktop named by
+    XDG_CURRENT_DESKTOP, most specific first, comes before the common file. The ``defaults.list`` of the data folders
+    come after all of them.
+    """
+    names = desktop_names(environment_by_name)
+    data_application_dirs = application_dirs(environment_by_name, home_dir)
+    searched_dirs = [xdg_config_home(environment_by_name, home_dir), *xdg_config_dirs(environment_by_name), *data_application_dirs]
+    filenames = []
+    for searched_dir in searched_dirs:
+        for name in names:
+            filenames.append(os.path.join(searched_dir, name + DESKTOP_MIMEAPPS_SUFFIX))
+        filenames.append(os.path.join(searched_dir, MIMEAPPS_BASENAME))
+    for data_application_dir in data_application_dirs:
+        filenames.append(os.path.join(data_application_dir, DEFAULTS_LIST_BASENAME))
+    return filenames
+
+
+def default_desktop_ids(text: str) -> list[str]:
+    """List, in order, the desktop file identifiers one mimeapps.list text names as default for plain text, or none.
+
+    The keys keep their case, since MIME types are written in lower case and a differently written key is another key;
+    ``%`` is plain text, and a repeated group is merged as GLib does. A text that is not a key file gives nothing.
+    """
+    parser = configparser.ConfigParser(interpolation=None, strict=False, delimiters=("=",), comment_prefixes=("#",))
+    # The parser lowercases keys by default; keyfile keys are case sensitive.
+    parser.optionxform = str
+    try:
+        parser.read_string(text)
+    except configparser.Error:
+        return []
+    if not parser.has_option(DEFAULT_APPLICATIONS_SECTION, PLAIN_TEXT_MIME_TYPE):
+        return []
+    desktop_ids = []
+    for desktop_id in parser.get(DEFAULT_APPLICATIONS_SECTION, PLAIN_TEXT_MIME_TYPE).split(DESKTOP_ID_SEPARATOR):
+        stripped_id = desktop_id.strip()
+        if stripped_id:
+            desktop_ids.append(stripped_id)
+    return desktop_ids
+
+
+def _desktop_file_exists(desktop_id: str, data_application_dirs: list[str], is_file: Callable[[str], bool]) -> bool:
+    """Tell whether a desktop file of that identifier is in one of the applications folders, so the application is still installed."""
+    if DESKTOP_ID_FORBIDDEN_SEPARATOR in desktop_id:
+        return False
+    for data_application_dir in data_application_dirs:
+        if is_file(os.path.join(data_application_dir, desktop_id)):
+            return True
+    return False
+
+
+def desktop_text_editor_id(environment_by_name: Mapping[str, str], home_dir: str, platform: str, read_text: Callable[[str], str | None], is_file: Callable[[str], bool], *,
+                           flatpak_dirs: tuple[str, ...] = ()) -> str:
+    """Answer the desktop file identifier of the application the desktop opens for plain text, or an empty text.
+
+    The first identifier, in the order of the files then of their line, whose desktop file is still installed decides;
+    an identifier whose application was removed is skipped for the next one, as the specification asks. Outside the
+    freedesktop systems no file is read and the text is empty. ``read_text`` answers None for a file it cannot read,
+    which is then skipped. A desktop file counts as installed in the applications folders of the data folders or in
+    the one each of ``flatpak_dirs`` exports. No program is started.
+    """
+    if editor_platform(platform) != LINUX_PLATFORM:
+        return ""
+    installed_desktop_file_dirs = desktop_file_dirs(environment_by_name, home_dir, flatpak_dirs)
+    for filename in mimeapps_filenames(environment_by_name, home_dir):
+        text = read_text(filename)
+        if text is None:
+            continue
+        for desktop_id in default_desktop_ids(text):
+            if _desktop_file_exists(desktop_id, installed_desktop_file_dirs, is_file):
+                return desktop_id
+    return ""
+
+
+def read_text_file(filename: str) -> str | None:
+    """Read a mimeapps.list file as UTF-8 text, or answer None when it is missing, unreadable or not UTF-8."""
+    try:
+        with open(filename, encoding=MIMEAPPS_ENCODING) as stream:
+            return stream.read()
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def session_desktop_text_editor_id() -> str:
+    """Answer the desktop's plain text application for this session, read from its real files.
+
+    It reads the user's folders, which may sit on a network share that stops answering: call it on a thread of its own
+    only, never on the window's thread. The session's two Flatpak installations are looked in too, for an editor
+    installed from Flatpak since the session opened.
+    """
+    environment_by_name = dict(os.environ)
+    home_dir = os.path.expanduser("~")
+    return desktop_text_editor_id(environment_by_name, home_dir, sys.platform, read_text_file, os.path.isfile, flatpak_dirs=flatpak_installation_dirs(environment_by_name, home_dir))