sequential-hooks 0.1.0__py3-none-any.whl

sequential_hooks/_downstream.py

@@ -0,0 +1,181 @@
+"""Absorb closure of a downstream reader of standard output."""
+
+import contextlib
+import errno
+import os
+import sys
+from collections.abc import Generator, Iterable
+from typing import TextIO, cast
+
+_WINDOWS = sys.platform == 'win32'
+
+
+def _null_text_stream() -> TextIO:
+    """Open a text stream on the null device."""
+    sink = os.open(os.devnull, os.O_WRONLY)
+    try:
+        return os.fdopen(sink, 'w', encoding='utf-8')
+    except BaseException:
+        os.close(sink)
+        raise
+
+
+def is_downstream_closure(error: OSError, *, windows: bool | None = None) -> bool:
+    """Report whether a write or flush failed because the reader closed the stream.
+
+    Args:
+        error: Error raised by a write or flush of an output stream.
+        windows: Whether Windows error reporting applies, or `None` for the
+            running platform. CPython on Windows can report a write to a pipe
+            whose reader closed as `EINVAL`.
+
+    Returns:
+        Whether the error means the downstream reader is gone.
+    """
+    on_windows = _WINDOWS if windows is None else windows
+    return isinstance(error, BrokenPipeError) or (on_windows and error.errno == errno.EINVAL)
+
+
+class ClosableTextOutput:
+    """Text output that discards writes after its downstream reader closes.
+
+    Attributes other than writing and flushing come from the wrapped stream, so
+    encoding, terminal detection, and reconfiguration behave as on that stream.
+    """
+
+    def __init__(self, stream: TextIO, *, windows: bool | None = None) -> None:
+        """Wrap a text stream.
+
+        Args:
+            stream: Stream written through until its reader closes.
+            windows: Whether Windows closed-pipe reporting applies, or `None`
+                for the running platform.
+        """
+        self._closed_downstream = False
+        self._stream = stream
+        self._windows = windows
+
+    def __getattr__(self, name: str) -> object:
+        """Return an attribute of the wrapped stream."""
+        return getattr(self._stream, name)
+
+    @property
+    def closed_downstream(self) -> bool:
+        """Whether the downstream reader has closed the stream."""
+        return self._closed_downstream
+
+    def flush(self) -> None:
+        """Flush the wrapped stream unless its reader has closed.
+
+        Raises:
+            OSError: If flushing fails for a reason other than closure.
+        """
+        if self._closed_downstream:
+            return
+        try:
+            self._stream.flush()
+        except OSError as error:
+            if not is_downstream_closure(error, windows=self._windows):
+                raise
+            self._closed_downstream = True
+
+    def write(self, text: str) -> int:
+        """Write text, or discard it after the reader has closed.
+
+        Args:
+            text: Text to write.
+
+        Returns:
+            The number of characters accepted.
+
+        Raises:
+            OSError: If writing fails for a reason other than closure.
+        """
+        if self._closed_downstream:
+            return len(text)
+        try:
+            return self._stream.write(text)
+        except OSError as error:
+            if not is_downstream_closure(error, windows=self._windows):
+                raise
+            self._closed_downstream = True
+            return len(text)
+
+    def writelines(self, lines: Iterable[str]) -> None:
+        """Write lines until the reader closes, then stop consuming them.
+
+        Args:
+            lines: Text lines in output order.
+
+        Raises:
+            OSError: If writing fails for a reason other than closure.
+        """
+        if self._closed_downstream:
+            return
+        for line in lines:
+            self.write(line)
+            if self._closed_downstream:
+                return
+
+
+def silence_descriptor(stream: TextIO) -> bool:
+    """Point a stream's descriptor at the null device when it has one.
+
+    Args:
+        stream: Stream whose descriptor the interpreter flushes at shutdown.
+
+    Returns:
+        Whether the stream had a descriptor to redirect.
+
+    Raises:
+        OSError: If redirecting an existing descriptor fails.
+    """
+    try:
+        target = stream.fileno()
+    except (OSError, ValueError):
+        return False
+    devnull = os.open(os.devnull, os.O_WRONLY)
+    try:
+        os.dup2(devnull, target)
+    finally:
+        os.close(devnull)
+    return True
+
+
+@contextlib.contextmanager
+def closable_stdout() -> Generator[ClosableTextOutput]:
+    """Route standard output through a closure-absorbing wrapper.
+
+    On every exit, including `SystemExit` from argument parsing, pending output
+    is flushed through the wrapper and the original stream is restored. If the
+    reader closed, the original descriptor is pointed at the null device, or a
+    stream without a descriptor is replaced by a null-device stream, so the
+    interpreter's final flush cannot fail again.
+
+    Yields:
+        The installed wrapper.
+    """
+    original = sys.stdout
+    output = ClosableTextOutput(original)
+    sys.stdout = cast('TextIO', output)
+    try:
+        yield output
+    finally:
+        try:
+            output.flush()
+        finally:
+            sys.stdout = original
+            if output.closed_downstream and not silence_descriptor(original):
+                # The interpreter still flushes a stream without a descriptor
+                # at shutdown, so replace it with one that cannot fail.
+                sys.stdout = _null_text_stream()
+
+
+def stdout_closed() -> bool:
+    """Report whether standard output's downstream reader has closed.
+
+    Returns:
+        Whether the installed wrapper has observed closure.
+    """
+    output = sys.stdout
+    return isinstance(output, ClosableTextOutput) and output.closed_downstream

sequential_hooks/_executable.py

@@ -0,0 +1,187 @@
+"""Resolve supported child executable paths without launching them."""
+
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+_DEFAULT_WINDOWS_PATHEXT = ('.COM', '.EXE', '.BAT', '.CMD')
+_RUNNABLE_WINDOWS_SUFFIXES = frozenset({'.com', '.exe'})
+_UNSUPPORTED_WINDOWS_SUFFIXES = frozenset({'.bat', '.cmd', '.ps1'})
+_WINDOWS_PATH_SEPARATOR = ';'
+
+
+class ExecutableStatus(StrEnum):
+    """Classify a resolved child executable.
+
+    Attributes:
+        RUNNABLE: The executable can be started directly.
+        NOT_FOUND: No matching executable could be resolved.
+        UNSUPPORTED_SHIM: Resolution found a shell-dependent Windows shim.
+    """
+
+    RUNNABLE = 'runnable'
+    NOT_FOUND = 'not_found'
+    UNSUPPORTED_SHIM = 'unsupported_shim'
+
+
+@dataclass(frozen=True)
+class ExecutableResolution:
+    """Describe the static resolution of one executable token.
+
+    Args:
+        requested: Literal executable token supplied by the caller.
+        resolved: Matching filesystem path, if one was found.
+        status: Classification of the resolution result.
+        correction: Safe corrective guidance for an unsupported result.
+
+    Attributes:
+        requested: Literal executable token supplied by the caller.
+        resolved: Matching filesystem path, if one was found.
+        status: Classification of the resolution result.
+        correction: Safe corrective guidance for an unsupported result.
+    """
+
+    requested: str
+    resolved: Path | None
+    status: ExecutableStatus
+    correction: str | None = None
+
+
+def _case_insensitive_file(candidate: Path) -> Path | None:
+    """Return the actual-cased file matching one Windows candidate."""
+    current = Path(candidate.anchor) if candidate.is_absolute() else Path()
+    parts = candidate.parts[1:] if candidate.is_absolute() else candidate.parts
+    for part in parts:
+        if part == '..':
+            current /= part
+            continue
+        try:
+            matches = sorted(
+                (child for child in current.iterdir() if child.name.casefold() == part.casefold()),
+                key=lambda child: child.name,
+            )
+        except OSError:
+            return None
+        if not matches:
+            return None
+        current = next((child for child in matches if child.name == part), matches[0])
+    return current if current.is_file() else None
+
+
+def _not_found(requested: str) -> ExecutableResolution:
+    """Build a missing-executable result."""
+    return ExecutableResolution(requested, None, ExecutableStatus.NOT_FOUND)
+
+
+def _resolve_posix(executable: str, path_value: str | None) -> ExecutableResolution:
+    """Resolve one executable with POSIX path and permission rules."""
+    if '/' in executable:
+        candidate = Path(executable)
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return ExecutableResolution(executable, candidate, ExecutableStatus.RUNNABLE)
+        return _not_found(executable)
+    if path_value is None:
+        return _not_found(executable)
+    resolved = shutil.which(executable, path=path_value)
+    if resolved is None:
+        return _not_found(executable)
+    return ExecutableResolution(executable, Path(resolved), ExecutableStatus.RUNNABLE)
+
+
+def _windows_candidate_names(executable: str, pathext: tuple[str, ...]) -> tuple[str, ...]:
+    """Apply Windows executable suffix search rules to one token."""
+    suffix = Path(executable).suffix.casefold()
+    if (
+        suffix in _RUNNABLE_WINDOWS_SUFFIXES
+        or suffix in _UNSUPPORTED_WINDOWS_SUFFIXES
+        or any(suffix == extension.casefold() for extension in pathext)
+    ):
+        return (executable,)
+    return tuple(f'{executable}{extension}' for extension in pathext)
+
+
+def _windows_resolution(
+    requested: str,
+    candidate: Path,
+) -> ExecutableResolution | None:
+    """Classify one existing native or simulated Windows candidate."""
+    if sys.platform == 'win32':
+        resolved = candidate if candidate.is_file() else None
+    else:
+        resolved = _case_insensitive_file(candidate)
+    if resolved is None:
+        return None
+    if resolved.suffix.casefold() in _UNSUPPORTED_WINDOWS_SUFFIXES:
+        correction = (
+            f'Use a real executable entry point for {requested}; '
+            f'resolved unsupported Windows shim {resolved}.'
+        )
+        return ExecutableResolution(
+            requested,
+            resolved,
+            ExecutableStatus.UNSUPPORTED_SHIM,
+            correction,
+        )
+    if resolved.suffix.casefold() not in _RUNNABLE_WINDOWS_SUFFIXES:
+        return None
+    return ExecutableResolution(requested, resolved, ExecutableStatus.RUNNABLE)
+
+
+def _resolve_windows(
+    executable: str,
+    path_value: str | None,
+    pathext_value: str | None,
+) -> ExecutableResolution:
+    """Resolve one executable with Windows search rules."""
+    pathext = (
+        tuple(extension for extension in pathext_value.split(_WINDOWS_PATH_SEPARATOR) if extension)
+        if pathext_value is not None
+        else ()
+    )
+    if not pathext:
+        pathext = _DEFAULT_WINDOWS_PATHEXT
+    names = _windows_candidate_names(executable.replace('\\', os.sep), pathext)
+    if '/' in executable or '\\' in executable:
+        directories = ('',)
+    elif path_value:
+        directories = tuple(path_value.split(_WINDOWS_PATH_SEPARATOR))
+    else:
+        directories = ()
+
+    for directory in directories:
+        normalized_directory = directory.replace('\\', os.sep)
+        if len(directory) > 1 and directory.startswith('"') and directory.endswith('"'):
+            normalized_directory = normalized_directory[1:-1]
+        for name in names:
+            candidate = Path(normalized_directory) / name
+            if resolution := _windows_resolution(executable, candidate):
+                return resolution
+    return _not_found(executable)
+
+
+def resolve_executable(
+    executable: str,
+    *,
+    path_value: str | None,
+    windows: bool,
+    pathext_value: str | None,
+) -> ExecutableResolution:
+    """Resolve one literal executable without starting it.
+
+    Args:
+        executable: Literal executable token to resolve.
+        path_value: Injected executable search path, if set.
+        windows: Whether to apply Windows lookup rules.
+        pathext_value: Injected Windows executable suffix list, if set.
+
+    Returns:
+        Static executable resolution and any required correction.
+    """
+    if not executable:
+        return _not_found(executable)
+    if windows:
+        return _resolve_windows(executable, path_value, pathext_value)
+    return _resolve_posix(executable, path_value)