gitpane 1.0.0__py3-none-any.whl

gitpane/process/exact_arguments.py

@@ -0,0 +1,77 @@
+"""Hand a program its exact command line on a system whose process launcher rewrites arguments.
+
+This file is run on its own: the base interpreter runs it in isolated mode, with neither the application's packages
+nor any site directory, so only the standard library can be imported. The application imports it only to find this
+file and the name of its variable. It reads the exact command from that variable, removes the variable, and replaces
+itself with the command, keeping its process id: the command runs as the same process, with nothing between them.
+"""
+
+# Workaround: Qt for macOS converts every argument QProcess passes into its decomposed Unicode form (NFD), so an
+# accented branch name typed by the user would reach Git as other bytes. Environment values are passed unchanged, so
+# the exact command travels in one variable and this relay gives it back to the program as it was.
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+EXACT_ARGUMENTS_ENVIRONMENT_NAME = "GITPANE_EXACT_ARGUMENTS"
+# Exit code of a relay that could not start its command. A command can answer 127 too, so GitPane reads it as a
+# launch failure only when the relay's refusal line comes with it.
+EXACT_ARGUMENTS_START_FAILED_EXIT_CODE = 127
+# Start of the one line a refusing relay writes on standard error; GitPane recognises the refusal by it.
+EXACT_ARGUMENTS_START_FAILURE_PREFIX = "Cannot start the command: "
+EXACT_COMMAND_PROGRAM_POSITION = 0
+# Python ignores these signals at start and an ignored signal stays ignored across exec. The standard library gives
+# them back to the programs it starts, and so does QProcess, so the relay gives them back to its command too.
+RESTORED_SIGNAL_NAMES = ("SIGPIPE", "SIGXFSZ")
+
+
+def read_exact_command(encoded_command: str | None) -> list[str]:
+    """Decode the command the variable carries, accepting only a non-empty JSON list of texts."""
+    if encoded_command is None:
+        raise ValueError(EXACT_ARGUMENTS_ENVIRONMENT_NAME + " is not set")
+    command = json.loads(encoded_command)
+    if not isinstance(command, list):
+        raise TypeError(EXACT_ARGUMENTS_ENVIRONMENT_NAME + " is not a list")
+    if not command:
+        raise ValueError(EXACT_ARGUMENTS_ENVIRONMENT_NAME + " is an empty list")
+    for part in command:
+        if not isinstance(part, str):
+            raise TypeError(EXACT_ARGUMENTS_ENVIRONMENT_NAME + " holds an element that is not text")
+    return command
+
+
+def restore_default_signals() -> None:
+    """Give back the default action of the signals Python ignores, so the command reacts to them as if started directly."""
+    for signal_name in RESTORED_SIGNAL_NAMES:
+        signal_number = getattr(signal, signal_name, None)
+        if signal_number is not None:
+            signal.signal(signal_number, signal.SIG_DFL)
+
+
+def run_exact_command(environment: MutableMapping[str, str]) -> int:
+    """Replace this process with the command the environment carries, or answer the launch failure code.
+
+    The variable is removed first, so neither the command nor anything it starts can see it, even when the command is
+    refused. The command runs without any shell, with ``environment`` as its environment. A refusal writes one line of
+    cause on standard error.
+    """
+    encoded_command = environment.pop(EXACT_ARGUMENTS_ENVIRONMENT_NAME, None)
+    try:
+        command = read_exact_command(encoded_command)
+        restore_default_signals()
+        os.execve(command[EXACT_COMMAND_PROGRAM_POSITION], command, environment)
+    except (OSError, TypeError, ValueError) as error:
+        print(EXACT_ARGUMENTS_START_FAILURE_PREFIX + " ".join(str(error).split()), file=sys.stderr)
+        return EXACT_ARGUMENTS_START_FAILED_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(run_exact_command(os.environ))

gitpane/process/git_output_text.py

@@ -0,0 +1,20 @@
+"""Decode the error output of a Git process once, for every check that reads it.
+
+It is decoded as os.fsdecode decodes a path under Linux and macOS, so a folder Git cites gets the key a read of the
+submodules gives that folder: a byte that is not UTF-8 stays one undecoded character, never a replacement character.
+"""
+
+from __future__ import annotations
+
+# How Git's error output is decoded: as UTF-8, each byte that is not UTF-8 kept as one undecoded character.
+GIT_ERROR_DECODE_ERRORS = "surrogateescape"
+
+
+def git_error_text(stderr: bytes) -> str:
+    """Return the standard error of one Git result as text, decoded once for every refusal check that reads it.
+
+    It is decoded as os.fsdecode decodes a path under Linux and macOS, so a folder Git names in a refusal gets the key a
+    read of the submodules gives that folder. A byte that is not UTF-8 stays readable as one undecoded character and is
+    never replaced; the text shown to the user writes it as \\x and two hexadecimal digits.
+    """
+    return stderr.decode("utf-8", GIT_ERROR_DECODE_ERRORS)