hostctl 0.2.2__tar.gz → 0.2.4__tar.gz

{hostctl-0.2.2 → hostctl-0.2.4}/.gitignore

@@ -17,3 +17,6 @@ site/
 .agents
 CLAUDE*
 .claude
+.*
+!.gitignore
+

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

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-08-05
+
+### Fixed
+
+- Directory listings no longer discard the backend's own `_scandir()`.
+  `walk()` and `glob()` went through hostctl's `_scandir()`, which was a
+  verbatim copy of `pathlib_next`'s generic fallback and called `iterdir()` —
+  so a scheme whose listing already carries metadata never got to use it.
+  `SftpPath._scandir()` reads every child's attributes in a single
+  `listdir_attr` round trip; before this fix a remote `walk()` paid a listing
+  plus one `stat()` per entry. `_scandir()` is now the routed primitive and
+  `iterdir()` derives from it, matching the direction upstream intends.
+
+- `copy()` and `move()` on a composite path now use the backend's own
+  implementation when the destination resolves to a path that backend
+  understands. They previously called `Path.copy(self, ...)` unconditionally,
+  which bypassed every backend override — `SftpPath.copy()` fans out over
+  asyncssh workers and `SftpPath.rm()`/`checksum()` run server-side, so the
+  results stayed correct while the transport-native path was silently
+  discarded. A genuine cross-backend transfer (a destination on another
+  provider) still uses the generic implementation, which is what it is for.
+
+### Changed
+
+- Composite paths forward the method that was called to the selected backend
+  instead of re-declaring a copy of `pathlib_next.Path`'s surface. Operations
+  hostctl never declares — `touch()`, `rm()`, `lstat()`, `is_symlink()`,
+  `chown()`, `checksum()` — now work through `host.path()`, and an operation
+  added upstream is reachable without a new method here. `chown()`, added in
+  `pathlib_next` 0.9.1, was unreachable before this.
+
+  `_CompositePathMixin` drops from 47 to 36 methods. Operations with real
+  composite behavior stay hand-written, each for a reason: `iterdir`/`_scandir`
+  (rebuild children as composite paths), `rename` (cross-provider guard),
+  `readlink` (rebuilds its result), `copy`/`move` (backend when the destination
+  resolves on this provider, generic for a true cross-backend transfer), and
+  `open` (the capability gate depends on the mode).
+
+  The pure-path derivations (`parent`, `parents`, `joinpath`, `/`,
+  `with_name`/`with_stem`/`with_suffix`, `relative_to`, `with_segments`) also
+  stay: `pathlib.PurePath` builds those through `object.__new__`, bypassing the
+  composite constructor, so they re-attach routing state that inheritance drops
+  rather than duplicating anything.
+
+- Provider fallback now also triggers on `NotImplementedError`, but only for
+  operations that cannot mutate before raising (reads, `stat`, `chown`,
+  `chmod`). Writes and composed wrappers still propagate it: a wrapper built
+  from several primitives may have already changed something when a later
+  primitive raises — `symlink_to(force=True)` unlinks before calling
+  `_symlink_to()`, so a backend lacking that primitive deletes the entry and
+  only then fails. Retrying that against another provider would repeat the
+  work with the original already gone.
+
+## [0.2.3] - 2026-08-04
+
+### Fixed
+
+- Composite paths no longer drop backend-specific keyword arguments.
+  `CompositePosixPath.symlink_to()` accepted only the stdlib signature and
+  forwarded nothing else, so a backend's documented extension was unreachable
+  through the very abstraction meant to expose it — a path obtained from
+  `host.path()` raised `TypeError: unexpected keyword argument 'force'` even
+  when the selected backend implemented `force=`.
+
+  Forwarding is **signature-aware** rather than blind: the selected backend's
+  method is inspected, and only keywords it declares are passed through.
+  Anything else still raises `TypeError` at the composite boundary, naming
+  the backend class and the rejected keyword. Blind passthrough would have
+  turned a clear error at the abstraction boundary into a confusing one from
+  inside a transport, and the existing contract — a backend lacking a
+  capability raises `NotImplementedError`, never a silent no-op — is
+  unchanged. A method whose signature cannot be introspected (a C function,
+  a `functools.partial`) receives the keywords, since an error from it is no
+  worse than calling it directly.
+
+  Applied to `mkdir()`, `chmod()`, `unlink()`, and `rmdir()` alongside
+  `symlink_to()`, since the same normalization affected each of them.
+
+  This pairs with `pathlib_next`'s `symlink_to(force=)`, which that project
+  exposes as a generic `Path` extension over a `_symlink_to()` backend
+  primitive. No version floor change: hostctl's `pathlib_next>=0.8.6` floor
+  stays where it is, so `force=` is forwarded when the installed version
+  provides it and rejected at the boundary when it does not.
+
 ## [0.2.2] - 2026-07-29
 
 ### Changed
@@ -313,7 +397,9 @@ 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.2...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.4...HEAD
+[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
 [0.2.1]: https://github.com/jose-pr/hostctl/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/jose-pr/hostctl/compare/v0.1.2...v0.2.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hostctl
-Version: 0.2.2
+Version: 0.2.4
 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.2 → hostctl-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.2.2"
+version = "0.2.4"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"
@@ -37,7 +37,10 @@ classifiers = [
 # Both ranges span two minors deliberately: hostctl uses no API added in
 # pathlib_next 0.9 or netimps 0.2, so raising the floor would exclude working
 # installs for nothing. The ceilings stay at the next major-ish boundary
-# because both projects are pre-1.0, where a minor may break.
+# because both projects are pre-1.0, where a minor may break. Composite kwargs
+# passthrough does not change this: forwarding is signature-aware, so `force=`
+# is forwarded when the installed pathlib_next provides it and rejected at the
+# boundary when it does not (verified against 0.9.0 and 0.9.1).
 dependencies = ["pathlib_next>=0.8.6,<0.10", "netimps>=0.1,<0.3"]
 
 [project.optional-dependencies]

{hostctl-0.2.2 → hostctl-0.2.4}/src/hostctl/host/composite_path.py

@@ -8,6 +8,7 @@ authority for I/O.
 
 from __future__ import annotations
 
+import inspect
 import pathlib
 import typing
 
@@ -27,16 +28,228 @@ def _supports(provider: PathProvider, operation: PathOperation) -> bool:
     )
 
 
+def _accepts_kwargs(
+    method: typing.Callable[..., object],
+    kwargs: dict[str, object],
+    operation: PathOperation,
+) -> dict[str, object]:
+    """Return ``kwargs``, first checking the backend method accepts them.
+
+    Composite dispatch normalises to the stdlib signature, which made a
+    backend's documented extension unreachable through the wrapper.  Rather
+    than forward blindly -- which turns a clear ``TypeError`` here into a
+    confusing one from inside a transport -- consult the selected backend's
+    signature and reject at this boundary what it cannot take.
+
+    A method whose signature cannot be introspected (a C function, a
+    ``functools.partial`` over one) is given the benefit of the doubt and
+    the kwargs are forwarded; a backend that then rejects them raises its
+    own ``TypeError``, which is no worse than calling it directly.
+    """
+
+    if not kwargs:
+        return kwargs
+
+    try:
+        signature = inspect.signature(method)
+    except (TypeError, ValueError):
+        return kwargs
+
+    parameters = signature.parameters
+    if any(
+        parameter.kind is inspect.Parameter.VAR_KEYWORD
+        for parameter in parameters.values()
+    ):
+        return kwargs
+
+    unsupported = sorted(name for name in kwargs if name not in parameters)
+    if unsupported:
+        owner = getattr(method, "__self__", None)
+        backend = type(owner).__name__ if owner is not None else "backend path"
+        raise TypeError(
+            f"{backend}.{operation}() does not accept "
+            + ", ".join(repr(name) for name in unsupported)
+        )
+    return kwargs
+
+
+def _is_composite_owner(base: type) -> bool:
+    """True for classes belonging to this module's composite hierarchy.
+
+    Used to tell a deliberate composite override (``iterdir``, ``rename``,
+    ``readlink``, ``copy``) apart from an inherited ``pathlib_next``
+    implementation, which is exactly what forwarding must displace.
+    """
+    return getattr(base, "__module__", "") == __name__
+
+
+def _make_forwarder(
+    name: str, capability: PathOperation, pin: bool, retry_safe: bool
+) -> typing.Callable[..., object]:
+    """Build a method forwarding ``name`` to the selected backend path."""
+
+    def forwarder(self, *args, **kwargs):
+        # A composite path used as an argument (a symlink target, a
+        # samefile operand) is meaningless to the backend, which would
+        # re-parse it through its own constructor.  Hand over the logical
+        # string and let the backend build its own path type from it.
+        args = tuple(
+            str(arg) if isinstance(arg, _CompositePathMixin) else arg for arg in args
+        )
+
+        def call(path: Path):
+            method = getattr(path, name, None)
+            if method is None:
+                raise NotImplementedError(
+                    f"{type(path).__name__} does not support {name}"
+                )
+            return method(*args, **_accepts_kwargs(method, kwargs, name))
+
+        return self._dispatch(
+            capability, call, pin=pin, retry_on_not_implemented=retry_safe
+        )
+
+    forwarder.__name__ = name
+    forwarder.__qualname__ = f"_CompositePathMixin.{name}"
+    forwarder.__doc__ = (
+        f"Route ``{name}`` to the selected path provider's backend path.\n\n"
+        f"        Forwarded verbatim, so a backend overriding ``{name}`` for a\n"
+        f"        transport-native implementation is the code that runs.\n"
+        f"        Generated from ``_FORWARDED``; see that table for the\n"
+        f"        capability gate and retry contract.\n        "
+    )
+    return forwarder
+
+
+# Methods forwarded verbatim to the selected backend path.  Each entry maps a
+# method name to the capability string gating it, whether the call pins the
+# provider, and whether a `NotImplementedError` from it may fall through to the
+# next provider.
+#
+# The method that was *called* is the method invoked on the backend -- never a
+# decomposition into primitives.  Backends override derived operations for real
+# optimization (``SftpPath.copy`` fans out over asyncssh workers,
+# ``SftpPath.rm``/``checksum`` run server-side, ``LocalPath`` reaches ``shutil``
+# and ``os.scandir``), and decomposing would silently discard all of it while
+# still producing correct results.  Anything the backend does not override
+# resolves to ``pathlib_next``'s own wrapper, so operations added upstream work
+# by adding a row here rather than writing a body.
+#
+# ``retry_safe`` is deliberately conservative.  A wrapper composed of several
+# primitives may already have mutated when a later primitive raises --
+# ``Path.symlink_to(force=True)`` unlinks *before* calling ``_symlink_to``, so a
+# backend lacking that primitive deletes the entry and only then raises.
+# ``NotImplementedError`` cannot distinguish "did nothing" from "did half", so
+# only calls that cannot mutate before raising opt in.
+_FORWARDED: "dict[str, tuple[str, bool, bool]]" = {
+    # name: (capability, pin, retry_safe)
+    "exists": ("exists", False, True),
+    "is_file": ("is_file", False, True),
+    "is_dir": ("is_dir", False, True),
+    "is_symlink": ("stat", False, True),
+    "is_block_device": ("stat", False, True),
+    "is_char_device": ("stat", False, True),
+    "is_fifo": ("stat", False, True),
+    "is_socket": ("stat", False, True),
+    "stat": ("stat", False, True),
+    "lstat": ("stat", False, True),
+    "samefile": ("stat", False, True),
+    "read_bytes": ("read", False, True),
+    "read_text": ("read", False, True),
+    "checksum": ("read", False, True),
+    "supported_checksums": ("read", False, True),
+    "chown": ("chmod", True, True),
+    "chmod": ("chmod", True, True),
+    "lchmod": ("chmod", True, True),
+    "write_bytes": ("write", True, False),
+    "write_text": ("write", True, False),
+    "mkdir": ("mkdir", True, False),
+    "touch": ("write", True, False),
+    "unlink": ("unlink", True, False),
+    "rmdir": ("rmdir", True, False),
+    "rm": ("unlink", True, False),
+    "symlink_to": ("symlink_to", True, False),
+}
+
+
 class _CompositePathMixin:
     """Provider routing shared by the POSIX and Windows concrete classes."""
 
     __slots__ = ()
 
+    def __init_subclass__(cls, **kwargs):
+        """Install the forwarders on every concrete composite class.
+
+        Generated here rather than written out so that following
+        ``pathlib_next`` is a row in ``_FORWARDED``, not a new method body.
+        A class defining the name in its own body always wins -- that is the
+        opt-out for an operation needing real composite logic (``iterdir``,
+        ``rename``, ``readlink``, ``copy``/``move``).
+        """
+        super().__init_subclass__(**kwargs)
+        for name, (capability, pin, retry_safe) in _FORWARDED.items():
+            # Only a definition inside the composite classes themselves opts
+            # out.  Testing the whole MRO would match everything inherited
+            # from ``pathlib_next.Path`` -- which is the entire surface this
+            # table exists to route.
+            owner = next(
+                (
+                    base
+                    for base in cls.__mro__
+                    if name in vars(base) and _is_composite_owner(base)
+                ),
+                None,
+            )
+            if owner is not None:
+                continue
+            setattr(cls, name, _make_forwarder(name, capability, pin, retry_safe))
+
     def copy(self, target, **kwargs):
-        return Path.copy(self, target, **kwargs)
+        return self._transfer("copy", target, **kwargs)
 
     def move(self, target, **kwargs):
-        return Path.move(self, target, **kwargs)
+        return self._transfer("move", target, **kwargs)
+
+    def _transfer(self, name, target, **kwargs):
+        """Route ``copy``/``move`` to the backend when both ends agree.
+
+        A backend overrides these for transport-native transfer --
+        ``SftpPath.copy`` fans out over asyncssh workers rather than
+        streaming bytes through the client -- so handing the call straight
+        to ``Path.copy`` would be correct and much slower.
+
+        The backend can only be used when the destination resolves to a
+        path *it* understands: a plain backend path, or a composite path
+        sharing this provider.  Anything else (a composite path on another
+        provider, a foreign ``Path``) is a genuine cross-backend transfer,
+        which is what the generic implementation exists for.
+        """
+        generic = getattr(Path, name)
+        provider = self._provider
+        backend_target = target
+        if isinstance(target, _CompositePathMixin):
+            if provider is None or not any(
+                item is provider for item in target.providers
+            ):
+                return generic(self, target, **kwargs)
+            backend_target = target._provider_path(provider)
+        elif isinstance(target, str):
+            backend_target = target
+        elif not isinstance(target, Path):
+            return generic(self, target, **kwargs)
+
+        def call(path: Path):
+            method = getattr(type(path), name, None)
+            if method is None or method is generic:
+                # The backend adds nothing over the generic implementation;
+                # use it directly so composite-aware behavior is preserved.
+                return generic(self, target, **kwargs)
+            return method(path, backend_target, **kwargs)
+
+        # Gated on "write", not a "copy"/"move" capability: neither is in
+        # PathProvider.DEFAULT_CAPABILITIES, so gating on the method name
+        # would reject every provider that has not opted in by hand.
+        return self._dispatch("write", call, pin=True)
 
     def _copy_from(self, source, **kwargs):
         """Accept Python 3.14 stdlib ``Path.copy()`` destinations."""
@@ -136,9 +349,11 @@ class _CompositePathMixin:
         *,
         pin: bool = False,
         with_provider: bool = False,
+        retry_on_not_implemented: bool = False,
     ):
         candidates = self._providers_in_order(operation, pin=pin)
         attempted = False
+        not_implemented: typing.Optional[NotImplementedError] = None
         for provider in candidates:
             attempted = True
             old = (self._provider, self._backend_path, self._factory, self._pinned)
@@ -150,6 +365,21 @@ class _CompositePathMixin:
                     # undo this and try the next provider.
                     self._adopt(provider, backend_path, pinned=True)
                 result = callback(backend_path)
+            except NotImplementedError as exc:
+                if not retry_on_not_implemented:
+                    # The call may have mutated before raising -- a wrapper
+                    # composed of primitives can fail partway (see _FORWARDED).
+                    # Report it rather than silently repeating the work
+                    # against another provider.
+                    raise
+                not_implemented = exc
+                if pin:
+                    self._provider, self._backend_path, self._factory, self._pinned = (
+                        old
+                    )
+                if self._selector is not None:
+                    self._selector.decline(provider.name, str(exc))
+                continue
             except OperationNotStarted as exc:
                 if pin:
                     self._provider, self._backend_path, self._factory, self._pinned = (
@@ -166,6 +396,14 @@ class _CompositePathMixin:
             return (result, provider) if with_provider else result
         if not attempted:
             raise NotImplementedError(f"no path provider supports {operation}")
+        if not_implemented is not None:
+            # Every candidate declined by saying it cannot do this at all.
+            # Surfacing OperationNotStarted here would rename a permanent
+            # "no backend implements this" into a transient "nothing started",
+            # which reads as retryable and hides the real cause -- most
+            # visibly with a single provider, where "try the next one" has
+            # nothing to try.
+            raise not_implemented
         raise OperationNotStarted(f"no path provider completed {operation}")
 
     def via(self, name: str):
@@ -267,49 +505,52 @@ class _CompositePathMixin:
     def parent(self):
         return self._child(str(super().parent))
 
-    def stat(self, *, follow_symlinks: bool = True):
-        return self._dispatch(
-            "stat", lambda path: path.stat(follow_symlinks=follow_symlinks)
-        )
-
-    def _scan_with_provider(self):
-        # The provider's iterator is returned only after the pre-dispatch
-        # operation has succeeded; errors after that point are terminal.
-        return self._dispatch(
-            "scandir", lambda path: iter(path.iterdir()), with_provider=True
-        )
-
     def _scandir(self):
-        """Yield ``(name, stat)`` pairs for ``walk()``/``glob()``.
-
-        ``pathlib_next.Path._scandir`` is a listing hook with a fixed shape;
-        overriding it with a different return type silently breaks every
-        caller.  Provider selection still happens once, in
-        ``_scan_with_provider``.
+        """Yield ``(name, stat)`` pairs, routed to the backend's listing.
+
+        ``_scandir`` is the primitive and ``iterdir`` derives from it, not
+        the other way round: a backend whose listing call already carries
+        metadata answers in one round trip (``SftpPath`` uses
+        ``listdir_attr``; FTP/HTTP/S3 do the equivalent).  Listing via
+        ``iterdir`` instead would rebuild every child as a composite path
+        and then stat each one separately, discarding that.
         """
-        from pathlib_next.path import FileStat
-
-        for entry in self.iterdir():
-            try:
-                stat = FileStat.from_path(entry, follow_symlink=False)
-            except OSError:
-                stat = None
-            yield entry.name, stat
+        entries, _provider = self._dispatch(
+            "scandir",
+            lambda path: iter(path._scandir()),
+            with_provider=True,
+            retry_on_not_implemented=True,
+        )
+        return entries
 
     def iterdir(self):
-        children, provider = self._scan_with_provider()
-        for child in children:
+        # Dispatches for the provider as well as the entries: children must
+        # be built against the provider that actually scanned, and
+        # ``__slots__`` leaves nowhere to stash it between calls.
+        entries, provider = self._dispatch(
+            "scandir",
+            lambda path: iter(path._scandir()),
+            with_provider=True,
+            retry_on_not_implemented=True,
+        )
+        for name, _stat in entries:
             yield type(self).from_path(
-                child,
+                provider.path(str(self), name),
                 provider,
                 provider.path,
                 self._providers,
                 self._selector,
                 pinned=self._pinned,
-                logical_segments=(str(self), getattr(child, "name", str(child))),
+                logical_segments=(str(self), name),
             )
 
     def open(self, mode="r", buffering=-1, encoding=None, errors=None, newline=None):
+        """Open through the selected provider.
+
+        Hand-written rather than generated because the capability gate
+        depends on the mode: a read opens under ``open_read``, a write
+        under ``open_write``.
+        """
         raw_mode = mode.replace("b", "")
         write = any(flag in raw_mode for flag in "wax+")
         operation = "open_write" if write else "open_read"
@@ -323,66 +564,11 @@ class _CompositePathMixin:
                 newline=newline,
             ),
             pin=True,
+            # A read has not mutated anything when it reports it cannot open;
+            # a write may have created or truncated the file first.
+            retry_on_not_implemented=not write,
         )
 
-    def read_bytes(self):
-        return self._dispatch("read", lambda path: path.read_bytes())
-
-    def write_bytes(self, data):
-        return self._dispatch("write", lambda path: path.write_bytes(data), pin=True)
-
-    def read_text(self, *args, **kwargs):
-        return self._dispatch("read", lambda path: path.read_text(*args, **kwargs))
-
-    def write_text(self, data, *args, **kwargs):
-        return self._dispatch(
-            "write", lambda path: path.write_text(data, *args, **kwargs), pin=True
-        )
-
-    def exists(self, *, follow_symlinks=True):
-        return self._dispatch(
-            "exists", lambda path: path.exists(follow_symlinks=follow_symlinks)
-        )
-
-    def is_file(self):
-        return self._dispatch("is_file", lambda path: path.is_file())
-
-    def is_dir(self):
-        return self._dispatch("is_dir", lambda path: path.is_dir())
-
-    def mkdir(self, mode=0o777, parents=False, exist_ok=False):
-        return self._dispatch(
-            "mkdir",
-            lambda path: path.mkdir(mode=mode, parents=parents, exist_ok=exist_ok),
-            pin=True,
-        )
-
-    def chmod(self, mode, *, follow_symlinks=True):
-        return self._dispatch(
-            "chmod",
-            lambda path: path.chmod(mode, follow_symlinks=follow_symlinks),
-            pin=True,
-        )
-
-    def symlink_to(self, target, target_is_directory: bool = False):
-        """Create this path as a symlink, through the selected provider.
-
-        The backend path class owns the transport's real capability: a
-        backend without symlink support raises ``NotImplementedError``
-        (never a silent no-op), and that surfaces here unchanged.
-        """
-        logical_target = str(target)
-
-        def symlink_with_selected_provider(path):
-            method = getattr(path, "symlink_to", None)
-            if method is None:
-                raise NotImplementedError(
-                    f"{type(path).__name__} does not support symlink_to"
-                )
-            return method(logical_target, target_is_directory)
-
-        return self._dispatch("symlink_to", symlink_with_selected_provider, pin=True)
-
     def readlink(self):
         def readlink_with_selected_provider(path):
             method = getattr(path, "readlink", None)
@@ -408,14 +594,6 @@ class _CompositePathMixin:
             logical_segments=(str(target),),
         )
 
-    def unlink(self, missing_ok=False):
-        return self._dispatch(
-            "unlink", lambda path: path.unlink(missing_ok=missing_ok), pin=True
-        )
-
-    def rmdir(self):
-        return self._dispatch("rmdir", lambda path: path.rmdir(), pin=True)
-
     def rename(self, target):
         logical_target = str(target)
 

hostctl-0.2.4/tests/test_composite_path_backend_kwargs.py

@@ -0,0 +1,118 @@
+"""Backend-specific keyword arguments survive composite dispatch.
+
+The composite path normalises every operation to the stdlib signature, which
+made a backend's documented extension unreachable through the very wrapper
+meant to expose it.  Forwarding is signature-aware on purpose: a kwarg the
+selected backend declares is passed through, and one it does not is rejected
+*here*, so the error names the composite boundary instead of surfacing from
+inside a transport.
+"""
+
+import inspect
+
+import pytest
+from pathlib_next.mempath import MemPath, MemPathBackend
+
+from hostctl import PathProvider, PosixHost
+
+
+class ExtendedMemPath(MemPath):
+    """A backend path with an extension, as real backends do."""
+
+    calls: list[tuple[str, dict]] = []
+
+    # MemPath has no symlink_to to delegate to; recording the call is the
+    # whole point here -- what is under test is which kwargs arrive, not
+    # whether the memory backend can model a symlink.
+    def symlink_to(self, target, target_is_directory=False, *, force=False):
+        type(self).calls.append(("symlink_to", {"force": force}))
+
+    def mkdir(self, mode=0o777, parents=False, exist_ok=False, *, owner=None):
+        type(self).calls.append(("mkdir", {"owner": owner}))
+        return super().mkdir(mode=mode, parents=parents, exist_ok=exist_ok)
+
+
+@pytest.fixture
+def host():
+    backend = MemPathBackend()
+    ExtendedMemPath("root", backend=backend).mkdir()
+    ExtendedMemPath("root/target", backend=backend).write_bytes(b"t")
+    # Reset *after* fixture setup: the mkdir above is an ExtendedMemPath call
+    # too, and would otherwise read as something the test provoked.
+    ExtendedMemPath.calls = []
+    # ``symlink_to``/``readlink`` are not in DEFAULT_CAPABILITIES, so a
+    # provider that supports them has to say so or dispatch never reaches
+    # the backend at all.
+    provider = PathProvider(
+        "extended",
+        lambda *p: ExtendedMemPath(*p, backend=backend),
+        capabilities=PathProvider.DEFAULT_CAPABILITIES | {"symlink_to", "readlink"},
+    )
+    return PosixHost(path_providers=(provider,))
+
+
+def test_backend_extension_kwarg_reaches_the_backend(host):
+    link = host.path("root", "link")
+
+    try:
+        link.symlink_to("root/target", force=True)
+    except NotImplementedError:
+        pytest.skip("backing pathname does not implement symlink_to here")
+
+    assert ("symlink_to", {"force": True}) in ExtendedMemPath.calls
+
+
+def test_mkdir_extension_kwarg_reaches_the_backend(host):
+    host.path("root", "made").mkdir(owner="operator")
+
+    assert ("mkdir", {"owner": "operator"}) in ExtendedMemPath.calls
+
+
+def test_unknown_kwarg_fails_at_the_composite_boundary(host):
+    """Not forwarded blindly: the message names the backend, not a transport."""
+    link = host.path("root", "link")
+
+    with pytest.raises(TypeError) as excinfo:
+        link.symlink_to("root/target", no_such_option=True)
+
+    assert "no_such_option" in str(excinfo.value)
+    assert "ExtendedMemPath.symlink_to()" in str(excinfo.value)
+    assert ExtendedMemPath.calls == []
+
+
+def test_no_kwargs_leaves_the_stdlib_call_untouched(host):
+    """The common path must not pay for -- or be changed by -- introspection."""
+    host.path("root", "plain").mkdir()
+
+    assert ("mkdir", {"owner": None}) in ExtendedMemPath.calls
+
+
+def test_force_reaches_a_real_backend_end_to_end(tmp_path):
+    """`symlink_to(force=)` over a genuine backend, no fake in the way.
+
+    As of pathlib_next 0.9.0+, `force=` is a generic `Path` extension rather
+    than a backend-specific one, so this exercises the whole chain --
+    composite wrapper, signature check, real filesystem -- which is the call
+    that raised `TypeError` before the passthrough existed.
+    """
+    from pathlib_next import Path as PnPath
+
+    if "force" not in inspect.signature(PnPath.symlink_to).parameters:
+        pytest.skip("installed pathlib_next predates symlink_to(force=)")
+
+    provider = PathProvider(
+        "local",
+        lambda *p: PnPath(*p),
+        capabilities=PathProvider.DEFAULT_CAPABILITIES | {"symlink_to", "readlink"},
+    )
+    host = PosixHost(path_providers=(provider,))
+    target = tmp_path / "target"
+    target.write_text("t")
+    link = tmp_path / "link"
+    link.write_text("occupied")  # force= has to displace this
+
+    host.path(str(link).replace("\\", "/")).symlink_to(
+        str(target).replace("\\", "/"), force=True
+    )
+
+    assert link.is_symlink()

hostctl-0.2.4/tests/test_composite_path_inherited_operations.py

@@ -0,0 +1,124 @@
+"""Composite paths forward the called method and inherit the rest.
+
+Two properties, and they pull against each other:
+
+1. A backend that overrides a derived operation for a transport-native
+   implementation must be the code that runs -- ``SftpPath.copy`` fans out
+   over asyncssh workers, ``SftpPath.rm``/``checksum`` execute server-side,
+   ``LocalPath`` reaches ``shutil``/``os.scandir``. Decomposing a call into
+   backend primitives would still produce correct results while silently
+   discarding every one of those, which no output assertion would catch.
+2. An operation hostctl never declares must still work, so that following
+   ``pathlib_next`` does not mean hand-writing a forwarder per release.
+
+The tests below pin both, because satisfying either one alone is easy and
+the failure mode of trading one for the other is invisible.
+"""
+
+import inspect
+
+import pytest
+from pathlib_next.mempath import MemPath, MemPathBackend
+
+from hostctl import PathProvider, PosixHost
+
+FULL = PathProvider.DEFAULT_CAPABILITIES | {"symlink_to", "readlink", "scandir"}
+
+
+class RecordingMemPath(MemPath):
+    """A backend that overrides derived operations, as real backends do."""
+
+    calls: list = []
+
+    def copy(self, target, **kwargs):
+        type(self).calls.append("copy")
+        return super().copy(target, **kwargs)
+
+    def rm(self, *args, **kwargs):
+        type(self).calls.append("rm")
+        return super().rm(*args, **kwargs)
+
+    def touch(self, mode=0o666, exist_ok=True):
+        type(self).calls.append("touch")
+        return super().touch(mode=mode, exist_ok=exist_ok)
+
+
+@pytest.fixture
+def host():
+    backend = MemPathBackend()
+    RecordingMemPath("root", backend=backend).mkdir()
+    RecordingMemPath("root/a.txt", backend=backend).write_bytes(b"a")
+    RecordingMemPath.calls = []
+    provider = PathProvider(
+        "recording",
+        lambda *p: RecordingMemPath(*p, backend=backend),
+        capabilities=FULL,
+    )
+    return PosixHost(path_providers=(provider,))
+
+
+def test_backend_override_of_copy_runs(host):
+    """The backend's own copy() must run, not a primitive decomposition."""
+    source = host.path("root", "a.txt")
+
+    source.copy(host.path("root", "b.txt"))
+
+    assert "copy" in RecordingMemPath.calls
+
+
+def test_backend_override_of_rm_runs(host):
+    """rm() is a derived operation; SftpPath implements it server-side."""
+    target = host.path("root", "a.txt")
+
+    target.rm()
+
+    assert "rm" in RecordingMemPath.calls
+
+
+def test_backend_override_of_touch_runs(host):
+    """touch() is derived from chmod()/open() but backends may override it."""
+    host.path("root", "t.txt").touch()
+
+    assert "touch" in RecordingMemPath.calls
+
+
+@pytest.mark.parametrize(
+    "operation",
+    [
+        pytest.param(lambda p: p.lstat(), id="lstat"),
+        pytest.param(lambda p: p.is_symlink(), id="is_symlink"),
+        pytest.param(lambda p: p.read_text(), id="read_text"),
+        pytest.param(lambda p: p.exists(), id="exists"),
+    ],
+)
+def test_operations_work_without_a_composite_declaration(host, operation):
+    """None of these need a hand-written method in composite_path.py."""
+    operation(host.path("root", "a.txt"))
+
+
+def test_chown_reaches_the_backend_without_a_composite_method(host):
+    """The regression that motivated this: 0.9.1 added chown(), hostctl had none.
+
+    The assertion is that the call *reaches the backend* -- MemPath has no
+    ``_chown`` primitive, so NotImplementedError from it is the proof that
+    routing happened rather than a missing attribute at the composite layer.
+    """
+    from pathlib_next import Path as PnPath
+
+    if not hasattr(PnPath, "chown"):
+        pytest.skip("installed pathlib_next predates chown()")
+
+    from hostctl.host import composite_path
+
+    assert "def chown" not in inspect.getsource(composite_path)
+
+    with pytest.raises(NotImplementedError) as excinfo:
+        host.path("root", "a.txt").chown(uid=0)
+
+    assert "_chown" in str(excinfo.value)
+
+
+def test_walk_yields_composite_paths(host):
+    """A derived traversal must still hand back routed paths, not raw ones."""
+    for root, _dirs, _files in host.path("root").walk():
+        assert root.provider is not None

{hostctl-0.2.2 → hostctl-0.2.4}/tests/test_system_hosts.py

@@ -388,10 +388,10 @@ def test_composite_path_uses_target_flavour_independent_of_client():
     )
     windows = WindowsHost(path_providers=(windows_provider,)).path(
         r"C:\\Users",
-        "jose",
+        "operator",
     )
     assert type(windows).__name__ == "CompositeWindowsPath"
-    assert str(windows) == r"C:\Users\jose"
+    assert str(windows) == r"C:\Users\operator"
     assert windows.drive == "C:"
     assert windows.root == "\\"
     assert windows.parent.name == "Users"