hostctl 0.1.0__py3-none-any.whl

hostctl/shell/cmd.py

@@ -0,0 +1,167 @@
+"""Windows CMD/BAT shell flavour."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import typing
+from pathlib import PureWindowsPath
+
+from ..executor import Environment, PathLike
+from ._common import ShellCommand, ShellFlavour, ShellOperator, ShellToken
+
+
+def _argument(value: object) -> str:
+    """Quote one argv value for cmd.exe and a C-runtime child program."""
+    if isinstance(value, os.PathLike):
+        value = os.fspath(value)
+    elif isinstance(value, bytes):
+        value = value.decode("utf-8", "surrogateescape")
+    value = str(value)
+    if value and not any(char.isspace() or char in '&|<>()@^"%!' for char in value):
+        return value
+    value = value.replace("^", "^^").replace("%", "^%").replace("!", "^!")
+    for character in "&|<>()":
+        value = value.replace(character, f"^{character}")
+    escaped = []
+    backslashes = 0
+    for char in value:
+        if char == "\\":
+            backslashes += 1
+        elif char == '"':
+            # The caret preserves the quote through cmd.exe; the extra
+            # backslash makes the child C argv parser retain it as data.
+            escaped.append("\\" * (backslashes * 2 + 1) + '^"')
+            backslashes = 0
+        else:
+            escaped.append("\\" * backslashes + char)
+            backslashes = 0
+    escaped.append("\\" * (backslashes * 2))
+    # The delimiters must survive cmd.exe so the child C runtime, rather
+    # than cmd itself, consumes them as argv quoting.
+    return '^"' + "".join(escaped) + '^"'
+
+
+def _builtin_argument(value: object) -> str:
+    """Escape data for a cmd.exe builtin, which has no C argv parser."""
+    if isinstance(value, os.PathLike):
+        value = os.fspath(value)
+    elif isinstance(value, bytes):
+        value = value.decode("utf-8", "surrogateescape")
+    text = str(value).replace("^", "^^")
+    for character in '&|<>()@^"%!':
+        if character == "^":
+            continue
+        text = text.replace(character, f"^{character}")
+    return text
+
+
+class CmdShellFlavour(ShellFlavour):
+    """Windows ``cmd.exe`` and BAT-compatible command construction."""
+
+    name = "cmd"
+    default_executable = "cmd.exe"
+    command_separator = "&"
+    path_flavor = PureWindowsPath
+    info_script = (
+        "echo hostname=%COMPUTERNAME%&"
+        "echo os_family=windows&"
+        "echo os_name=%OS%&"
+        "echo architecture=%PROCESSOR_ARCHITECTURE%"
+    )
+    builtins = frozenset(
+        (
+            "assoc",
+            "break",
+            "call",
+            "cd",
+            "chdir",
+            "cls",
+            "color",
+            "copy",
+            "date",
+            "del",
+            "dir",
+            "echo",
+            "endlocal",
+            "erase",
+            "exit",
+            "md",
+            "mkdir",
+            "mklink",
+            "move",
+            "path",
+            "pause",
+            "popd",
+            "prompt",
+            "pushd",
+            "rd",
+            "ren",
+            "rename",
+            "rmdir",
+            "set",
+            "setlocal",
+            "shift",
+            "start",
+            "time",
+            "title",
+            "type",
+            "ver",
+            "verify",
+            "vol",
+        )
+    )
+
+    def quote(self, value: object) -> str:
+        return _argument(self._text(value))
+
+    def structured_command(self, values: typing.Iterable[object]) -> str:
+        values = tuple(values)
+        if values and self._text(values[0]).casefold() in self.builtins:
+            return " ".join(_builtin_argument(self._text(value)) for value in values)
+        return super().structured_command(values)
+
+    def operator(self, value: ShellOperator) -> str:
+        return {
+            ShellOperator.PIPE: "|",
+            ShellOperator.AND: "&&",
+            ShellOperator.OR: "||",
+            ShellOperator.REDIRECT: ">",
+            ShellOperator.APPEND: ">>",
+            ShellOperator.SEQUENCE: self.command_separator,
+        }[value]
+
+    def environment_assignment(self, key: str, value: object) -> str:
+        value = self._text(value).replace("^", "^^")
+        value = value.replace("%", "^%").replace("!", "^!").replace('"', '^"')
+        return f'set "{key}={value}"'
+
+    def change_directory(self, cwd: PathLike) -> str:
+        return f"cd /d {_builtin_argument(self._text(cwd))}"
+
+    def command(
+        self,
+        cmds: typing.Iterable[ShellToken],
+        *,
+        executable: typing.Optional[str] = None,
+        cwd: typing.Optional[PathLike] = None,
+        env: typing.Optional[Environment] = None,
+    ) -> ShellCommand:
+        script = self.script(cmds, cwd=cwd, env=env)
+        executable_text = _argument(executable or self.default_executable)
+        return ShellCommand(
+            f'{executable_text} /d /v:off /s /c "{script}"',
+            None,
+        )
+
+    def invocation(
+        self, script: str, *, executable: typing.Optional[str] = None
+    ) -> typing.Sequence[str]:
+        return (
+            executable or self.default_executable,
+            "/d",
+            "/v:off",
+            "/s",
+            "/c",
+            script,
+        )

hostctl/shell/fish.py

@@ -0,0 +1,63 @@
+"""Fish shell flavour."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import typing
+from pathlib import Path, PurePath, PurePosixPath
+
+from ..executor import Environment, PathLike
+from ._common import ShellCommand, ShellFlavour, ShellOperator, ShellToken
+
+
+class FishShellFlavour(ShellFlavour):
+    name = "fish"
+    default_executable = "/usr/bin/fish"
+    command_separator = ";"
+    info_script = (
+        "echo hostname=(hostname);"
+        "echo os_family=(uname -s);"
+        "echo architecture=(uname -m)"
+    )
+    path_flavor = PurePosixPath
+
+    def quote(self, value: object) -> str:
+        if isinstance(value, (PurePath, Path)):
+            value = value.as_posix()
+        return shlex.quote(self._text(value))
+
+    def operator(self, value: ShellOperator) -> str:
+        return {
+            ShellOperator.PIPE: "|",
+            ShellOperator.AND: "; and ",
+            ShellOperator.OR: "; or ",
+            ShellOperator.REDIRECT: ">",
+            ShellOperator.APPEND: ">>",
+            ShellOperator.SEQUENCE: self.command_separator,
+        }[value]
+
+    def environment_assignment(self, key: str, value: object) -> str:
+        return f"set -gx {key} {self.quote(value)}"
+
+    def change_directory(self, cwd: PathLike) -> str:
+        return f"cd -- {self.quote(PurePosixPath(cwd).as_posix())}"
+
+    def command(
+        self,
+        cmds: typing.Iterable[ShellToken],
+        *,
+        executable: typing.Optional[str] = None,
+        cwd: typing.Optional[PathLike] = None,
+        env: typing.Optional[Environment] = None,
+    ) -> ShellCommand:
+        command = self.invocation(
+            self.script(cmds, cwd=cwd, env=env),
+            executable=executable,
+        )
+        return ShellCommand(shlex.join(command), None)
+
+    def invocation(
+        self, script: str, *, executable: typing.Optional[str] = None
+    ) -> typing.Sequence[str]:
+        return (executable or self.default_executable, "-c", script)

hostctl/shell/posix.py

@@ -0,0 +1,83 @@
+"""POSIX shell flavour."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import typing
+from pathlib import Path, PurePath, PurePosixPath
+
+from ..executor import Environment, PathLike
+from ._common import ShellCommand, ShellFlavour, ShellOperator, ShellToken
+
+
+class PosixShellFlavour(ShellFlavour):
+    name = "posix"
+    default_executable = "/bin/sh"
+    command_separator = ";"
+    info_script = (
+        "printf 'hostname=%s\\n' \"$(hostname 2>/dev/null)\";"
+        "printf 'os_family=%s\\n' \"$(uname -s 2>/dev/null)\";"
+        "if [ -r /etc/os-release ]; then . /etc/os-release;"
+        "printf 'os_name=%s\\n' \"$ID\";"
+        "printf 'os_version=%s\\n' \"$VERSION_ID\"; fi;"
+        "printf 'architecture=%s\\n' \"$(uname -m 2>/dev/null)\""
+    )
+    path_flavor = PurePosixPath
+
+    def quote(self, value: object) -> str:
+        if isinstance(value, (PurePath, Path)):
+            value = value.as_posix()
+        return shlex.quote(self._text(value))
+
+    def operator(self, value: ShellOperator) -> str:
+        return {
+            ShellOperator.PIPE: "|",
+            ShellOperator.AND: "&&",
+            ShellOperator.OR: "||",
+            ShellOperator.REDIRECT: ">",
+            ShellOperator.APPEND: ">>",
+            ShellOperator.SEQUENCE: self.command_separator,
+        }[value]
+
+    def environment_assignment(self, key: str, value: object) -> str:
+        return f"export {key}={self.quote(value)}"
+
+    def change_directory(self, cwd: PathLike) -> str:
+        return f"cd -- {self.quote(PurePosixPath(cwd).as_posix())}"
+
+    def command(
+        self,
+        cmds: typing.Iterable[ShellToken],
+        *,
+        executable: typing.Optional[str] = None,
+        cwd: typing.Optional[PathLike] = None,
+        env: typing.Optional[Environment] = None,
+    ) -> ShellCommand:
+        command = self.invocation(
+            self.script(cmds, env=env),
+            executable=executable,
+        )
+        remote_command = shlex.join(command)
+        if cwd:
+            remote_command = f"{self.change_directory(cwd)}{self.operator(ShellOperator.AND)}{remote_command}"
+        return ShellCommand(remote_command, None)
+
+    def invocation(
+        self, script: str, *, executable: typing.Optional[str] = None
+    ) -> typing.Sequence[str]:
+        return (executable or self.default_executable, "-c", script)
+
+
+class BashShellFlavour(PosixShellFlavour):
+    """Bash using the portable POSIX command-construction baseline."""
+
+    name = "bash"
+    default_executable = "/bin/bash"
+
+
+class ZshShellFlavour(PosixShellFlavour):
+    """Zsh using the portable POSIX command-construction baseline."""
+
+    name = "zsh"
+    default_executable = "/bin/zsh"

hostctl/shell/powershell.py

@@ -0,0 +1,120 @@
+"""Windows PowerShell shell flavour."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import typing
+from pathlib import PureWindowsPath
+
+from ..executor import Environment, PathLike
+from ._common import ShellCommand, ShellFlavour, ShellOperator, ShellToken
+
+
+def _literal(value: object) -> str:
+    return (
+        "'"
+        + str(value)
+        .replace("'", "''")
+        .replace("‘", "‘‘")
+        .replace("’", "’’")
+        .replace("‚", "‚‚")
+        .replace("‛", "‛‛")
+        + "'"
+    )
+
+
+class PowerShellFlavour(ShellFlavour):
+    name = "powershell"
+    default_executable = "powershell.exe"
+    command_separator = ";"
+    context_order = ("cwd", "env", "command")
+    execution_epilogue = "; exit $LASTEXITCODE"
+    structured_command_prefix = "& "
+    path_flavor = PureWindowsPath
+    info_script = (
+        'Write-Output ("hostname=" + [Environment]::MachineName);'
+        'Write-Output ("os_family=" + [Environment]::OSVersion.Platform);'
+        'Write-Output ("os_name=" + '
+        "[System.Runtime.InteropServices.RuntimeInformation]::OSDescription);"
+        'Write-Output ("os_version=" + [Environment]::OSVersion.Version);'
+        'Write-Output ("architecture=" + '
+        "[System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture)"
+    )
+
+    def __init__(
+        self,
+        major_version: int = 5,
+        executable: typing.Optional[str] = None,
+    ) -> None:
+        if major_version == 6 or major_version < 5:
+            raise ValueError("supported PowerShell versions are 5 and 7+")
+        self.major_version = major_version
+        if executable is not None:
+            self.default_executable = executable
+        elif major_version >= 7:
+            self.default_executable = "pwsh"
+            self.name = "pwsh"
+
+    def quote(self, value: object) -> str:
+        return _literal(self._text(value))
+
+    def operator(self, value: ShellOperator) -> str:
+        if self.major_version >= 7 and value in (
+            ShellOperator.AND,
+            ShellOperator.OR,
+        ):
+            return {
+                ShellOperator.AND: " && ",
+                ShellOperator.OR: " || ",
+            }[value]
+        try:
+            return {
+                ShellOperator.PIPE: " | ",
+                ShellOperator.REDIRECT: " > ",
+                ShellOperator.APPEND: " >> ",
+                ShellOperator.SEQUENCE: self.command_separator,
+            }[value]
+        except KeyError as exc:
+            raise NotImplementedError(
+                f"{value.name} is not portable to Windows PowerShell"
+            ) from exc
+
+    def environment_assignment(self, key: str, value: object) -> str:
+        return f"$env:{key}={_literal(self._text(value))}"
+
+    def change_directory(self, cwd: PathLike) -> str:
+        return (
+            f"Set-Location -LiteralPath {_literal(self._text(cwd))} -ErrorAction Stop"
+        )
+
+    def join_cwd(self, changed: str, command: str) -> str:
+        # PowerShell 5 has no &&.  ErrorAction Stop makes a failed Set-Location
+        # terminate the script before the payload is evaluated.
+        return f"{changed};{command}"
+
+    def command(
+        self,
+        cmds: typing.Iterable[ShellToken],
+        *,
+        executable: typing.Optional[str] = None,
+        cwd: typing.Optional[PathLike] = None,
+        env: typing.Optional[Environment] = None,
+    ) -> ShellCommand:
+        script = self.script(cmds, cwd=cwd, env=env)
+        command = self.invocation(
+            script,
+            executable=executable,
+        )
+        return ShellCommand(subprocess.list2cmdline(command), None)
+
+    def invocation(
+        self, script: str, *, executable: typing.Optional[str] = None
+    ) -> typing.Sequence[str]:
+        return (
+            executable or self.default_executable,
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            script,
+        )

hostctl/sync.py

@@ -0,0 +1,245 @@
+"""Checksum and progress helpers for :mod:`pathlib_next` copy and sync."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import subprocess
+import typing
+
+from pathlib_next.utils.sync import PathAndStat
+
+if typing.TYPE_CHECKING:
+    from .host import Host
+
+
+_REMOTE_ALGORITHMS = frozenset(("md5", "sha1", "sha256", "sha384", "sha512"))
+_HEX_DIGEST = re.compile(r"^[0-9a-fA-F]+$")
+
+#: Remote hashing is an optimization, never a requirement.  A host which owns
+#: the path but cannot hash it in place -- no such tool, a refused command, an
+#: unparseable answer -- must degrade to reading the content, not fail the
+#: whole sync.  Missing files and other path-level errors are deliberately not
+#: absorbed here: those are real answers about the path and must propagate.
+_UNAVAILABLE_REMOTE_TOOL = (
+    ValueError,
+    OSError,
+    NotImplementedError,
+    subprocess.SubprocessError,
+)
+
+
+def stat_checksum(entry: PathAndStat) -> tuple[int, float]:
+    """Return the cached size and modification time without reading content.
+
+    This is rsync's quick check: no content is read and no command is run.
+    Two caveats decide whether it suits a given sync.
+
+    It can *miss* a change which preserves both size and modification time.
+
+    It can also *report* a change which is not one, on interpreters where
+    ``pathlib_next.Path.copy()`` preserves ``st_mode`` but not timestamps: a
+    file this helper copies lands with a fresh modification time and compares
+    unequal on the next run, so the sync never settles.  Python 3.14 added a
+    stdlib ``Path.copy()`` which does preserve timestamps, and a local path
+    resolves to it there, so the same sync converges.  Because that difference
+    is version- and backend-dependent, use this helper where source
+    modification times are meaningful on both sides -- a tree replicated by
+    something which preserves them -- and prefer :func:`host_checksum` when
+    hostctl's own copies must converge to a no-op on every supported
+    interpreter.
+    """
+    if entry.stat is None:
+        raise FileNotFoundError(entry.path)
+    return entry.stat.st_size, entry.stat.st_mtime
+
+
+def host_checksum(
+    *hosts: Host,
+    algorithm: str = "md5",
+    chunk_size: int = 1024 * 1024,
+) -> typing.Callable[[PathAndStat], str]:
+    """Build a ``PathSyncer`` checksum using execution beside owned paths.
+
+    More than one host may be supplied for a cross-host sync. Paths which do
+    not belong to any supplied host are hashed through their binary ``open()``
+    contract, preserving interoperability with arbitrary ``pathlib_next``
+    implementations.
+    """
+    normalized = algorithm.casefold().replace("-", "")
+    if normalized not in _REMOTE_ALGORITHMS:
+        raise ValueError(
+            f"unsupported remote checksum algorithm: {algorithm!r}; "
+            f"choose one of {', '.join(sorted(_REMOTE_ALGORITHMS))}"
+        )
+    if not hosts:
+        raise ValueError("host_checksum requires at least one host")
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be positive")
+
+    owners = tuple((host, _host_path_token(host)) for host in hosts)
+
+    def checksum(entry: PathAndStat) -> str:
+        for host, owner_token in owners:
+            if _host_owns_path(host, entry.path, owner_token):
+                try:
+                    return _remote_checksum(host, entry.path, normalized)
+                except _UNAVAILABLE_REMOTE_TOOL:
+                    # The host owns the path but cannot hash it in place: the
+                    # tool is missing, refused, or answered unintelligibly.
+                    # Reading the content is slower but still correct, so a
+                    # sync degrades rather than aborting.
+                    break
+        return _stream_checksum(entry.path, normalized, chunk_size)
+
+    return checksum
+
+
+class ProgressReader:
+    """Wrap a binary reader and report ``(bytes_read, total_bytes)``."""
+
+    def __init__(
+        self,
+        reader: typing.BinaryIO,
+        callback: typing.Callable[[int, typing.Optional[int]], None],
+        *,
+        total: typing.Optional[int] = None,
+    ) -> None:
+        if not callable(callback):
+            raise TypeError("callback must be callable")
+        self.reader = reader
+        self.callback = callback
+        self.total = total
+        self.bytes_read = 0
+
+    def read(self, size: int = -1) -> bytes:
+        data = self.reader.read(size)
+        self.bytes_read += len(data)
+        self.callback(self.bytes_read, self.total)
+        return data
+
+    def readable(self) -> bool:
+        return True
+
+    @property
+    def closed(self) -> bool:
+        return self.reader.closed
+
+    def close(self) -> None:
+        self.reader.close()
+
+    def __enter__(self) -> ProgressReader:
+        self.reader.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> typing.Optional[bool]:
+        return self.reader.__exit__(exc_type, exc_value, traceback)
+
+    def __getattr__(self, name: str) -> object:
+        return getattr(self.reader, name)
+
+
+def _remote_checksum(host: Host, path: object, algorithm: str) -> str:
+    flavour = host.shell_flavour.name
+    if flavour in ("powershell", "pwsh"):
+        quote = host.shell_flavour.quote
+        script = (
+            f"Get-FileHash -LiteralPath {quote(os.fspath(path))} "
+            f"-Algorithm {quote(algorithm.upper())} "
+            "| Select-Object -ExpandProperty Hash"
+        )
+        result = host.run(script, encoding="utf-8")
+        try:
+            return _parse_digest(result.stdout, algorithm)
+        except ValueError:
+            result = host.run(
+                ("certutil.exe", "-hashfile", os.fspath(path), algorithm.upper()),
+                encoding="utf-8",
+            )
+    elif flavour == "cmd":
+        result = host.run(
+            ("certutil", "-hashfile", os.fspath(path), algorithm.upper()),
+            encoding="utf-8",
+        )
+    else:
+        result = host.run(
+            (f"{algorithm}sum", os.fspath(path)),
+            encoding="utf-8",
+        )
+    return _parse_digest(result.stdout, algorithm)
+
+
+def _parse_digest(output: typing.Union[bytes, str, None], algorithm: str) -> str:
+    if isinstance(output, bytes):
+        output = output.decode("utf-8", "replace")
+    expected = hashlib.new(algorithm).digest_size * 2
+    for line in (output or "").splitlines():
+        fields = line.split()
+        if not fields:
+            continue
+        # Two shapes to accept: certutil spreads the digest across
+        # space-separated byte pairs, so the whole line joins into one
+        # candidate; md5sum emits "<digest>  <path>", so the first field is
+        # the candidate. A path may itself look like a digest, hence the
+        # first field rather than any field.
+        for candidate in ("".join(fields), fields[0]):
+            if len(candidate) == expected and _HEX_DIGEST.fullmatch(candidate):
+                return candidate.casefold()
+    raise ValueError(f"unable to parse {algorithm} checksum from host output")
+
+
+def _stream_checksum(path: object, algorithm: str, chunk_size: int) -> str:
+    digest = hashlib.new(algorithm)
+    with path.open("rb") as stream:
+        while True:
+            chunk = stream.read(chunk_size)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _host_path_token(host: Host) -> typing.Optional[tuple[object, ...]]:
+    """Return the backend identity for a host without using path prefixes."""
+    selector = getattr(host, "_path_selector", None)
+    if selector is not None:
+        return None
+    try:
+        sample = host.path()
+    except (NotImplementedError, RuntimeError, OSError):
+        return None
+    return _path_token(sample)
+
+
+def _host_owns_path(
+    host: Host,
+    path: object,
+    owner_token: typing.Optional[tuple[object, ...]],
+) -> bool:
+    provider = getattr(path, "provider", None)
+    selector = getattr(host, "_path_selector", None)
+    if provider is not None and selector is not None:
+        return any(
+            provider is candidate for candidate in getattr(selector, "providers", ())
+        )
+    return owner_token is not None and _path_token(path) == owner_token
+
+
+def _path_token(path: object) -> typing.Optional[tuple[object, ...]]:
+    provider = getattr(path, "provider", None)
+    if provider is not None:
+        return ("provider", id(provider))
+
+    backend_path = getattr(path, "_backend_path", None)
+    if backend_path is not None and backend_path is not path:
+        return _path_token(backend_path)
+
+    backend = getattr(path, "backend", None)
+    if backend is None:
+        return ("local", type(path))
+
+    container = getattr(backend, "container", None)
+    if container is not None:
+        return ("container", id(container))
+    return ("backend", id(backend))