hostctl 0.1.0__py3-none-any.whl

hostctl/executor/container.py

@@ -0,0 +1,171 @@
+"""Docker Engine command executor."""
+
+from __future__ import annotations
+
+import subprocess
+import typing
+
+from ._common import (
+    CaptureOutput,
+    CommandArgument,
+    Environment,
+    Executor,
+    ExecutorCapability,
+    ExecutorCommand,
+    FileHandle,
+    Input,
+    PathLike,
+    dispatch_output,
+    normalize_environment,
+    capture_streams,
+)
+
+
+class ContainerLike(typing.Protocol):
+    """Small Docker SDK container surface used by :class:`ContainerExecutor`."""
+
+    def exec_run(self, command: typing.Sequence[str], **options: object) -> object: ...
+
+
+class ContainerExecutor(Executor[subprocess.CompletedProcess]):
+    """Execute argv directly through a Docker Engine container exec."""
+
+    executor_capabilities = frozenset(
+        (ExecutorCapability.ARGS, ExecutorCapability.CWD, ExecutorCapability.ENV)
+    )
+
+    def __init__(
+        self,
+        container: typing.Callable[[], ContainerLike],
+        *,
+        user: typing.Optional[str] = None,
+        workdir: typing.Optional[str] = None,
+    ) -> None:
+        self._container = container
+        self._user = user
+        self._workdir = workdir
+
+    def __call__(
+        self,
+        command: ExecutorCommand,
+        *args: CommandArgument,
+        bufsize: int = -1,
+        stdin: typing.Optional[FileHandle] = None,
+        stdout: typing.Optional[FileHandle] = None,
+        stderr: typing.Optional[FileHandle] = None,
+        cwd: typing.Optional[PathLike] = None,
+        env: typing.Optional[Environment] = None,
+        capture_output: CaptureOutput = True,
+        check: bool = True,
+        encoding: typing.Optional[str] = None,
+        errors: typing.Optional[str] = None,
+        input: Input = None,
+        timeout: typing.Optional[float] = None,
+        text: typing.Optional[bool] = None,
+        **options: object,
+    ) -> subprocess.CompletedProcess:
+        del bufsize
+        if options:
+            raise TypeError(
+                f"unsupported container executor option: {sorted(options)[0]}"
+            )
+        if stdin is not None or input is not None:
+            raise NotImplementedError(
+                "buffered container execution does not yet support stdin/input"
+            )
+        if timeout is not None:
+            raise NotImplementedError(
+                "Docker Engine exec does not provide a cancellable command timeout"
+            )
+
+        stdout, stderr = capture_streams(capture_output, stdout, stderr)
+        argv = [str(command)]
+        argv.extend(
+            value.decode() if isinstance(value, bytes) else str(value) for value in args
+        )
+        merge_stderr = stderr is subprocess.STDOUT
+        exec_options: typing.Dict[str, object] = {
+            "stdout": True,
+            "stderr": True,
+            # Docker's demux=False stream preserves stdout/stderr ordering,
+            # which is required when callers request STDERR->STDOUT.
+            "demux": not merge_stderr,
+        }
+        normalized_env = normalize_environment(env)
+        if normalized_env is not None:
+            exec_options["environment"] = normalized_env
+        selected_workdir = str(cwd) if cwd is not None else self._workdir
+        if selected_workdir is not None:
+            exec_options["workdir"] = selected_workdir
+        if self._user is not None:
+            exec_options["user"] = self._user
+
+        try:
+            result = self._container().exec_run(argv, **exec_options)
+        except Exception as exc:
+            if _is_not_found(exc):
+                raise ConnectionError("container not found") from exc
+            normalized = normalize_container_error(exc)
+            if normalized is exc:
+                raise
+            raise normalized from exc
+
+        returncode = typing.cast(int, getattr(result, "exit_code"))
+        output = getattr(result, "output")
+        if isinstance(output, tuple):
+            out, err = output
+        else:
+            out, err = output, None
+        if out is None:
+            out = b""
+        if err is None and not merge_stderr:
+            err = b""
+        if text or encoding is not None or errors is not None:
+            codec = encoding or "utf-8"
+            out = (
+                out.decode(codec, errors or "strict") if isinstance(out, bytes) else out
+            )
+            err = (
+                err.decode(codec, errors or "strict") if isinstance(err, bytes) else err
+            )
+        if merge_stderr:
+            if err:
+                out = out + err
+            err = None
+        out, err = dispatch_output(
+            stdout, stderr, out, err, encoding=encoding, errors=errors
+        )
+        completed = subprocess.CompletedProcess(argv, returncode, out, err)
+        if check:
+            completed.check_returncode()
+        return completed
+
+
+def normalize_container_error(exc: Exception) -> Exception:
+    """Map Docker SDK and HTTP failures without importing the optional SDK."""
+    name = type(exc).__name__
+    status_code = getattr(exc, "status_code", None)
+    if status_code is None:
+        response = getattr(exc, "response", None)
+        status_code = getattr(response, "status_code", None)
+    if status_code == 404 or name in ("NotFound",):
+        return FileNotFoundError(str(exc))
+    if status_code in (401, 403) or name in ("AuthenticationError",):
+        return PermissionError(str(exc))
+    if name in ("ReadTimeout", "ConnectTimeout", "Timeout"):
+        return TimeoutError(str(exc))
+    if name in (
+        "APIError",
+        "ConnectionError",
+        "DockerException",
+        "MaxRetryError",
+    ):
+        return ConnectionError(str(exc))
+    return exc
+
+
+def _is_not_found(exc: Exception) -> bool:
+    status_code = getattr(exc, "status_code", None)
+    if status_code is None:
+        status_code = getattr(getattr(exc, "response", None), "status_code", None)
+    return status_code == 404 or type(exc).__name__ == "NotFound"

hostctl/executor/local.py

@@ -0,0 +1,91 @@
+"""Local subprocess executor."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import typing
+
+from ._common import (
+    CaptureOutput,
+    CommandArgument,
+    Environment,
+    Executor,
+    ExecutorCapability,
+    ExecutorCommand,
+    FileHandle,
+    Input,
+    normalize_environment,
+    normalize_input,
+    capture_streams,
+    reject_stdin_conflict,
+)
+
+
+class LocalExecutor(Executor[subprocess.CompletedProcess]):
+    """Execute direct argv or finalized shell invocations locally."""
+
+    executor_capabilities = frozenset(
+        (ExecutorCapability.ARGS, ExecutorCapability.CWD, ExecutorCapability.ENV)
+    )
+
+    def __call__(
+        self,
+        command: ExecutorCommand,
+        *args: CommandArgument,
+        bufsize: int = -1,
+        stdin: typing.Optional[FileHandle] = None,
+        stdout: typing.Optional[FileHandle] = None,
+        stderr: typing.Optional[FileHandle] = None,
+        cwd: typing.Optional[typing.Union[str, os.PathLike[str]]] = None,
+        env: typing.Optional[Environment] = None,
+        capture_output: CaptureOutput = True,
+        check: bool = True,
+        encoding: typing.Optional[str] = None,
+        errors: typing.Optional[str] = None,
+        input: Input = None,
+        timeout: typing.Optional[float] = None,
+        text: typing.Optional[bool] = None,
+        **options: object,
+    ) -> subprocess.CompletedProcess:
+        if options:
+            raise TypeError(f"unsupported local executor option: {sorted(options)[0]}")
+        reject_stdin_conflict(input, stdin)
+        stdout, stderr = capture_streams(capture_output, stdout, stderr)
+        argv = [
+            os.fspath(command),
+            *[
+                (
+                    value.decode()
+                    if isinstance(value, bytes)
+                    else (
+                        os.fspath(value)
+                        if isinstance(value, os.PathLike)
+                        else str(value)
+                    )
+                )
+                for value in args
+            ],
+        ]
+        return subprocess.run(
+            argv,
+            bufsize=bufsize,
+            stdin=stdin,
+            stdout=stdout,
+            stderr=stderr,
+            cwd=os.fspath(cwd) if cwd is not None else None,
+            env=normalize_environment(env),
+            check=check,
+            encoding=encoding,
+            errors=errors,
+            # `encoding`/`errors`/`text` put subprocess's stdin in text mode,
+            # where bytes would kill the writer thread and hang the call.
+            input=normalize_input(
+                input,
+                text_mode=bool(encoding or errors or text),
+                encoding=encoding,
+                errors=errors,
+            ),
+            timeout=timeout,
+            text=text,
+        )

hostctl/executor/psrp.py

@@ -0,0 +1,145 @@
+"""Optional PowerShell Remoting Protocol execution provider."""
+
+from __future__ import annotations
+
+import importlib
+import subprocess
+import typing
+import types
+
+from ._common import (
+    CaptureOutput,
+    CommandArgument,
+    Executor,
+    ExecutorCapability,
+    ExecutorCommand,
+    FileHandle,
+    Input,
+    capture_streams,
+    dispatch_output,
+)
+
+if typing.TYPE_CHECKING:
+    from ..process import RunspaceSession
+
+
+def pypsrp_available() -> bool:
+    """Return whether the optional PSRP dependency can be imported."""
+    if __import__("sys").version_info < (3, 10):
+        return False
+    try:
+        importlib.import_module("pypsrp")
+    except ImportError:
+        return False
+    return True
+
+
+def require_pypsrp() -> types.ModuleType:
+    """Import pypsrp with an actionable, version-aware error."""
+    import sys
+
+    if sys.version_info < (3, 10):
+        raise ImportError(
+            "PSRP support requires Python 3.10 or newer; use the pywinrm "
+            "provider on Python 3.9"
+        )
+    try:
+        return importlib.import_module("pypsrp")
+    except ImportError as exc:
+        raise ImportError(
+            "PSRP support requires the 'psrp' extra: " "pip install hostctl[psrp]"
+        ) from exc
+
+
+class PsrpExecutor(Executor[subprocess.CompletedProcess]):
+    """Execute finalized PowerShell scripts in fresh PSRP pipelines."""
+
+    # PSRP receives a finalized PowerShell script; cwd/env are embedded by
+    # the host shell rather than forwarded as unsupported executor options.
+    executor_capabilities = frozenset(
+        (ExecutorCapability.SCRIPT, ExecutorCapability.MANAGES_STATUS)
+    )
+
+    def __init__(self, session: typing.Callable[[], RunspaceSession]) -> None:
+        self._session = session
+
+    def __call__(
+        self,
+        command: ExecutorCommand,
+        *args: CommandArgument,
+        bufsize: int = -1,
+        stdin: typing.Optional[FileHandle] = None,
+        stdout: typing.Optional[FileHandle] = None,
+        stderr: typing.Optional[FileHandle] = None,
+        capture_output: CaptureOutput = True,
+        check: bool = True,
+        encoding: typing.Optional[str] = None,
+        errors: typing.Optional[str] = None,
+        input: Input = None,
+        timeout: typing.Optional[float] = None,
+        text: typing.Optional[bool] = None,
+        **options: object,
+    ) -> subprocess.CompletedProcess:
+        del bufsize
+        if options:
+            raise TypeError(f"unsupported PSRP executor option: {sorted(options)[0]}")
+        if args:
+            raise NotImplementedError("PSRP executor receives a finalized script")
+        if stdin is not None or input is not None:
+            raise NotImplementedError("PSRP does not provide raw stdin for run()")
+        if timeout is not None:
+            raise NotImplementedError(
+                "PSRP pipeline timeout is unsupported; configure WinRM timeouts"
+            )
+        stdout, stderr = capture_streams(capture_output, stdout, stderr)
+        result = self._session().invoke(str(command), raw=False, capture_exit=True)
+        codec = encoding or "utf-8"
+        # Preserve PowerShell's object-pipeline line orientation when
+        # projecting objects to subprocess-compatible text.
+        projected_output = []
+        returncode = result.returncode
+        marker = "__HOSTCTL_LASTEXITCODE__:"
+        for item in result.output:
+            value = str(item)
+            if value.startswith(marker):
+                try:
+                    parsed_returncode = int(value[len(marker) :])
+                    returncode = (
+                        1
+                        if result.had_errors and parsed_returncode == 0
+                        else parsed_returncode
+                    )
+                except ValueError:
+                    returncode = 1
+                continue
+            projected_output.append(item)
+        out_text = "\n".join(str(item) for item in projected_output)
+        err_text = "\n".join(str(item) for item in result.streams.error)
+        if out_text:
+            out_text += "\n"
+        out: typing.Union[str, bytes] = (
+            out_text if text or encoding else out_text.encode(codec)
+        )
+        err: typing.Union[str, bytes] = (
+            err_text if text or encoding else err_text.encode(codec)
+        )
+        if stderr is subprocess.STDOUT:
+            out = out + err
+            err = None
+        out, err = dispatch_output(
+            stdout,
+            stderr,
+            out,
+            err,
+            encoding=encoding,
+            errors=errors,
+        )
+        completed = subprocess.CompletedProcess(
+            args=str(command),
+            returncode=returncode,
+            stdout=out,
+            stderr=err,
+        )
+        if check:
+            completed.check_returncode()
+        return completed