hostctl 0.2.3__tar.gz → 0.2.4__tar.gz

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

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

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

@@ -7,6 +7,59 @@ 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
@@ -344,7 +397,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.3...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

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.2.3"
+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"
@@ -40,7 +40,7 @@ classifiers = [
 # 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).
+# 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.3 → hostctl-0.2.4}/src/hostctl/host/composite_path.py

@@ -73,16 +73,183 @@ def _accepts_kwargs(
     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."""
@@ -182,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)
@@ -196,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 = (
@@ -212,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):
@@ -313,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"
@@ -369,84 +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, **kwargs):
-        return self._dispatch(
-            "mkdir",
-            lambda path: path.mkdir(
-                mode=mode,
-                parents=parents,
-                exist_ok=exist_ok,
-                **_accepts_kwargs(path.mkdir, kwargs, "mkdir"),
-            ),
-            pin=True,
-        )
-
-    def chmod(self, mode, *, follow_symlinks=True, **kwargs):
-        return self._dispatch(
-            "chmod",
-            lambda path: path.chmod(
-                mode,
-                follow_symlinks=follow_symlinks,
-                **_accepts_kwargs(path.chmod, kwargs, "chmod"),
-            ),
-            pin=True,
-        )
-
-    def symlink_to(self, target, target_is_directory: bool = False, **kwargs):
-        """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.
-
-        Extra keyword arguments are forwarded to the backend's
-        ``symlink_to`` only when its signature actually accepts them --
-        see :func:`_accepts_kwargs`.  A backend extension (for example
-        pytruenas' ``force=``/``onremove=``) is therefore reachable through
-        the composite wrapper, while a kwarg no backend understands still
-        fails at this boundary with a plain ``TypeError`` rather than an
-        obscure one from inside a transport.
-        """
-        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"
-                )
-            extra = _accepts_kwargs(method, kwargs, "symlink_to")
-            return method(logical_target, target_is_directory, **extra)
-
-        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)
@@ -472,23 +594,6 @@ class _CompositePathMixin:
             logical_segments=(str(target),),
         )
 
-    def unlink(self, missing_ok=False, **kwargs):
-        return self._dispatch(
-            "unlink",
-            lambda path: path.unlink(
-                missing_ok=missing_ok,
-                **_accepts_kwargs(path.unlink, kwargs, "unlink"),
-            ),
-            pin=True,
-        )
-
-    def rmdir(self, **kwargs):
-        return self._dispatch(
-            "rmdir",
-            lambda path: path.rmdir(**_accepts_kwargs(path.rmdir, kwargs, "rmdir")),
-            pin=True,
-        )
-
     def rename(self, target):
         logical_target = str(target)
 

{hostctl-0.2.3 → hostctl-0.2.4}/tests/test_composite_path_backend_kwargs.py

@@ -2,11 +2,10 @@
 
 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 (`.agents/findings/processed/
-2026-08-04_composite_symlink_to_drops_backend_kwargs.md`).  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.
+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
@@ -18,7 +17,7 @@ from hostctl import PathProvider, PosixHost
 
 
 class ExtendedMemPath(MemPath):
-    """A backend path with an extension, like pytruenas' ``TruenasPath``."""
+    """A backend path with an extension, as real backends do."""
 
     calls: list[tuple[str, dict]] = []
 
@@ -64,9 +63,9 @@ def test_backend_extension_kwarg_reaches_the_backend(host):
 
 
 def test_mkdir_extension_kwarg_reaches_the_backend(host):
-    host.path("root", "made").mkdir(owner="jose")
+    host.path("root", "made").mkdir(owner="operator")
 
-    assert ("mkdir", {"owner": "jose"}) in ExtendedMemPath.calls
+    assert ("mkdir", {"owner": "operator"}) in ExtendedMemPath.calls
 
 
 def test_unknown_kwarg_fails_at_the_composite_boundary(host):

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.3 → 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"