gitpane 1.0.0__py3-none-any.whl

gitpane/system/startup_activation.py

@@ -0,0 +1,65 @@
+"""Describe how a program GitPane starts learns that the user asked for it.
+
+A desktop only lets a window come to the front without the user clicking it when the program that shows it proves the
+user asked for it: under X11 with a startup identifier carrying the time of the user's last action, under Wayland with
+an activation token the compositor handed out for that action. GitPane reads that value when the user clicks, and hands
+it to the program it starts through the program's environment or the file manager's D-Bus argument.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from enum import Enum
+
+
+class StartupHandoff(Enum):
+    """How a started program receives the value that lets its window come to the front.
+
+    The value of each member is the name of the environment variable the started program reads, or an empty text when
+    there is nothing to hand over.
+    """
+
+    NONE = ""
+    X11_STARTUP_ID = "DESKTOP_STARTUP_ID"
+    WAYLAND_ACTIVATION_TOKEN = "XDG_ACTIVATION_TOKEN"
+
+
+@dataclass(frozen=True)
+class StartupActivation:
+    """The startup value read when the user clicked, with the way it reaches the started program."""
+
+    handoff: StartupHandoff
+    value: str = ""
+
+    def environment(self, base_by_name: Mapping[str, str]) -> dict[str, str]:
+        """Copy an environment without any inherited startup value, then add this one when there is one.
+
+        Every startup variable is removed first: one inherited from GitPane's own start was already used by GitPane's
+        first window, and an identifier of another launch would name the wrong action. Qt removes its own token from
+        the C environment only, never from ``os.environ``, so a copy of ``os.environ`` still holds it. The table
+        received is left as it is.
+        """
+        inherited_name_set: set[str] = set()
+        for handoff in StartupHandoff:
+            if handoff.value:
+                inherited_name_set.add(handoff.value)
+        environment_by_name: dict[str, str] = {}
+        for name, value in base_by_name.items():
+            if name in inherited_name_set:
+                continue
+            environment_by_name[name] = value
+        if self.value and self.handoff.value:
+            environment_by_name[self.handoff.value] = self.value
+        return environment_by_name
+
+
+NO_STARTUP_ACTIVATION = StartupActivation(StartupHandoff.NONE)
+
+
+def no_startup_activation() -> StartupActivation:
+    """Answer that there is no startup value, so the desktop alone decides whether an opened window comes to the front.
+
+    The source of a service built without a desktop, as in the tests: it never touches a window.
+    """
+    return NO_STARTUP_ACTIVATION

gitpane/system/terminal_detach.py

@@ -0,0 +1,384 @@
+"""Detach GitPane from the terminal it was typed in, so closing that terminal leaves GitPane running.
+
+The gitpane command typed in a terminal starts GitPane again as a new process in a session of its own, then waits for
+that process to say it showed its first window. Until then, GitPane's output comes back to the terminal: an error at
+start is shown there with GitPane's exit code. Once GitPane is ready, the command gives the terminal back, and a hangup
+of that terminal no longer reaches GitPane. A new process is started rather than the running one forked: the command
+has already loaded Qt, and on macOS a fork without exec after Apple's frameworks are loaded is not safe.
+
+The channel GitPane uses to say it is ready is a pair of connected local sockets: the started GitPane receives one end,
+whose descriptor number travels in an environment variable, takes it out of its environment and keeps it from the
+programs it starts. GitPane writes on its end to say it is ready. The end the command keeps is never written on, and
+it closes when the command ends, which GitPane sees at its own end, then readable: that is how GitPane knows the
+command is gone even before it is ready.
+"""
+
+from __future__ import annotations
+
+import os
+import selectors
+import signal
+import socket
+import stat
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, BinaryIO, TextIO
+
+from gitpane.config import DETACHED_READY_TIMEOUT_MS, DETACHED_STOP_GRACE_MS, ISOLATED_MODE_OPTION, LINUX_PLATFORM, MACOS_PLATFORM, MILLISECONDS_PER_SECOND, MODULE_OPTION, SAFE_PATH_OPTION, SIGNAL_EXIT_CODE_BASE, WINDOWS_PLATFORM
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, MutableMapping, Sequence
+
+READY_CHANNEL_ENVIRONMENT_NAME = "GITPANE_READY_CHANNEL"
+READY_MARKER = b"R"
+STANDARD_INPUT_DESCRIPTOR = 0
+STANDARD_OUTPUT_DESCRIPTOR = 1
+STANDARD_ERROR_DESCRIPTOR = 2
+STANDARD_DESCRIPTORS = (STANDARD_INPUT_DESCRIPTOR, STANDARD_OUTPUT_DESCRIPTOR, STANDARD_ERROR_DESCRIPTOR)
+# Only the end of GitPane's output before it is ready is shown when it stops before its first window: a long run of
+# warnings before an error would otherwise grow without bound in the waiting command.
+KEPT_OUTPUT_BYTE_LIMIT = 65_536
+# Largest ready message read: the marker and the path of the diagnostic log. A longer path is not sent.
+READY_MESSAGE_BYTE_LIMIT = 4_096
+OUTPUT_READ_BYTE_COUNT = 65_536
+LOG_FILENAME_ENCODING = "utf-8"
+# Whether the gitpane command leaves the terminal it was typed in. On Windows the installed command has no console, so
+# there is nothing to leave; an unknown system stays attached.
+DETACH_BY_PLATFORM = {LINUX_PLATFORM: True, MACOS_PLATFORM: True, WINDOWS_PLATFORM: False}
+
+
+class TerminalDetachText(Enum):
+    """Texts the gitpane command writes to the terminal while it waits for GitPane to be ready."""
+
+    STILL_STARTING = "GitPane is still starting; it goes on without this terminal, and its output is no longer shown here."
+    """Written when the wait ends before GitPane said it is ready."""
+    LOG_FILE = "Diagnostic log: {filename}"
+    """Written once GitPane is ready, when it writes a diagnostic log."""
+    STOPPED_BEFORE_READY = "GitPane stopped before opening its first window (exit status {status})."
+    """Written after GitPane's own output when it ends before it is ready."""
+    INTERRUPTED = "GitPane goes on starting without this terminal; close its window to stop it."
+    """Written when Ctrl+C ends the wait before GitPane said it is ready."""
+
+
+@dataclass(frozen=True)
+class DetachOutcome:
+    """What the waiting command ends with: its exit code, and the process ID of the GitPane it started."""
+
+    exit_code: int
+    child_process_id: int
+
+
+def detaches_from_terminal(platform: str, stream_is_terminal: Callable[[int], bool], attach: bool, environment_by_name: Mapping[str, str]) -> bool:
+    """Tell whether the gitpane command should start GitPane again in a session of its own.
+
+    Only on Linux and macOS, only when both its standard output and its standard error are a terminal, never with
+    ``--attach``, and never in a GitPane that was itself started detached. A desktop shortcut or a menu never detaches,
+    and an output or errors redirected to a file or a program keep GitPane attached, so that file or program receives
+    them. The standard input is not looked at: the detached GitPane gets the null device as its input anyway.
+    ``stream_is_terminal`` receives a descriptor number (``os.isatty`` in the command); it is not called on a system that
+    never detaches.
+    """
+    if not DETACH_BY_PLATFORM.get(platform, False):
+        return False
+    if attach:
+        return False
+    if READY_CHANNEL_ENVIRONMENT_NAME in environment_by_name:
+        return False
+    return stream_is_terminal(STANDARD_OUTPUT_DESCRIPTOR) and stream_is_terminal(STANDARD_ERROR_DESCRIPTOR)
+
+
+def interrupt_stops_gitpane(platform: str, attach: bool) -> bool:
+    """Tell whether Ctrl+C in the terminal must stop GitPane at once, which only an attached GitPane asks for.
+
+    With ``--attach`` on a system where the command would otherwise detach, the terminal is a diagnostic one and Ctrl+C
+    is expected to end GitPane right away, as for any program typed there. Elsewhere the interrupt keeps Python's
+    default handling.
+    """
+    return attach and DETACH_BY_PLATFORM.get(platform, False)
+
+
+def running_interpreter_options() -> list[str]:
+    """Return the options of the running Python (``-X dev``, ``-W …``, ``-E``, ``-s``, ``-O``, ``-I``…) as command-line arguments."""
+    # Workaround: Python has no public way to rebuild the options of the running interpreter from sys.flags,
+    # sys.warnoptions and sys._xoptions; this private function of the standard library does it, and multiprocessing
+    # relies on it to start its processes with the options of their parent.
+    return subprocess._args_from_interpreter_flags()
+
+
+def detached_child_command(argv: Sequence[str], python_filename: str, module_name: str, interpreter_options: Sequence[str]) -> list[str]:
+    """Build the command that starts GitPane again with the same arguments, on its module, without the current folder in its path.
+
+    ``interpreter_options`` are the options of the command's own Python, passed on first so the started GitPane runs
+    under the same ones. The safe path option is added only when they hold neither it nor isolated mode, which already
+    implies it.
+    """
+    command = [python_filename, *interpreter_options]
+    if SAFE_PATH_OPTION not in interpreter_options and ISOLATED_MODE_OPTION not in interpreter_options:
+        command.append(SAFE_PATH_OPTION)
+    return [*command, MODULE_OPTION, module_name, *argv]
+
+
+def exit_status(return_code: int) -> int:
+    """Turn a child's return code into a shell's exit status: its own code, or the base plus n for signal n."""
+    if return_code >= 0:
+        return return_code
+    return SIGNAL_EXIT_CODE_BASE - return_code
+
+
+def relaunch_detached(
+    command: Sequence[str],
+    environment_by_name: Mapping[str, str],
+    *,
+    timeout_ms: int = DETACHED_READY_TIMEOUT_MS,
+    popen: Callable[..., subprocess.Popen[bytes]] = subprocess.Popen,
+    output_stream: BinaryIO | None = None,
+    message_stream: TextIO | None = None,
+) -> DetachOutcome:
+    """Start ``command`` in a session of its own, then wait for its ready signal, its end or the timeout.
+
+    Returns 0 when it is ready, and writes the diagnostic log path it sent, if any. When it closes its channel without
+    the ready signal, its output is still read, then its end waited for, during ``DETACHED_STOP_GRACE_MS`` counted from
+    that close, whatever is left of the timeout: its last output is written to ``output_stream`` (the binary error
+    stream by default), then a line that says it stopped, and its exit status is returned. When the timeout comes first,
+    or the child is still alive past that delay, a line says GitPane goes on without the terminal, and 0 is returned.
+    The child's output is read during the whole wait, so a child that writes a lot before it is ready never blocks.
+    """
+    if output_stream is None:
+        output_stream = sys.stderr.buffer
+    if message_stream is None:
+        message_stream = sys.stderr
+    deadline = time.monotonic() + timeout_ms / MILLISECONDS_PER_SECOND
+    command_socket, gitpane_socket = socket.socketpair()
+    command_end_descriptor = command_socket.detach()
+    gitpane_end_descriptor = gitpane_socket.detach()
+    try:
+        child_environment = dict(environment_by_name)
+        child_environment[READY_CHANNEL_ENVIRONMENT_NAME] = str(gitpane_end_descriptor)
+        try:
+            child = popen(
+                list(command),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                start_new_session=True,
+                pass_fds=(gitpane_end_descriptor,),
+                env=child_environment,
+            )
+        finally:
+            os.close(gitpane_end_descriptor)
+        try:
+            return _wait_for_ready(child, command_end_descriptor, deadline, output_stream, message_stream)
+        finally:
+            if child.stdout is not None:
+                child.stdout.close()
+    finally:
+        os.close(command_end_descriptor)
+
+
+class _ChildWait:
+    """Hold what the waiting command has read so far: the end of the child's output and the ready message."""
+
+    def __init__(self) -> None:
+        """Start with nothing read."""
+        self.kept_output = bytearray()
+        self.ready_message = bytearray()
+        self.output_open = True
+        self.ready_open = True
+
+    def keep_output(self, chunk: bytes) -> None:
+        """Add ``chunk`` to the kept output, dropping its oldest bytes past the limit."""
+        self.kept_output += chunk
+        excess = len(self.kept_output) - KEPT_OUTPUT_BYTE_LIMIT
+        if excess > 0:
+            del self.kept_output[:excess]
+
+    def keep_ready_message(self, chunk: bytes) -> None:
+        """Add ``chunk`` to the ready message, up to its limit."""
+        room = READY_MESSAGE_BYTE_LIMIT - len(self.ready_message)
+        if room > 0:
+            self.ready_message += chunk[:room]
+
+
+def _remaining_seconds(deadline: float) -> float:
+    """Return the seconds left until ``deadline``, never below zero."""
+    return max(0.0, deadline - time.monotonic())
+
+
+def _wait_for_ready(child: subprocess.Popen[bytes], read_descriptor: int, deadline: float, output_stream: BinaryIO, message_stream: TextIO) -> DetachOutcome:
+    """Read the child's output and its ready channel until the channel ends or the deadline passes, then decide the outcome."""
+    wait = _ChildWait()
+    output_descriptor = child.stdout.fileno() if child.stdout is not None else None
+    selector = selectors.DefaultSelector()
+    try:
+        selector.register(read_descriptor, selectors.EVENT_READ)
+        if output_descriptor is not None:
+            selector.register(output_descriptor, selectors.EVENT_READ)
+        else:
+            wait.output_open = False
+        try:
+            _read_until(selector, wait, read_descriptor, deadline, lambda: wait.ready_open)
+            if wait.ready_open:
+                return _still_starting(child, message_stream)
+            if wait.ready_message.startswith(READY_MARKER):
+                return _ready(child, wait, message_stream)
+            # From the close of the channel on, the wait has its own short delay: a program GitPane started may keep
+            # the output open, and the end of a process comes a little after the close of its channel, maybe past the
+            # deadline of the ready signal.
+            stop_deadline = time.monotonic() + DETACHED_STOP_GRACE_MS / MILLISECONDS_PER_SECOND
+            _read_until(selector, wait, read_descriptor, stop_deadline, lambda: wait.output_open)
+            return _stopped_before_ready(child, wait, stop_deadline, output_stream, message_stream)
+        except KeyboardInterrupt:
+            # GitPane already runs in a session of its own, so Ctrl+C reaches only this waiting command: it says that
+            # GitPane goes on, then ends the way a shell reports an interrupted program, without a traceback.
+            return _interrupted(child, message_stream)
+    finally:
+        selector.close()
+
+
+def _read_until(selector: selectors.BaseSelector, wait: _ChildWait, read_descriptor: int, deadline: float, still_open: Callable[[], bool]) -> None:
+    """Read whatever the child writes on either pipe while ``still_open`` holds and the deadline has not passed."""
+    while still_open():
+        remaining = _remaining_seconds(deadline)
+        if remaining <= 0:
+            return
+        for key, _event in selector.select(remaining):
+            chunk = os.read(key.fd, OUTPUT_READ_BYTE_COUNT)
+            if key.fd == read_descriptor:
+                if chunk:
+                    wait.keep_ready_message(chunk)
+                    continue
+                wait.ready_open = False
+            else:
+                if chunk:
+                    wait.keep_output(chunk)
+                    continue
+                wait.output_open = False
+            selector.unregister(key.fd)
+
+
+def _write_message(message_stream: TextIO, text: str) -> None:
+    """Write one line to the terminal at once, so it is not mixed with output written around it."""
+    message_stream.write(text + "\n")
+    message_stream.flush()
+
+
+def _ready(child: subprocess.Popen[bytes], wait: _ChildWait, message_stream: TextIO) -> DetachOutcome:
+    """End the wait for a ready GitPane, naming its diagnostic log when it sent one."""
+    log_filename = bytes(wait.ready_message[len(READY_MARKER) :]).decode(LOG_FILENAME_ENCODING, errors="replace")
+    if log_filename:
+        _write_message(message_stream, TerminalDetachText.LOG_FILE.value.format(filename=log_filename))
+    return DetachOutcome(0, child.pid)
+
+
+def _still_starting(child: subprocess.Popen[bytes], message_stream: TextIO) -> DetachOutcome:
+    """End the wait at the deadline: GitPane goes on alone, and the terminal is given back."""
+    _write_message(message_stream, TerminalDetachText.STILL_STARTING.value)
+    return DetachOutcome(0, child.pid)
+
+
+def _interrupted(child: subprocess.Popen[bytes], message_stream: TextIO) -> DetachOutcome:
+    """End the wait at Ctrl+C: say that GitPane goes on without the terminal, and return the shell's interrupt status."""
+    _write_message(message_stream, TerminalDetachText.INTERRUPTED.value)
+    return DetachOutcome(SIGNAL_EXIT_CODE_BASE + signal.SIGINT, child.pid)
+
+
+def _stopped_before_ready(child: subprocess.Popen[bytes], wait: _ChildWait, stop_deadline: float, output_stream: BinaryIO, message_stream: TextIO) -> DetachOutcome:
+    """End the wait for a GitPane that closed its channel without the ready signal: show its output and return its status.
+
+    Its end is waited for until ``stop_deadline``, the delay granted from the close of its channel; a GitPane still
+    alive then goes on without the terminal.
+    """
+    try:
+        return_code = child.wait(timeout=_remaining_seconds(stop_deadline))
+    except subprocess.TimeoutExpired:
+        return _still_starting(child, message_stream)
+    status = exit_status(return_code)
+    message_stream.flush()
+    output_stream.write(bytes(wait.kept_output))
+    output_stream.flush()
+    _write_message(message_stream, TerminalDetachText.STOPPED_BEFORE_READY.value.format(status=status))
+    return DetachOutcome(status, child.pid)
+
+
+def take_ready_channel(environment_by_name: MutableMapping[str, str]) -> int | None:
+    """Take the ready channel out of the environment, and return its descriptor when it really is an open socket.
+
+    The variable is always removed, so no program GitPane starts sees it. Any parent can set it: a value that is not a
+    number, a standard stream, a closed descriptor or anything but a socket (a pipe, an ordinary file) is ignored. The
+    descriptor returned is no longer inherited by the programs GitPane starts, so none of them keeps the channel open
+    after GitPane ends.
+    """
+    value = environment_by_name.pop(READY_CHANNEL_ENVIRONMENT_NAME, None)
+    if value is None:
+        return None
+    try:
+        channel = int(value)
+    except ValueError:
+        return None
+    if channel in STANDARD_DESCRIPTORS:
+        return None
+    try:
+        mode = os.fstat(channel).st_mode
+    except OSError:
+        return None
+    if not stat.S_ISSOCK(mode):
+        return None
+    os.set_inheritable(channel, False)
+    return channel
+
+
+def redirect_standard_streams_to_null() -> None:
+    """Point the three standard streams to the null device, once the gitpane command that read them gave them up.
+
+    Nothing reads the command's pipes any more after it gave the terminal back or ended: a program GitPane starts later
+    inherits the standard streams, and writing to a pipe nobody reads could stop it. Python's buffers are emptied first,
+    but a failure to empty them never keeps the streams on those pipes.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if stream is None:
+            continue
+        try:
+            stream.flush()
+        except OSError:
+            # The command that read this stream is gone: the text left in the buffer has no reader any more.
+            pass
+    null_descriptor = os.open(os.devnull, os.O_RDWR)
+    try:
+        for descriptor in STANDARD_DESCRIPTORS:
+            os.dup2(null_descriptor, descriptor)
+    finally:
+        if null_descriptor not in STANDARD_DESCRIPTORS:
+            os.close(null_descriptor)
+
+
+def notify_ready(channel: int, log_filename: str) -> None:
+    """Tell the waiting command that GitPane is ready, after moving the standard streams off the pipes it reads.
+
+    The streams point to the null device before the signal is sent, so the command never gives the terminal back while
+    GitPane still writes to it. A waiting command already gone is not an error: the streams are moved all the same, the
+    signal is dropped and the channel is closed, and nothing is raised.
+    """
+    redirect_standard_streams_to_null()
+    message = READY_MARKER + log_filename.encode(LOG_FILENAME_ENCODING)
+    if len(message) > READY_MESSAGE_BYTE_LIMIT:
+        message = READY_MARKER
+    try:
+        _write_all(channel, message)
+    except OSError:
+        pass
+    finally:
+        try:
+            os.close(channel)
+        except OSError:
+            pass
+
+
+def _write_all(descriptor: int, data: bytes) -> None:
+    """Write every byte of ``data``: a socket may take a long message in several writes."""
+    view = memoryview(data)
+    while view:
+        written = os.write(descriptor, view)
+        view = view[written:]

gitpane/system/xdg_session.py

@@ -0,0 +1,85 @@
+"""Read the session values a freedesktop desktop declares in its environment, falling back on the specification's defaults.
+
+Every function receives the environment, and the home folder when it needs one, instead of reading the process's own, so
+each rule can be checked from any system.
+"""
+
+from __future__ import annotations
+
+import os
+import posixpath
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+# The same value is written in tests/qt_platform.py, which imports nothing from GitPane; a test keeps the two identical.
+DESKTOP_SEPARATOR = ":"
+XDG_PATH_SEPARATOR = ":"
+XDG_CURRENT_DESKTOP_ENVIRONMENT_NAME = "XDG_CURRENT_DESKTOP"
+XDG_CONFIG_HOME_ENVIRONMENT_NAME = "XDG_CONFIG_HOME"
+XDG_CONFIG_DIRS_ENVIRONMENT_NAME = "XDG_CONFIG_DIRS"
+XDG_DATA_HOME_ENVIRONMENT_NAME = "XDG_DATA_HOME"
+XDG_DATA_DIRS_ENVIRONMENT_NAME = "XDG_DATA_DIRS"
+USER_CONFIG_DIR_BASENAME = ".config"
+USER_DATA_DIR_PARTS = (".local", "share")
+DEFAULT_XDG_CONFIG_DIRS = ("/etc/xdg",)
+DEFAULT_XDG_DATA_DIRS = ("/usr/local/share", "/usr/share")
+
+
+def desktop_names(environment_by_name: Mapping[str, str]) -> list[str]:
+    """List the desktop names XDG_CURRENT_DESKTOP declares, lowercased, most specific first, without empty names.
+
+    Desktop-specific files, such as ``gnome-mimeapps.list``, are named after these lowercased names.
+    """
+    names = []
+    for name in environment_by_name.get(XDG_CURRENT_DESKTOP_ENVIRONMENT_NAME, "").split(DESKTOP_SEPARATOR):
+        if name:
+            names.append(name.lower())
+    return names
+
+
+def _xdg_home(environment_by_name: Mapping[str, str], environment_name: str, home_dir: str, default_parts: tuple[str, ...]) -> str:
+    """Answer the absolute folder an XDG home variable names, or its default under ``home_dir`` when it is missing, empty or relative.
+
+    The specification asks to ignore a relative value, so nothing ever lands in the current folder.
+    """
+    xdg_dir = environment_by_name.get(environment_name, "")
+    if xdg_dir and os.path.isabs(xdg_dir):
+        return xdg_dir
+    return os.path.join(home_dir, *default_parts)
+
+
+def xdg_config_home(environment_by_name: Mapping[str, str], home_dir: str) -> str:
+    """Answer the user's configuration folder: XDG_CONFIG_HOME when absolute, otherwise ``~/.config``."""
+    return _xdg_home(environment_by_name, XDG_CONFIG_HOME_ENVIRONMENT_NAME, home_dir, (USER_CONFIG_DIR_BASENAME,))
+
+
+def xdg_data_home(environment_by_name: Mapping[str, str], home_dir: str) -> str:
+    """Answer the user's data folder: XDG_DATA_HOME when absolute, otherwise ``~/.local/share``."""
+    return _xdg_home(environment_by_name, XDG_DATA_HOME_ENVIRONMENT_NAME, home_dir, USER_DATA_DIR_PARTS)
+
+
+def _xdg_dirs(environment_by_name: Mapping[str, str], environment_name: str, default_dirs: tuple[str, ...]) -> list[str]:
+    """List the absolute folders of an XDG folder list in order, or its defaults when no absolute folder is left.
+
+    The list is separated by ':', which is only a separator on freedesktop systems, so its entries are judged as POSIX
+    paths: a Windows path, which carries a ':' after its drive, cannot be one of them.
+    """
+    xdg_dirs = []
+    for xdg_dir in environment_by_name.get(environment_name, "").split(XDG_PATH_SEPARATOR):
+        if xdg_dir and posixpath.isabs(xdg_dir):
+            xdg_dirs.append(xdg_dir)
+    if not xdg_dirs:
+        return list(default_dirs)
+    return xdg_dirs
+
+
+def xdg_config_dirs(environment_by_name: Mapping[str, str]) -> list[str]:
+    """List the system configuration folders, most important first: XDG_CONFIG_DIRS, otherwise ``/etc/xdg``."""
+    return _xdg_dirs(environment_by_name, XDG_CONFIG_DIRS_ENVIRONMENT_NAME, DEFAULT_XDG_CONFIG_DIRS)
+
+
+def xdg_data_dirs(environment_by_name: Mapping[str, str]) -> list[str]:
+    """List the system data folders, most important first: XDG_DATA_DIRS, otherwise ``/usr/local/share`` then ``/usr/share``."""
+    return _xdg_dirs(environment_by_name, XDG_DATA_DIRS_ENVIRONMENT_NAME, DEFAULT_XDG_DATA_DIRS)

gitpane/text/text_query.py

@@ -0,0 +1,97 @@
+"""Match case-insensitive text with an optional asterisk wildcard."""
+
+from __future__ import annotations
+
+from bisect import bisect_left
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+class TextQuery:
+    """Search ordered literal fragments without regex interpretation or backtracking."""
+
+    def __init__(self, query: str, *, wildcard: bool = True) -> None:
+        """Treat asterisks as gaps and preserve all other characters, including spaces."""
+        self.parts: list[str] = []
+        for part in query.split("*") if wildcard else (query,):
+            if part:
+                self.parts.append(part.casefold())
+
+    def matches(self, text: str) -> bool:
+        """Check complete messages with Unicode case folding and no offset conversion."""
+        return self._find_span(text.casefold(), 0) is not None
+
+    def find_match(self, text: str, *, overlap: bool = False, wildcard_whitespace: bool = True) -> Iterator[tuple[int, int]]:
+        """Yield source spans, optionally keeping wildcard gaps inside words for local highlighting."""
+        if not text:
+            return
+        folded_text = text.casefold()
+        whitespace_positions = None
+        if not wildcard_whitespace:
+            whitespace_positions = []
+            if len(self.parts) > 1:
+                for position, character in enumerate(folded_text):
+                    if character.isspace():
+                        whitespace_positions.append(position)
+        source_positions = []
+        if len(folded_text) != len(text):
+            for position, character in enumerate(text):
+                for _folded_character in character.casefold():
+                    source_positions.append(position)
+        start = 0
+        previous_span = None
+        while start < len(folded_text):
+            span = self._find_span(folded_text, start, whitespace_positions)
+            if span is None:
+                return
+            begin, end = span
+            if source_positions:
+                last_character_index = end - 1
+                span = (source_positions[begin], source_positions[last_character_index] + 1)
+            if span != previous_span:
+                yield span
+                previous_span = span
+            if not self.parts and wildcard_whitespace:
+                return
+            start = begin + 1 if overlap else end
+            if source_positions and not overlap:
+                # Case folding can expand one source character; do not reuse half of it in the next match.
+                _source_begin, source_end = span
+                while start < len(source_positions) and source_positions[start] < source_end:
+                    start += 1
+
+    def _find_span(self, folded_text: str, start: int, whitespace_positions: list[int] | None = None) -> tuple[int, int] | None:
+        """Retry invalid word gaps using cached fragment positions instead of rescanning the same suffix."""
+        if not self.parts:
+            if whitespace_positions is None:
+                return start, len(folded_text)
+            while start < len(folded_text) and folded_text[start].isspace():
+                start += 1
+            end = start
+            while end < len(folded_text) and not folded_text[end].isspace():
+                end += 1
+            return (start, end) if end > start else None
+        position_by_part_index: dict[int, int] = {}
+        while start < len(folded_text):
+            begin = None
+            end = start
+            for part_index, part in enumerate(self.parts):
+                position = position_by_part_index.get(part_index, -1)
+                if position < end:
+                    position = folded_text.find(part, end)
+                    if position < 0:
+                        return None
+                    position_by_part_index[part_index] = position
+                if begin is not None and whitespace_positions is not None:
+                    boundary_index = bisect_left(whitespace_positions, end)
+                    if boundary_index < len(whitespace_positions) and whitespace_positions[boundary_index] < position:
+                        start = begin + 1
+                        break
+                if begin is None:
+                    begin = position
+                end = position + len(part)
+            else:
+                return begin, end
+        return None