hostctl 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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 +344,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.2...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.3...HEAD
+[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.3}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.2.2"
+version = "0.2.3"
 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).
 dependencies = ["pathlib_next>=0.8.6,<0.10", "netimps>=0.1,<0.3"]
 
 [project.optional-dependencies]

{hostctl-0.2.2 → hostctl-0.2.3}/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,6 +28,51 @@ 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
+
+
 class _CompositePathMixin:
     """Provider routing shared by the POSIX and Windows concrete classes."""
 
@@ -350,26 +396,43 @@ class _CompositePathMixin:
     def is_dir(self):
         return self._dispatch("is_dir", lambda path: path.is_dir())
 
-    def mkdir(self, mode=0o777, parents=False, exist_ok=False):
+    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),
+            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):
+    def chmod(self, mode, *, follow_symlinks=True, **kwargs):
         return self._dispatch(
             "chmod",
-            lambda path: path.chmod(mode, follow_symlinks=follow_symlinks),
+            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):
+    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)
 
@@ -379,7 +442,8 @@ class _CompositePathMixin:
                 raise NotImplementedError(
                     f"{type(path).__name__} does not support symlink_to"
                 )
-            return method(logical_target, target_is_directory)
+            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)
 
@@ -408,13 +472,22 @@ class _CompositePathMixin:
             logical_segments=(str(target),),
         )
 
-    def unlink(self, missing_ok=False):
+    def unlink(self, missing_ok=False, **kwargs):
         return self._dispatch(
-            "unlink", lambda path: path.unlink(missing_ok=missing_ok), pin=True
+            "unlink",
+            lambda path: path.unlink(
+                missing_ok=missing_ok,
+                **_accepts_kwargs(path.unlink, kwargs, "unlink"),
+            ),
+            pin=True,
         )
 
-    def rmdir(self):
-        return self._dispatch("rmdir", lambda path: path.rmdir(), 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/tests/test_composite_path_backend_kwargs.py

@@ -0,0 +1,119 @@
+"""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 (`.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.
+"""
+
+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, like pytruenas' ``TruenasPath``."""
+
+    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="jose")
+
+    assert ("mkdir", {"owner": "jose"}) 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()