gitpane 1.0.0__py3-none-any.whl

gitpane/sequencer/rebase_edit_file.py

@@ -0,0 +1,224 @@
+"""Keep the file Git handed to the rebase editor byte-exact from its read to the write of the user's text."""
+
+from __future__ import annotations
+
+import codecs
+import os
+import stat
+import tempfile
+from dataclasses import dataclass
+from enum import Enum
+
+from gitpane.config import QT_PARAGRAPH_SEPARATOR
+from gitpane.system.path_identity import link_resolved_path
+from gitpane.worktree.worktree_file import SINGLE_LINK_COUNT
+
+# Git writes its instruction list and its messages in UTF-8 unless the repository asks for another commit encoding.
+EDIT_FILE_CODEC = "utf-8"
+EDIT_FILE_TEMPORARY_PREFIX = "gitpane-rebase-edit-"
+# The editor widget turns a carriage return and a paragraph separator into a plain line break, and drops a byte order
+# mark at the start of the document: text holding one of them would come back with bytes the user never changed.
+CARRIAGE_RETURN_CHARACTER = "\r"
+BYTE_ORDER_MARK_CHARACTER = "\ufeff"
+
+
+class ReadOnlyCause(Enum):
+    """Why a file Git waits for can be shown but not written back; each value is the line the editor window shows above it."""
+
+    UNDECODABLE = "Read-only: the file is in an encoding GitPane cannot read back exactly."
+    CARRIAGE_RETURN = "Read-only: the file has carriage returns GitPane cannot keep."
+    BYTE_ORDER_MARK = "Read-only: the file starts with a byte order mark GitPane cannot keep."
+    PARAGRAPH_SEPARATOR = "Read-only: the file holds a paragraph separator GitPane cannot keep."
+
+    @property
+    def label(self) -> str:
+        """Answer the line the editor window shows above a file it keeps read-only."""
+        return self.value
+
+
+class EditFileFailure(Enum):
+    """Why the file Git waits for could not be read or written; each value is the fixed start of the cause shown to the user."""
+
+    CHANGED = "The file Git is waiting for changed."
+    # The codec is named, never the character it cannot hold.
+    UNENCODABLE = "The text cannot be written in {codec}."
+    CREATE = "Cannot create the new file next to the file Git is waiting for:"
+    WRITE = "Cannot write the new file:"
+    REPLACE = "Cannot replace the file Git is waiting for:"
+    # Out of reach in practice, os.name being posix or nt, both in the table of open flags.
+    UNKNOWN_SYSTEM = "GitPane does not know how to open the file Git is waiting for on this system."
+
+
+class EditFileWriteError(OSError):
+    """A write of the file Git waits for that did not happen; the file is left as it was.
+
+    Its cause is a readable sentence, never the content of the file, and is also the error's strerror so that code
+    reading system errors shows it as is.
+    """
+
+    def __init__(self, cause: str, error_number: int | None = None) -> None:
+        super().__init__(error_number, cause)
+        self.cause = cause
+
+    def __str__(self) -> str:
+        return self.cause
+
+
+def _system_failure(failure: EditFileFailure, error: OSError) -> EditFileWriteError:
+    """Turn the system error of one write step into a write error naming the step, then the system's reason."""
+    return EditFileWriteError(failure.value + " " + (error.strerror or str(error)), error.errno)
+
+
+def read_only_cause(text: str) -> ReadOnlyCause | None:
+    """Answer why the editor could not give this text back unchanged, or None when it can.
+
+    The editor widget changes a carriage return into a line break, cannot tell a paragraph separator from a line break
+    once it holds the text, and drops a byte order mark at the start of the document; any of them would rewrite bytes
+    the user never touched.
+    """
+    if text.startswith(BYTE_ORDER_MARK_CHARACTER):
+        return ReadOnlyCause.BYTE_ORDER_MARK
+    if CARRIAGE_RETURN_CHARACTER in text:
+        return ReadOnlyCause.CARRIAGE_RETURN
+    if QT_PARAGRAPH_SEPARATOR in text:
+        return ReadOnlyCause.PARAGRAPH_SEPARATOR
+    return None
+
+
+@dataclass(frozen=True)
+class EditFileContent:
+    """The text of one file Git waits for, with what writing it back needs: its codec, the identity it was read from and its permission bits."""
+
+    filename: str
+    text: str
+    codec: str
+    identity: tuple[int, int]
+    mode: int
+    read_only_cause: ReadOnlyCause | None = None
+
+
+EDIT_FILE_OPEN_FLAG_NAMES_BY_OS_NAME: dict[str, tuple[str, ...]] = {
+    # Binary mode, so the C library of Windows neither turns CR LF into LF nor stops reading at the first Ctrl+Z byte.
+    "nt": ("O_RDONLY", "O_BINARY"),
+    # The path can become a FIFO after Git wrote it: reading must never wait for a writer, nor follow a link put in place of the file.
+    "posix": ("O_RDONLY", "O_NONBLOCK", "O_NOFOLLOW"),
+}
+
+
+def edit_file_open_flags(os_name: str) -> int:
+    """Answer the flags, for the system named like os.name, that open the file Git waits for byte for byte and without any wait.
+
+    The file is read in binary mode on Windows, and without waiting on a FIFO or following a replacement link on a
+    POSIX system. The flag names come from the table by system and are resolved on the os module of the running Python,
+    at the call: the function is meant to be called with os.name, and the name of another system can miss one of its
+    flags there (AttributeError), which is why the tests put the Windows flag in place. A system the table does not
+    know raises OSError.
+    """
+    flag_names = EDIT_FILE_OPEN_FLAG_NAMES_BY_OS_NAME.get(os_name)
+    if flag_names is None:
+        raise OSError(EditFileFailure.UNKNOWN_SYSTEM.value)
+    # Each flag only exists in the os module of its own system, and the function is called with os.name; reading them
+    # at the call, rather than at import, also lets a test put the Windows flag in place.
+    flags = 0
+    for flag_name in flag_names:
+        flags |= getattr(os, flag_name)
+    return flags
+
+
+def _same_single_file(status: os.stat_result, identity: tuple[int, int] | None) -> bool:
+    """Tell whether a status is the regular file with one link that the bridge validated."""
+    return stat.S_ISREG(status.st_mode) and status.st_nlink == SINGLE_LINK_COUNT and identity == (status.st_dev, status.st_ino)
+
+
+def _decoded(data: bytes, fallback_codec: str) -> tuple[str, str] | None:
+    """Decode the bytes in strict UTF-8, else in the fallback text codec, answering the text and the codec's normalized name.
+
+    None means neither decodes: no known text codec is given, or the bytes are not valid in it.
+    """
+    try:
+        return data.decode(EDIT_FILE_CODEC), codecs.lookup(EDIT_FILE_CODEC).name
+    except UnicodeDecodeError:
+        pass
+    if not fallback_codec:
+        return None
+    try:
+        codec = codecs.lookup(fallback_codec).name
+        # bytes.decode refuses a codec that is not a text encoding (rot13, base64) with LookupError.
+        return data.decode(codec), codec
+    except (LookupError, UnicodeDecodeError):
+        return None
+
+
+def read_edit_file(filename: str, identity: tuple[int, int] | None, fallback_codec: str = "") -> EditFileContent:
+    """Read the file Git waits for, refusing any other file than the one the bridge validated.
+
+    The bytes are decoded in strict UTF-8, else with the fallback codec (the repository's commit encoding, in which Git
+    writes a commit message). A file neither decodes is still shown, decoded with replacement characters, and a text the
+    editor could not give back unchanged is shown too, but both are marked read-only: writing them back would change
+    bytes the user never touched.
+    """
+    descriptor = os.open(filename, edit_file_open_flags(os.name))
+    with os.fdopen(descriptor, "rb") as stream:
+        opened = os.fstat(stream.fileno())
+        if not _same_single_file(opened, identity):
+            raise OSError(EditFileFailure.CHANGED.value)
+        data = stream.read()
+    mode = stat.S_IMODE(opened.st_mode)
+    file_identity = (opened.st_dev, opened.st_ino)
+    decoded = _decoded(data, fallback_codec)
+    if decoded is None:
+        return EditFileContent(filename, data.decode(EDIT_FILE_CODEC, errors="replace"), EDIT_FILE_CODEC, file_identity, mode, ReadOnlyCause.UNDECODABLE)
+    text, codec = decoded
+    return EditFileContent(filename, text, codec, file_identity, mode, read_only_cause(text))
+
+
+def _verify_unchanged(content: EditFileContent) -> None:
+    """Refuse to replace the file when its path no longer names the single regular file that was read: a link, another file, a second link or no file at all."""
+    try:
+        current = os.lstat(content.filename)
+    except OSError:
+        raise EditFileWriteError(EditFileFailure.CHANGED.value) from None
+    if not _same_single_file(current, content.identity) or link_resolved_path(content.filename) != os.path.normcase(content.filename):
+        raise EditFileWriteError(EditFileFailure.CHANGED.value)
+
+
+def write_edit_file(content: EditFileContent, text: str) -> EditFileContent:
+    """Replace the file Git waits for with the user's text in one step, or leave it untouched when the text did not change.
+
+    An unchanged text writes nothing, so Git reads back exactly the bytes it wrote. A changed text goes to a private
+    file of the same folder, which takes the permission bits of the original and replaces it only once it is complete
+    on disk and the original is proven to be the file that was read. Any failure raises EditFileWriteError with a
+    readable cause, leaves the original as it was and removes the private file. A read-only content raises ValueError.
+    """
+    if text == content.text:
+        return content
+    if content.read_only_cause is not None:
+        raise ValueError(content.read_only_cause.label)
+    try:
+        data = text.encode(content.codec)
+    except UnicodeEncodeError:
+        # The encoding error holds the whole text; dropping it keeps the user's text out of any diagnostic.
+        raise EditFileWriteError(EditFileFailure.UNENCODABLE.value.format(codec=content.codec)) from None
+    try:
+        descriptor, candidate_filename = tempfile.mkstemp(prefix=EDIT_FILE_TEMPORARY_PREFIX, dir=os.path.dirname(content.filename))
+    except OSError as error:
+        raise _system_failure(EditFileFailure.CREATE, error) from error
+    try:
+        try:
+            with os.fdopen(descriptor, "wb") as stream:
+                os.fchmod(stream.fileno(), content.mode)
+                stream.write(data)
+                stream.flush()
+                os.fsync(stream.fileno())
+                written = os.fstat(stream.fileno())
+        except OSError as error:
+            raise _system_failure(EditFileFailure.WRITE, error) from error
+        _verify_unchanged(content)
+        try:
+            os.replace(candidate_filename, content.filename)
+        except OSError as error:
+            raise _system_failure(EditFileFailure.REPLACE, error) from error
+    finally:
+        if os.path.lexists(candidate_filename):
+            os.unlink(candidate_filename)
+    return EditFileContent(content.filename, text, content.codec, (written.st_dev, written.st_ino), content.mode)