hostctl 0.2.4__tar.gz → 0.2.5__tar.gz

{hostctl-0.2.4 → hostctl-0.2.5}/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.5] - 2026-08-05
+
+### Added
+
+- `write_output`, `normalize_input`, and `dispatch_output` are exported from
+  `hostctl.executor`, joining `capture_streams`. An executor implemented
+  outside hostctl previously had to import `hostctl.executor._common` to
+  reproduce hostctl's own stdout/stderr and stdin semantics.
+
+  Sharing these is a correctness requirement rather than a convenience: a
+  `SystemHost` can dispatch the same call through different providers on
+  different attempts, so providers that disagree about output handling return
+  results that differ by which transport won. `normalize_input` is the one
+  worth not reimplementing — a mismatch there does not raise, it deadlocks,
+  because bytes handed to a text-mode stdin kill `subprocess`'s writer thread
+  without closing the pipe, so the child never sees EOF and `timeout=` never
+  fires.
+
+  No behaviour change; these are the same objects `_common` defines.
+
+### Fixed
+
+- Four conformance tests covering timestamp handling were skipping for a
+  reason that was not true, so the contract they check went unverified. The
+  checks called `os.utime()` on paths belonging to fake *remote* providers,
+  which map into a private sandbox root and have no local existence; the
+  resulting `FileNotFoundError` was reported as "this provider cannot set
+  timestamps". Timestamps are now set through the sandbox that actually stores
+  the file. Test-only change.
+
 ## [0.2.4] - 2026-08-05
 
 ### Fixed
@@ -397,7 +427,8 @@ test suite on Python 3.9 through 3.14.
   assigned to it; a config-less host now builds its own family configuration
   instead.
 
-[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/jose-pr/hostctl/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/jose-pr/hostctl/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/jose-pr/hostctl/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/jose-pr/hostctl/compare/v0.2.1...v0.2.2

{hostctl-0.2.4 → hostctl-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hostctl
-Version: 0.2.4
+Version: 0.2.5
 Summary: Run commands and access files on a host, local or remote, protocol-agnostic
 Project-URL: Homepage, https://github.com/jose-pr/hostctl/
 Project-URL: Documentation, https://jose-pr.github.io/hostctl/

{hostctl-0.2.4 → hostctl-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.2.4"
+version = "0.2.5"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"

{hostctl-0.2.4 → hostctl-0.2.5}/src/hostctl/executor/__init__.py

@@ -13,7 +13,10 @@ from ._common import (
     PathLike as PathLike,
     normalize_environment as normalize_environment,
     capture_streams as capture_streams,
+    dispatch_output as dispatch_output,
+    normalize_input as normalize_input,
     reject_stdin_conflict as reject_stdin_conflict,
+    write_output as write_output,
 )
 from .container import (
     ContainerExecutor as ContainerExecutor,
@@ -65,7 +68,10 @@ __all__ = [
     "normalize_container_error",
     "normalize_environment",
     "capture_streams",
+    "dispatch_output",
+    "normalize_input",
     "reject_stdin_conflict",
+    "write_output",
     "normalize_serial_error",
     "SerialExecutor",
     "SerialFactory",

{hostctl-0.2.4 → hostctl-0.2.5}/src/hostctl/host/serial.py

@@ -18,8 +18,8 @@ from ..executor import (
     SerialLike,
     SerialSettings,
     capture_streams,
+    write_output,
 )
-from ..executor._common import write_output
 from ..process import Process, SerialConsoleProcess, terminal_options
 from ..serial import PromptConsoleProfile, RawConsoleProfile, SerialConsoleProtocol
 from ._common import (

{hostctl-0.2.4 → hostctl-0.2.5}/tests/conformance/providers.py

@@ -762,6 +762,64 @@ def _docker_live() -> tuple[object, Callable[[], None]]:
     return host, host.close
 
 
+def _sandbox_for(host, provider: Provider, path):
+    """Return the `_Sandbox` backing a fake provider's paths, or None.
+
+    The fakes present target-flavoured absolute paths (`/hostctl-conformance/
+    ...`, `C:\\hostctl-conformance\\...`) that have no local existence -- each
+    maps into a private temporary root.  Reaching that root is the only way to
+    drive a real filesystem call against a fake remote path.
+
+    Each fake reaches its sandbox by a different route (`_sftp_backend._client`
+    for SFTP, `_path_backend.runner` for WinRM, the transport itself for QGA),
+    so this walks object attributes breadth-first rather than encoding one
+    chain per transport -- a hardcoded chain silently returns None when a fake
+    is restructured, which reintroduces exactly the misreported skip this
+    helper exists to prevent.
+    """
+
+    if provider.live or provider.name == "local":
+        return None
+    roots = list(getattr(path, "_providers", ()) or ())
+    roots += [host]
+    seen: set = set()
+    queue = list(roots)
+    while queue:
+        current = queue.pop(0)
+        if current is None or id(current) in seen:
+            continue
+        seen.add(id(current))
+        sandbox = getattr(current, "sandbox", None)
+        if sandbox is not None and hasattr(sandbox, "local"):
+            return sandbox
+        for value in list(getattr(current, "__dict__", {}).values()):
+            if hasattr(value, "__dict__"):
+                queue.append(value)
+    return None
+
+
+def conformance_utime(host, provider: Provider, path, times) -> bool:
+    """Set `path`'s mtime through whatever really stores it.
+
+    Returns False only when the provider genuinely cannot set timestamps, so a
+    caller can skip for that reason alone.  `os.utime(str(path))` is NOT a
+    substitute: for every fake remote provider that call targets a local path
+    that does not exist, raising `FileNotFoundError` -- an `OSError` that reads
+    as "this transport has no timestamp support" while actually meaning the
+    test pointed at the wrong filesystem.
+    """
+
+    target = str(path)
+    sandbox = _sandbox_for(host, provider, path)
+    if sandbox is not None:
+        target = str(sandbox.local(target))
+    try:
+        os.utime(target, times)
+    except (OSError, NotImplementedError):
+        return False
+    return True
+
+
 @contextlib.contextmanager
 def provider_context(provider: Provider) -> Iterator[object]:
     try:

{hostctl-0.2.4 → hostctl-0.2.5}/tests/conformance/test_sync_contract.py

@@ -15,7 +15,12 @@ from pathlib_next.utils.sync import PathAndStat, PathSyncer, SyncEvent
 
 from hostctl.sync import host_checksum, stat_checksum
 
-from .providers import conformance_path, fake_providers, provider_context
+from .providers import (
+    conformance_path,
+    conformance_utime,
+    fake_providers,
+    provider_context,
+)
 
 _PATH_PROVIDERS = tuple(
     provider for provider in fake_providers() if "path" in provider.capabilities
@@ -144,6 +149,11 @@ def test_path_syncer_skips_files_whose_stat_already_matches(provider, tmp_path):
         # Build a target entry whose stat matches its source exactly.
         (source / "same.txt").write_bytes(b"identical")
         (target / "same.txt").write_bytes(b"identical")
+        # Two writes land at whatever mtime the clock gave them, so align the
+        # pair explicitly rather than skipping when they happen to differ.
+        pinned = stat_checksum(PathAndStat(source / "same.txt"))[1]
+        for side in (source, target):
+            conformance_utime(host, provider, side / "same.txt", (pinned, pinned))
         matching = stat_checksum(PathAndStat(source / "same.txt")) == stat_checksum(
             PathAndStat(target / "same.txt")
         )
@@ -174,8 +184,6 @@ def test_stat_checksum_does_not_converge_after_a_copy(provider, tmp_path):
     convergence and "a second pass would copy again" are exact opposites.
     """
 
-    import os
-
     with provider_context(provider) as host:
         source = conformance_path(host, provider, tmp_path, "converge-source.bin")
         target = conformance_path(host, provider, tmp_path, "converge-target.bin")
@@ -184,9 +192,7 @@ def test_stat_checksum_does_not_converge_after_a_copy(provider, tmp_path):
         # Age the source well beyond any filesystem timestamp granularity, so
         # the comparison below cannot pass by coincidence of a coarse clock.
         aged = stat_checksum(PathAndStat(source))[1] - 3600
-        try:
-            os.utime(str(source), (aged, aged))
-        except (OSError, NotImplementedError):
+        if not conformance_utime(host, provider, source, (aged, aged)):
             pytest.skip(f"{provider.name} cannot set timestamps for this check")
         if stat_checksum(PathAndStat(source))[1] != aged:
             pytest.skip(f"{provider.name} did not honor the backdated timestamp")

hostctl-0.2.5/tests/test_executor_exports.py

@@ -0,0 +1,85 @@
+"""The stream helpers a third-party executor needs are public.
+
+`hostctl/AGENTS.md` states that only names in `__all__` are stable and anything
+else "may change without notice".  An executor implemented outside hostctl --
+pytruenas 0.4.0's web shell is the real case -- must reproduce hostctl's own
+stdout/stderr and stdin semantics exactly, because a `SystemHost` can dispatch
+the same call through different providers on different attempts.  Providers
+that disagree about output handling produce results that differ by which
+transport happened to win.
+
+That argument is already written into `normalize_input`'s docstring as the
+reason every executor must share it.  These tests pin the corollary: sharing is
+only possible if the helpers are reachable without importing a private module.
+"""
+
+from __future__ import annotations
+
+import io
+
+import hostctl.executor as executor
+
+
+def test_stream_helpers_are_exported():
+    """All four helpers are public, not just `capture_streams`.
+
+    Regression test for a real gap: `capture_streams` was exported while
+    `write_output`, `normalize_input`, and `dispatch_output` -- its neighbours
+    in `_common.py`, used on the same call path -- were not, so consumers
+    imported them from `hostctl.executor._common`.
+    """
+
+    for name in (
+        "capture_streams",
+        "dispatch_output",
+        "normalize_input",
+        "write_output",
+    ):
+        assert name in executor.__all__, f"{name} is missing from __all__"
+        assert callable(getattr(executor, name)), f"{name} is not importable"
+
+
+def test_exported_helpers_are_the_implementations_themselves():
+    """The public names must not be re-wrapped copies of the private ones.
+
+    A shim would drift from the original, which is the outcome the shared
+    helpers exist to prevent.
+    """
+
+    from hostctl.executor import _common
+
+    for name in (
+        "capture_streams",
+        "dispatch_output",
+        "normalize_input",
+        "write_output",
+    ):
+        assert getattr(executor, name) is getattr(_common, name)
+
+
+def test_write_output_survives_a_stream_mode_mismatch():
+    """Pin the bytes<->str fallback an external executor would have to clone.
+
+    This is why reimplementing `write_output` is a trap rather than a chore:
+    the fallback is invisible until a transport hands text to a binary sink.
+    """
+
+    binary = io.BytesIO()
+    executor.write_output(binary, "text into a binary sink", encoding=None, errors=None)
+    assert binary.getvalue() == b"text into a binary sink"
+
+    text = io.StringIO()
+    executor.write_output(text, b"bytes into a text sink", encoding=None, errors=None)
+    assert text.getvalue() == "bytes into a text sink"
+
+
+def test_normalize_input_matches_the_stream_mode():
+    """Pin the conversion whose absence deadlocks `subprocess`.
+
+    Handing `bytes` to a text-mode stdin kills the writer thread without
+    closing the pipe, so the child never sees EOF and `timeout=` never fires.
+    """
+
+    assert executor.normalize_input(b"payload", text_mode=True) == "payload"
+    assert executor.normalize_input("payload", text_mode=False) == b"payload"
+    assert executor.normalize_input(None, text_mode=True) is None