hostctl 0.1.0__py3-none-any.whl

hostctl/__init__.py

@@ -0,0 +1,194 @@
+"""hostctl -- run commands and access files on a host, local or remote.
+
+Protocol-agnostic host management: concrete hosts expose only the operations
+their providers support. Shell dialect and path flavor remain explicit where
+the transport cannot identify them.
+
+``__all__`` is the package's promise: every name here is one a caller must be
+able to *write* -- to construct a host or config, to catch an exception, to
+annotate its own code, to pass as an argument, or to implement at a documented
+extension point. Concrete backends, transport adapters, and result types the
+library only ever hands back are reachable from their defining submodules
+(``hostctl.host.qemu``, ``hostctl.provider.transports``, ``hostctl.process``,
+and so on) but are not part of the stable surface.
+"""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _version
+
+    __version__ = _version("hostctl")
+except PackageNotFoundError:  # not installed (e.g. running from a bare checkout)
+    __version__ = "0.0.0.dev0"
+
+from .executor import (
+    Executor as Executor,
+    ExecutorCapability as ExecutorCapability,
+    ExecutorCommand as ExecutorCommand,
+    ExecutionOptions as ExecutionOptions,
+    LocalExecutor as LocalExecutor,
+    pypsrp_available as pypsrp_available,
+    require_pypsrp as require_pypsrp,
+)
+from .host import (
+    ContainerConfig as ContainerConfig,
+    ContainerHost as ContainerHost,
+    Host as Host,
+    HostConfig as HostConfig,
+    HostInfo as HostInfo,
+    HostPath as HostPath,
+    LocalConfig as LocalConfig,
+    LocalHost as LocalHost,
+    parse_credentials as parse_credentials,
+    redact_uri as redact_uri,
+    ssh_providers as ssh_providers,
+    strict_uri_credentials as strict_uri_credentials,
+    strict_uri_query as strict_uri_query,
+    uri_host as uri_host,
+    winrm_providers as winrm_providers,
+    QemuConfig as QemuConfig,
+    QemuHost as QemuHost,
+    SshConfig as SshConfig,
+    SerialConfig as SerialConfig,
+    SerialHost as SerialHost,
+    WinRMConfig as WinRMConfig,
+    WinRMPath as WinRMPath,
+    SystemConfig as SystemConfig,
+    SystemHost as SystemHost,
+    PosixConfig as PosixConfig,
+    PosixHost as PosixHost,
+    WindowsConfig as WindowsConfig,
+    WindowsHost as WindowsHost,
+    register_system_provider as register_system_provider,
+    IosConfig as IosConfig,
+    IosHost as IosHost,
+    CompositePosixPath as CompositePosixPath,
+    CompositeWindowsPath as CompositeWindowsPath,
+)
+from .provider import (
+    ExecutorProvider as ExecutorProvider,
+    OperationNotStarted as OperationNotStarted,
+    PathProvider as PathProvider,
+    ProviderProbe as ProviderProbe,
+    ProviderSelection as ProviderSelection,
+    ProviderSelector as ProviderSelector,
+    SessionInitializer as SessionInitializer,
+)
+from .executor._qga import (
+    QgaCommandError as QgaCommandError,
+    QgaProtocolError as QgaProtocolError,
+)
+from .process import (
+    Process as Process,
+    TerminalOptions as TerminalOptions,
+)
+from .serial import (
+    ConsoleProtocolError as ConsoleProtocolError,
+    LoginStep as LoginStep,
+    PromptConsoleProfile as PromptConsoleProfile,
+    RawConsoleProfile as RawConsoleProfile,
+    SerialConsoleProtocol as SerialConsoleProtocol,
+)
+from .sync import (
+    ProgressReader as ProgressReader,
+    host_checksum as host_checksum,
+    stat_checksum as stat_checksum,
+)
+from .shell import (
+    BASH as BASH,
+    CMD as CMD,
+    FISH as FISH,
+    POWERSHELL as POWERSHELL,
+    POSIX_SHELL as POSIX_SHELL,
+    PWSH as PWSH,
+    ZSH as ZSH,
+    Shell as Shell,
+    ShellFlavour as ShellFlavour,
+    ShellOperator as ShellOperator,
+    ShellSession as ShellSession,
+    register_shell_flavour as register_shell_flavour,
+    shell_flavour as shell_flavour,
+)
+
+__all__ = [
+    # Hosts and configuration
+    "Host",
+    "HostConfig",
+    "HostInfo",
+    "HostPath",
+    "LocalConfig",
+    "LocalHost",
+    "parse_credentials",
+    "redact_uri",
+    "ssh_providers",
+    "strict_uri_credentials",
+    "strict_uri_query",
+    "uri_host",
+    "winrm_providers",
+    "SshConfig",
+    "WinRMConfig",
+    "WinRMPath",
+    "ContainerConfig",
+    "ContainerHost",
+    "QemuConfig",
+    "QemuHost",
+    "SerialConfig",
+    "SerialHost",
+    "SystemConfig",
+    "SystemHost",
+    "PosixConfig",
+    "PosixHost",
+    "WindowsConfig",
+    "WindowsHost",
+    "IosConfig",
+    "IosHost",
+    # Executors and processes
+    "Executor",
+    "ExecutionOptions",
+    "ExecutorCapability",
+    "ExecutorCommand",
+    "LocalExecutor",
+    "pypsrp_available",
+    "require_pypsrp",
+    "Process",
+    "TerminalOptions",
+    "QgaCommandError",
+    "QgaProtocolError",
+    # Shells and sessions
+    "Shell",
+    "ShellFlavour",
+    "ShellOperator",
+    "ShellSession",
+    "register_shell_flavour",
+    "shell_flavour",
+    "BASH",
+    "CMD",
+    "FISH",
+    "POWERSHELL",
+    "POSIX_SHELL",
+    "PWSH",
+    "ZSH",
+    # Serial consoles
+    "SerialConsoleProtocol",
+    "RawConsoleProfile",
+    "PromptConsoleProfile",
+    "LoginStep",
+    "ConsoleProtocolError",
+    # Provider composition
+    "ExecutorProvider",
+    "PathProvider",
+    "ProviderProbe",
+    "ProviderSelection",
+    "ProviderSelector",
+    "OperationNotStarted",
+    "SessionInitializer",
+    "register_system_provider",
+    "CompositePosixPath",
+    "CompositeWindowsPath",
+    # Transfer helpers
+    "ProgressReader",
+    "host_checksum",
+    "stat_checksum",
+    "__version__",
+]

hostctl/__main__.py

@@ -0,0 +1,6 @@
+"""Execute ``python -m hostctl``."""
+
+from ._cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hostctl/_async.py

@@ -0,0 +1,169 @@
+"""Run an awaitable to completion from synchronous code.
+
+``asyncssh`` is fully async, but :class:`~hostctl.host.Host` presents a
+synchronous API, so its direct-asyncssh operations (opening the connection,
+running a remote command) are driven to completion here. SFTP is NOT among
+them: :meth:`~hostctl.host.Host.path` uses `pathlib_next`'s own ``SftpPath``
+(with its own async bridge), not this one.
+
+The bridge is a single **shared background event loop** running in a daemon
+thread; each call submits its coroutine with ``run_coroutine_threadsafe`` and
+blocks on the result. This works whether or not the *calling* thread already
+has a running loop (the coroutine runs on the dedicated background loop, not
+the caller's), so no ``nest_asyncio`` re-entrancy hack is needed -- and it
+avoids the deprecated ``asyncio.get_event_loop()``/policy APIs (slated for
+removal in 3.16). asyncssh objects created through this bridge are bound to
+this loop, so all subsequent operations on them must also go through here.
+"""
+
+from __future__ import annotations
+
+import asyncio as _asyncio
+import os as _os
+import subprocess as _subprocess
+import sys as _sys
+import threading as _threading
+import typing as _ty
+
+_T = _ty.TypeVar("_T")
+
+_loop: _ty.Optional[_asyncio.AbstractEventLoop] = None
+_loop_pid: _ty.Optional[int] = None
+_loop_thread: _ty.Optional[_threading.Thread] = None
+_loop_lock = _threading.Lock()
+
+
+def asyncssh():
+    """Import ``asyncssh`` on demand (the ``ssh`` extra)."""
+    try:
+        import asyncssh
+    except ImportError as exc:  # pragma: no cover - only without the extra
+        raise ImportError(
+            "SSH support requires the 'ssh' extra: pip install hostctl[ssh]"
+        ) from exc
+    return asyncssh
+
+
+def normalize_asyncssh_error(
+    exc: Exception,
+    *,
+    command: _ty.Optional[str] = None,
+    timeout: _ty.Optional[float] = None,
+) -> Exception:
+    """Map AsyncSSH transport/process errors to hostctl's standard contract."""
+    module = asyncssh()
+    if isinstance(exc, (TimeoutError, module.TimeoutError)):
+        if command is not None:
+            return _subprocess.TimeoutExpired(
+                command,
+                timeout,
+                output=getattr(exc, "stdout", None),
+                stderr=getattr(exc, "stderr", None),
+            )
+        # Connection/open timeouts have no subprocess command to attach, but
+        # must still cross the public boundary as a builtin timeout rather
+        # than leaking an AsyncSSH-specific exception.
+        return TimeoutError(str(exc))
+    if isinstance(exc, module.PermissionDenied):
+        return PermissionError(str(exc))
+    if isinstance(exc, module.ProcessError):
+        returncode = getattr(exc, "returncode", None)
+        if returncode is None:
+            returncode = -1
+        return _subprocess.CalledProcessError(
+            returncode,
+            command or getattr(exc, "command", None),
+            output=getattr(exc, "stdout", None),
+            stderr=getattr(exc, "stderr", None),
+        )
+    connection_errors = (
+        module.ChannelOpenError,
+        module.DisconnectError,
+        module.HostKeyNotVerifiable,
+        module.KeyExchangeFailed,
+        module.ProtocolError,
+    )
+    if isinstance(exc, connection_errors):
+        return ConnectionError(str(exc))
+    return exc
+
+
+def _new_loop() -> _asyncio.AbstractEventLoop:
+    if _sys.platform == "win32":
+        # SelectorEventLoop, not the Windows-default Proactor loop: this
+        # bridge only makes plain-TCP SSH client connections (no subprocess
+        # pipes), and Proactor's pipe transports emit a benign-but-noisy
+        # "Exception ignored in _ProactorBasePipeTransport.__del__" on GC.
+        return _asyncio.SelectorEventLoop()
+    return _asyncio.new_event_loop()
+
+
+def _ensure_loop() -> _asyncio.AbstractEventLoop:
+    global _loop, _loop_pid, _loop_thread
+    pid = _os.getpid()
+    with _loop_lock:
+        if (
+            _loop is not None
+            and not _loop.is_closed()
+            and _loop_pid == pid
+            and _loop_thread is not None
+            and _loop_thread.is_alive()
+        ):
+            return _loop
+        # First call, or a fork()'d child that inherited a now-dead loop thread.
+        if _loop is not None and (
+            _loop_pid != pid or _loop_thread is None or not _loop_thread.is_alive()
+        ):
+            try:
+                _loop.close()
+            except Exception:
+                pass
+        loop = _new_loop()
+        thread = _threading.Thread(
+            target=loop.run_forever,
+            name="hostctl-asyncssh-loop",
+            daemon=True,
+        )
+        thread.start()
+        _loop, _loop_pid, _loop_thread = loop, pid, thread
+        return loop
+
+
+def async_to_sync(
+    awaitable: _ty.Awaitable[_T],
+) -> _T:
+    """Drive ``awaitable`` to completion on the shared background loop.
+
+    Safe to call from any thread and from inside an unrelated running event
+    loop. Calling from the bridge loop itself is rejected to avoid deadlock.
+    """
+    try:
+        running = _asyncio.get_running_loop()
+    except RuntimeError:
+        running = None
+    if running is not None and running is _loop:
+        if _asyncio.iscoroutine(awaitable):
+            awaitable.close()
+        raise RuntimeError("async_to_sync called from the bridge loop thread")
+    loop = _ensure_loop()
+    if _loop_thread is None or not _loop_thread.is_alive():
+        if _asyncio.iscoroutine(awaitable):
+            awaitable.close()
+        raise RuntimeError("hostctl async bridge thread is not alive")
+    future = _asyncio.run_coroutine_threadsafe(_ensure_coro(awaitable), loop)
+    return future.result()
+
+
+def _ensure_coro(
+    awaitable: _ty.Awaitable[_T],
+) -> _ty.Coroutine[_ty.Any, _ty.Any, _T]:
+    """Adapt any awaitable to a coroutine (``run_coroutine_threadsafe`` requires
+    a genuine coroutine object; asyncssh's ``@async_context_manager`` awaitables
+    and futures are not)."""
+    if _asyncio.iscoroutine(awaitable):
+        return awaitable
+
+    async def _wrap() -> _T:
+        return await awaitable
+
+    return _wrap()

hostctl/_cli.py

@@ -0,0 +1,232 @@
+"""Small stdlib command-line adapter over the public hostctl API."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import dataclasses
+import getpass
+import json
+import os
+from pathlib import PurePath
+import re
+import subprocess
+import sys
+import threading
+import typing
+
+from pathlib_next import Path as NextPath
+
+from .host import Host, HostPath
+
+_URI_OPERAND = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+_OutputStream = typing.Union[typing.TextIO, typing.BinaryIO]
+_OutputValue = typing.Union[str, bytes]
+
+
+def _write(stream: _OutputStream, value: _OutputValue) -> None:
+    if value is None:
+        return
+    if isinstance(value, bytes):
+        binary = getattr(stream, "buffer", stream)
+        binary.write(value)
+    else:
+        stream.write(str(value))
+    flush = getattr(stream, "flush", None)
+    if flush:
+        flush()
+
+
+def _credentials(args: argparse.Namespace) -> dict[str, object]:
+    password = os.environ.get("HOSTCTL_PASSWORD")
+    if args.ask_password:
+        password = getpass.getpass("Password: ")
+    return {"password": password} if password is not None else {}
+
+
+def _open_host(stack: contextlib.ExitStack, uri: str, credentials: dict[str, object]):
+    return stack.enter_context(Host(uri, **credentials))
+
+
+def _path_operand(
+    stack: contextlib.ExitStack,
+    value: str,
+    credentials: dict[str, object],
+):
+    """Resolve ``URI:PATH`` or an ordinary local filesystem path."""
+    if not _URI_OPERAND.match(value) or re.match(r"^[A-Za-z]:[\\/]", value):
+        return HostPath(value)
+    if "://" in value:
+        authority_end = value.find("/", value.find("://") + 3)
+        search_end = len(value) if authority_end < 0 else authority_end
+        separator = value.rfind(":", 0, search_end)
+        if separator <= value.find("://") + 2:
+            raise ValueError("remote path operand must be URI:PATH")
+    else:
+        separator = value.find(":", value.find(":") + 1)
+        if separator < 0:
+            raise ValueError("remote path operand must be URI:PATH")
+    uri, path = value[:separator], value[separator + 1 :]
+    if not path:
+        raise ValueError("remote path operand requires a path")
+    return _open_host(stack, uri, credentials).path(path)
+
+
+def _command_run(args: argparse.Namespace, stdout, stderr) -> int:
+    command = list(args.command)
+    if command[:1] == ["--"]:
+        command.pop(0)
+    if not command:
+        raise ValueError("run requires a command after --")
+    with Host(args.uri, **_credentials(args)) as host:
+        try:
+            command_path = host.shell_flavour.command_path(command[0])
+        except NotImplementedError:
+            command_path = PurePath(command[0])
+        result = host.run(
+            command_path,
+            *command[1:],
+            check=False,
+            capture_output=True,
+        )
+    _write(stdout, result.stdout)
+    _write(stderr, result.stderr)
+    return int(result.returncode)
+
+
+def _command_ls(args: argparse.Namespace, stdout, stderr) -> int:
+    with Host(args.uri, **_credentials(args)) as host:
+        for child in host.path(args.path).iterdir():
+            _write(stdout, f"{child.name}\n")
+    return 0
+
+
+def _command_cat(args: argparse.Namespace, stdout, stderr) -> int:
+    with Host(args.uri, **_credentials(args)) as host:
+        _write(stdout, host.path(args.path).read_bytes())
+    return 0
+
+
+def _command_cp(args: argparse.Namespace, stdout, stderr) -> int:
+    with contextlib.ExitStack() as stack:
+        credentials = _credentials(args)
+        source = _path_operand(stack, args.source, credentials)
+        target = _path_operand(stack, args.target, credentials)
+        # Python 3.14 added stdlib pathlib.Path.copy(), which currently wins
+        # LocalPath's mixed MRO. Route explicitly through pathlib_next so local
+        # and remote operands retain one copy contract on every supported floor.
+        NextPath.copy(
+            source,
+            target,
+            overwrite=args.overwrite,
+            recursive=args.recursive,
+        )
+    return 0
+
+
+def _command_info(args: argparse.Namespace, stdout, stderr) -> int:
+    with Host(args.uri, **_credentials(args)) as host:
+        info = host.info()
+    value = dataclasses.asdict(info) if dataclasses.is_dataclass(info) else vars(info)
+    _write(stdout, json.dumps(value, sort_keys=True) + "\n")
+    return 0
+
+
+def _command_shell(args: argparse.Namespace, stdout, stderr) -> int:
+    with Host(args.uri, **_credentials(args)) as host:
+        session = host.shell.session(terminal=True)
+        stopped = threading.Event()
+
+        def pump() -> None:
+            try:
+                while not stopped.is_set():
+                    data = session.read(65536)
+                    if not data:
+                        return
+                    _write(stdout, data)
+            except (OSError, ValueError):
+                if not stopped.is_set():
+                    raise
+
+        reader = threading.Thread(target=pump, name="hostctl-shell-output", daemon=True)
+        reader.start()
+        try:
+            for line in sys.stdin:
+                session.send(line.rstrip("\r\n"))
+        except KeyboardInterrupt:
+            return 130
+        finally:
+            try:
+                session.send_eof()
+            except NotImplementedError:
+                pass
+            stopped.set()
+            session.close()
+            reader.join(timeout=1)
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hostctl")
+    subcommands = parser.add_subparsers(dest="subcommand", required=True)
+
+    def host_command(name: str, handler):
+        command = subcommands.add_parser(name)
+        command.add_argument("--ask-password", action="store_true")
+        command.add_argument("uri")
+        command.set_defaults(handler=handler)
+        return command
+
+    run = host_command("run", _command_run)
+    run.add_argument("command", nargs=argparse.REMAINDER)
+
+    ls = host_command("ls", _command_ls)
+    ls.add_argument("path")
+
+    cat = host_command("cat", _command_cat)
+    cat.add_argument("path")
+
+    info = host_command("info", _command_info)
+
+    shell = host_command("shell", _command_shell)
+
+    cp = subcommands.add_parser("cp")
+    cp.add_argument("--ask-password", action="store_true")
+    cp.add_argument("--overwrite", action="store_true")
+    cp.add_argument("--recursive", action="store_true")
+    cp.add_argument("source")
+    cp.add_argument("target")
+    cp.set_defaults(handler=_command_cp)
+    return parser
+
+
+def main(
+    argv: typing.Optional[typing.Sequence[str]] = None,
+    *,
+    stdout: typing.Optional[_OutputStream] = None,
+    stderr: typing.Optional[_OutputStream] = None,
+) -> int:
+    """Run the CLI and return its process exit status."""
+    stdout = sys.stdout if stdout is None else stdout
+    stderr = sys.stderr if stderr is None else stderr
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.handler(args, stdout, stderr))
+    except subprocess.TimeoutExpired as exc:
+        _write(stderr, f"hostctl: timed out: {exc}\n")
+        return 125
+    except PermissionError as exc:
+        _write(stderr, f"hostctl: permission denied: {exc}\n")
+        return 126
+    except FileNotFoundError as exc:
+        _write(stderr, f"hostctl: not found: {exc}\n")
+        return 127
+    except (ConnectionError, OSError, ValueError, NotImplementedError) as exc:
+        _write(stderr, f"hostctl: {exc}\n")
+        return 125
+
+
+__all__ = ["main"]

hostctl/executor/__init__.py

@@ -0,0 +1,82 @@
+"""Public executor contracts."""
+
+from ._common import (
+    CaptureOutput as CaptureOutput,
+    CommandArgument as CommandArgument,
+    Environment as Environment,
+    ExecutionOptions as ExecutionOptions,
+    Executor as Executor,
+    ExecutorCapability as ExecutorCapability,
+    ExecutorCommand as ExecutorCommand,
+    FileHandle as FileHandle,
+    Input as Input,
+    PathLike as PathLike,
+    normalize_environment as normalize_environment,
+    capture_streams as capture_streams,
+    reject_stdin_conflict as reject_stdin_conflict,
+)
+from .container import (
+    ContainerExecutor as ContainerExecutor,
+    ContainerLike as ContainerLike,
+    normalize_container_error as normalize_container_error,
+)
+from .ssh import SshConnection as SshConnection, SshExecutor as SshExecutor
+from .local import LocalExecutor as LocalExecutor
+from .serial import (
+    SerialExecutor as SerialExecutor,
+    SerialFactory as SerialFactory,
+    SerialLike as SerialLike,
+    SerialSettings as SerialSettings,
+    SerialTransport as SerialTransport,
+    normalize_serial_error as normalize_serial_error,
+)
+from .qemu import (
+    GuestAgentProtocolError as GuestAgentProtocolError,
+    QemuExecutor as QemuExecutor,
+)
+from .winrm import (
+    NativeWinRMSession as NativeWinRMSession,
+    WinRMExecutor as WinRMExecutor,
+    WinRMSession as WinRMSession,
+)
+from .psrp import (
+    PsrpExecutor as PsrpExecutor,
+    pypsrp_available as pypsrp_available,
+    require_pypsrp as require_pypsrp,
+)
+
+__all__ = [
+    "CaptureOutput",
+    "ContainerExecutor",
+    "ContainerLike",
+    "CommandArgument",
+    "Environment",
+    "ExecutionOptions",
+    "Executor",
+    "ExecutorCapability",
+    "ExecutorCommand",
+    "FileHandle",
+    "Input",
+    "LocalExecutor",
+    "PathLike",
+    "QemuExecutor",
+    "GuestAgentProtocolError",
+    "NativeWinRMSession",
+    "normalize_container_error",
+    "normalize_environment",
+    "capture_streams",
+    "reject_stdin_conflict",
+    "normalize_serial_error",
+    "SerialExecutor",
+    "SerialFactory",
+    "SerialLike",
+    "SerialSettings",
+    "SerialTransport",
+    "SshConnection",
+    "SshExecutor",
+    "WinRMExecutor",
+    "WinRMSession",
+    "PsrpExecutor",
+    "pypsrp_available",
+    "require_pypsrp",
+]