hostctl 0.2.0__tar.gz → 0.2.1__tar.gz

{hostctl-0.2.0 → hostctl-0.2.1}/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-07-29
+
+### Added
+
+- `ConnectionString` parses a connection target from whatever a user typed.
+  `ConnectionString("nas", scheme="wss")` and `ConnectionString("nas:8443",
+  ...)` parse, because a bare host is not an invalid URI — it is a URI with
+  the scheme left off, which is what people type on a command line.
+
+  Every field can be supplied directly, and three layers decide each one: an
+  explicit argument wins, then whatever the string carried, then `defaults`.
+  `scheme=`/`port=`/`host=`/… are therefore *overrides* — `scheme="ssh"`
+  beats a `wss://` in the string — while `defaults` (a mapping, or another
+  `ConnectionString` used as a profile) fills only what nothing else
+  supplied.
+
+  A port carries its own resolution strategy wherever one is accepted: an
+  `int`, a callable `scheme -> port | None`, or anything indexable by scheme
+  (a plain mapping), so a caller passes its whole table without pre-selecting
+  an entry. When no layer supplies one, `netimps.get_default_port` resolves
+  the scheme — it knows schemes no system services database does (`ws`/`wss`,
+  `socks5`), and an application can register more with
+  `netimps.register_port`.
+
+  `False` stops the search outright: no port, and no lookup.
+
+  Credentials are parsed but never rendered. `str()` and `repr()` both emit
+  the redacted form, with the password **removed rather than masked**, so the
+  output stays a valid, reusable connection string that cannot round-trip a
+  wrong credential — and a value reaching a log line or a traceback frame
+  cannot leak one. A password may carry `key:value` extras after a newline,
+  as `parse_credentials` describes, written raw.
+
+  The host keeps the spelling it was given. `is_local` resolves nothing — it
+  is called while a configuration is built, which is network-free, and
+  resolving would both block and raise on a name that does not resolve. An
+  address literal is answered by `netimps.is_local_address`, so an address
+  actually assigned to this machine counts as local and not just loopback,
+  while a name is compared against the loopback spellings. `qsl` and
+  `query_val()` read the query; `replace()` returns a changed copy.
+
+### Changed
+
+- **`netimps` is now a required dependency**, supplying scheme/port and
+  address semantics rather than hostctl reimplementing them. Note this
+  arrives in a patch release: an existing install pinned within `0.2.x` gains
+  a new requirement, so a locked or offline environment needs `netimps`
+  available before upgrading.
+
+### Fixed
+
+- A path in a command is rendered through `__fspath__` rather than `str()`.
+  Every transport now shares one `command_text` helper — the SSH, WinRM,
+  container, QGA, and PSRP executors each stringified with `str()`, so only
+  the local executor asked for the filesystem representation. `__fspath__` is
+  tried by attribute rather than by `isinstance(value, os.PathLike)`, so a
+  duck-typed path that never registered with the ABC is honoured too, and an
+  object whose `__fspath__` raises or returns a non-string falls back to
+  `str()` rather than failing the command. The shell layer follows the same
+  rule. No shipped path type changes behaviour — `str()` and `__fspath__`
+  agree for all of them — but the contract now matches what a path promises.
+
 ## [0.2.0] - 2026-07-28
 
 ### Added
@@ -230,7 +292,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.0...HEAD
+[Unreleased]: https://github.com/jose-pr/hostctl/compare/v0.2.1...HEAD
+[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
 [0.1.2]: https://github.com/jose-pr/hostctl/compare/v0.1.0...v0.1.2
 [0.1.0]: https://github.com/jose-pr/hostctl/releases/tag/v0.1.0

{hostctl-0.2.0 → hostctl-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hostctl
-Version: 0.2.0
+Version: 0.2.1
 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/
@@ -24,6 +24,7 @@ Classifier: Topic :: System :: Filesystems
 Classifier: Topic :: System :: Systems Administration
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
+Requires-Dist: netimps<0.2,>=0.1
 Requires-Dist: pathlib-next<0.9,>=0.8.6
 Provides-Extra: container
 Requires-Dist: docker<8,>=7.1; extra == 'container'

{hostctl-0.2.0 → hostctl-0.2.1}/docs/api/reference.md

@@ -80,6 +80,7 @@ without a deprecation cycle.
 
 ## Connection strings
 
+::: hostctl.ConnectionString
 ::: hostctl.redact_uri
 ::: hostctl.parse_credentials
 ::: hostctl.strict_uri_credentials

{hostctl-0.2.0 → hostctl-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hostctl"
-version = "0.2.0"
+version = "0.2.1"
 authors = [{ name = "Jose A." }]
 description = "Run commands and access files on a host, local or remote, protocol-agnostic"
 readme = "README.md"
@@ -28,9 +28,12 @@ classifiers = [
     "Topic :: System :: Filesystems",
     "Typing :: Typed",
 ]
-# pathlib_next supplies the common local/remote path return type. Transport
-# implementations remain extras, so importing hostctl never requires them.
-dependencies = ["pathlib_next>=0.8.6,<0.9"]
+# pathlib_next supplies the common local/remote path return type. netimps
+# supplies scheme/port and address semantics -- including schemes no system
+# services database knows (ws/wss, socks5) -- so hostctl does not reimplement
+# them. Transport implementations remain extras, so importing hostctl never
+# requires them.
+dependencies = ["pathlib_next>=0.8.6,<0.9", "netimps>=0.1,<0.2"]
 
 [project.optional-dependencies]
 # SSH-backed run()/path(): asyncssh for shell exec, pathlib_next's SftpPath

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/__init__.py

@@ -33,6 +33,7 @@ from .executor import (
 )
 from .host import (
     ContainerConfig as ContainerConfig,
+    ConnectionString as ConnectionString,
     ContainerHost as ContainerHost,
     Exec as Exec,
     Host as Host,
@@ -126,6 +127,7 @@ __all__ = [
     "ssh_providers",
     "strict_uri_credentials",
     "strict_uri_query",
+    "ConnectionString",
     "uri_host",
     "uri_hostname",
     "winrm_providers",

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/_common.py

@@ -94,6 +94,39 @@ def normalize_input(
     return input
 
 
+def command_text(
+    value: object, *, encoding: str = "utf-8", errors: str = "strict"
+) -> str:
+    """Render one command or argv value as the text a transport sends.
+
+    Anything offering `__fspath__` is asked for it first: that is the
+    filesystem representation a path promises, and it is what a transport
+    needs. `str()` happens to match for the path types shipped here, but that
+    is a coincidence of their `__str__` rather than a contract -- a path type
+    whose `repr`-ish `__str__` differs would otherwise send the wrong text.
+
+    `__fspath__` is tried directly rather than through
+    `isinstance(value, os.PathLike)`, so a duck-typed path that never
+    registered with the ABC is still honoured. A object whose `__fspath__`
+    raises or returns a non-string falls back to `str()` rather than failing
+    the command.
+
+    Bytes -- returned by `__fspath__` or passed directly -- are decoded;
+    everything else is stringified.
+    """
+    fspath = getattr(value, "__fspath__", None)
+    if callable(fspath):
+        try:
+            resolved = fspath()
+        except Exception:
+            resolved = None
+        if isinstance(resolved, (str, bytes)):
+            value = resolved
+    if isinstance(value, bytes):
+        return value.decode(encoding, errors)
+    return str(value)
+
+
 def normalize_environment(
     env: typing.Optional[Environment],
 ) -> typing.Optional[typing.Dict[str, str]]:

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/container.py

@@ -7,6 +7,7 @@ import typing
 
 from ._common import (
     CaptureOutput,
+    command_text,
     CommandArgument,
     Environment,
     Executor,
@@ -79,10 +80,8 @@ class ContainerExecutor(Executor[subprocess.CompletedProcess]):
             )
 
         stdout, stderr = capture_streams(capture_output, stdout, stderr)
-        argv = [str(command)]
-        argv.extend(
-            value.decode() if isinstance(value, bytes) else str(value) for value in args
-        )
+        argv = [command_text(command)]
+        argv.extend(command_text(value) for value in args)
         merge_stderr = stderr is subprocess.STDOUT
         exec_options: typing.Dict[str, object] = {
             "stdout": True,

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/local.py

@@ -8,6 +8,7 @@ import typing
 
 from ._common import (
     CaptureOutput,
+    command_text,
     CommandArgument,
     Environment,
     Executor,
@@ -52,21 +53,7 @@ class LocalExecutor(Executor[subprocess.CompletedProcess]):
             raise TypeError(f"unsupported local executor option: {sorted(options)[0]}")
         reject_stdin_conflict(input, stdin)
         stdout, stderr = capture_streams(capture_output, stdout, stderr)
-        argv = [
-            os.fspath(command),
-            *[
-                (
-                    value.decode()
-                    if isinstance(value, bytes)
-                    else (
-                        os.fspath(value)
-                        if isinstance(value, os.PathLike)
-                        else str(value)
-                    )
-                )
-                for value in args
-            ],
-        ]
+        argv = [command_text(command), *(command_text(value) for value in args)]
         return subprocess.run(
             argv,
             bufsize=bufsize,

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/psrp.py

@@ -9,6 +9,7 @@ import types
 
 from ._common import (
     CaptureOutput,
+    command_text,
     CommandArgument,
     Executor,
     ExecutorCapability,
@@ -92,7 +93,9 @@ class PsrpExecutor(Executor[subprocess.CompletedProcess]):
                 "PSRP pipeline timeout is unsupported; configure WinRM timeouts"
             )
         stdout, stderr = capture_streams(capture_output, stdout, stderr)
-        result = self._session().invoke(str(command), raw=False, capture_exit=True)
+        result = self._session().invoke(
+            command_text(command), raw=False, capture_exit=True
+        )
         codec = encoding or "utf-8"
         # Preserve PowerShell's object-pipeline line orientation when
         # projecting objects to subprocess-compatible text.
@@ -135,7 +138,7 @@ class PsrpExecutor(Executor[subprocess.CompletedProcess]):
             errors=errors,
         )
         completed = subprocess.CompletedProcess(
-            args=str(command),
+            args=command_text(command),
             returncode=returncode,
             stdout=out,
             stderr=err,

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/qemu.py

@@ -11,6 +11,7 @@ import typing
 from ._qga import GuestAgentTransport, QgaProtocolError
 from ._common import (
     CaptureOutput,
+    command_text,
     CommandArgument,
     Environment,
     Executor,
@@ -113,7 +114,8 @@ class QemuExecutor(Executor[subprocess.CompletedProcess]):
                 "QGA guest-exec has no native working-directory support"
             )
         reject_stdin_conflict(input, stdin)
-        if not str(command):
+        program = command_text(command)
+        if not program:
             raise ValueError("QGA guest-exec path must not be empty")
         if timeout is not None and timeout < 0:
             raise ValueError("timeout must not be negative")
@@ -122,15 +124,11 @@ class QemuExecutor(Executor[subprocess.CompletedProcess]):
 
         stdout, stderr = capture_streams(capture_output, stdout, stderr)
         argv = [
-            (
-                value.decode(encoding or "utf-8", errors or "strict")
-                if isinstance(value, bytes)
-                else str(value)
-            )
+            command_text(value, encoding=encoding or "utf-8", errors=errors or "strict")
             for value in args
         ]
         arguments: typing.Dict[str, object] = {
-            "path": str(command),
+            "path": program,
             "arg": argv,
             "capture-output": True,
         }
@@ -156,7 +154,7 @@ class QemuExecutor(Executor[subprocess.CompletedProcess]):
             arguments["input-data"] = base64.b64encode(payload).decode("ascii")
 
         deadline = None if timeout is None else self._clock() + timeout
-        command_display = [str(command), *argv]
+        command_display = [program, *argv]
         started = self._execute(
             {"execute": "guest-exec", "arguments": arguments},
             deadline,

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/ssh.py

@@ -10,6 +10,7 @@ import typing
 
 from ._common import (
     CaptureOutput,
+    command_text,
     CommandArgument,
     Environment,
     Executor,
@@ -135,7 +136,7 @@ class SshExecutor(Executor[subprocess.CompletedProcess]):
             raise NotImplementedError("SshExecutor does not support native arguments")
         if bufsize == 0:
             raise ValueError("bufsize=0 is unsupported by the buffered SSH executor")
-        command = str(command)
+        command = command_text(command)
         reject_stdin_conflict(input, stdin)
         if text and encoding is None:
             encoding = "utf-8"

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/executor/winrm.py

@@ -9,6 +9,7 @@ import typing
 
 from ._common import (
     CaptureOutput,
+    command_text,
     CommandArgument,
     Executor,
     ExecutorCommand,
@@ -165,7 +166,7 @@ class WinRMExecutor(Executor[subprocess.CompletedProcess]):
             raise TypeError(f"unsupported WinRM executor option: {sorted(options)[0]}")
         if args:
             raise NotImplementedError("WinRMExecutor does not support native arguments")
-        command = str(command)
+        command = command_text(command)
         if timeout is not None:
             raise NotImplementedError(
                 "WinRMExecutor timeout is unsupported; configure transport timeouts"

{hostctl-0.2.0 → hostctl-0.2.1}/src/hostctl/host/__init__.py

@@ -13,6 +13,7 @@ from ._common import (
     uri_host as uri_host,
     uri_hostname as uri_hostname,
 )
+from ._connection import ConnectionString as ConnectionString
 from ._ssh import ssh_providers as ssh_providers
 from ._winrm import winrm_providers as winrm_providers
 from ._local import LocalConfig as LocalConfig, LocalHost as LocalHost