pathlib-next 0.8.1__tar.gz → 0.8.2__tar.gz

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-07-18
+
+### Fixed
+- **`SftpPath` could not be imported or used with an asyncssh-only install
+  (no `paramiko`).** `uri/schemes/sftp/__init__.py` imported `._paramiko`
+  eagerly at module load, and `_asyncssh.py` imported the
+  `_DEFAULT_SSH_CONFIG` sentinel from `._paramiko`, so merely importing
+  `SftpPath` (or the `AsyncsshSftpBackend`) required `paramiko` even when the
+  caller only wanted the asyncssh backend from the `sftp-async` extra. The
+  paramiko-free bits (the sentinel + config-path normalization) moved to a new
+  `_sshconfig` module, and the paramiko `SftpBackend` is now imported lazily
+  (via `_probe_paramiko`, mirroring `_probe_asyncssh`) only when actually
+  selected. `SftpBackend`/`_DEFAULT_SSH_CONFIG` remain importable from the
+  scheme package (PEP 562 `__getattr__`) for backward compatibility.
+  `PATHLIB_NEXT_SFTP_BACKEND=paramiko` (or `auto` with neither library) now
+  raises a clear `ImportError` naming the missing extra instead of a bare
+  `ModuleNotFoundError` at import time. Regression test added
+  (`test_sftp_scheme_imports_and_resolves_without_paramiko`, runs in a
+  paramiko-masked subprocess).
+
 ## [0.8.1] - 2026-07-16
 
 ### Fixed
@@ -475,7 +495,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Sync error handling.
 - Generic Path Protocol based pathlib implementation for URI paths with file access support for sftp, http, file schemes.
 
-[Unreleased]: https://github.com/jose-pr/pathlib_next/compare/v0.8.1...HEAD
+[Unreleased]: https://github.com/jose-pr/pathlib_next/compare/v0.8.2...HEAD
+[0.8.2]: https://github.com/jose-pr/pathlib_next/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/jose-pr/pathlib_next/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/jose-pr/pathlib_next/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/jose-pr/pathlib_next/compare/v0.6.0...v0.7.0

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pathlib_next
-Version: 0.8.1
+Version: 0.8.2
 Summary: Generic Path Protocol based pathlib
 Project-URL: Homepage, https://github.com/jose-pr/pathlib_next/
 Project-URL: Documentation, https://jose-pr.github.io/pathlib_next/

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pathlib_next"
-version = "0.8.1"
+version = "0.8.2"
 authors = [{ name = "Jose A" }]
 description = "Generic Path Protocol based pathlib"
 readme = "README.md"

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/src/pathlib_next/uri/schemes/sftp/__init__.py

@@ -32,7 +32,9 @@ class BaseSftpBackend(object):
     def client(self, source: Source): ...
 
 
-from ._paramiko import _DEFAULT_SSH_CONFIG, SftpBackend as SftpBackend  # noqa: E402
+# The default-config sentinel is paramiko-free (lives in `_sshconfig`) so
+# importing this scheme never pulls paramiko in just to have the sentinel.
+from ._sshconfig import _DEFAULT_SSH_CONFIG
 
 
 # --- backend selection -----------------------------------------------------
@@ -41,10 +43,18 @@ from ._paramiko import _DEFAULT_SSH_CONFIG, SftpBackend as SftpBackend  # noqa:
 # UriPath backend propagation works, unchanged) > `SftpPath._default_backend_cls`
 # class attribute > `PATHLIB_NEXT_SFTP_BACKEND` env var > auto-detect
 # (asyncssh if importable, else paramiko).
+#
+# BOTH backends are imported lazily (`_probe_asyncssh`/`_probe_paramiko`): merely
+# importing this scheme -- which happens for every `sftp:` URL and for
+# `from ...sftp import SftpPath` -- must not require *either* SSH library. In
+# particular an asyncssh-only install (the `sftp-async` extra, no paramiko) must
+# be able to import and use `SftpPath`; eagerly importing `._paramiko` here broke
+# exactly that.
 
 _ENV_VAR = "PATHLIB_NEXT_SFTP_BACKEND"
-_BACKEND_REGISTRY: "dict[str, type[BaseSftpBackend]]" = {"paramiko": SftpBackend}
+_BACKEND_REGISTRY: "dict[str, type[BaseSftpBackend]]" = {}
 _asyncssh_probed = False
+_paramiko_probed = False
 _resolved_backend_cls: "type[BaseSftpBackend] | None" = None
 
 
@@ -64,47 +74,79 @@ def _probe_asyncssh() -> None:
     _BACKEND_REGISTRY["asyncssh"] = AsyncsshSftpBackend
 
 
+def _probe_paramiko() -> None:
+    # Symmetric with `_probe_asyncssh`: only import paramiko when it is actually
+    # needed (paramiko selected, or auto-detect with asyncssh unavailable), so an
+    # asyncssh-only install never imports paramiko.
+    global _paramiko_probed
+    if _paramiko_probed:
+        return
+    _paramiko_probed = True
+    try:
+        from ._paramiko import SftpBackend
+    except ImportError:
+        return
+    _BACKEND_REGISTRY["paramiko"] = SftpBackend
+
+
 def _resolve_default_backend_cls(reload: bool = False) -> "type[BaseSftpBackend]":
     global _resolved_backend_cls
     if not reload and _resolved_backend_cls is not None:
         return _resolved_backend_cls
     value = _os.environ.get(_ENV_VAR, "auto")
     if value == "paramiko":
+        _probe_paramiko()
+        if "paramiko" not in _BACKEND_REGISTRY:
+            raise ImportError(
+                f"{_ENV_VAR}=paramiko but the paramiko package is not "
+                "installed -- install the 'sftp' extra, or unset "
+                f"{_ENV_VAR} to auto-detect (uses asyncssh if available)."
+            )
         cls = _BACKEND_REGISTRY["paramiko"]
-    else:
+    elif value == "asyncssh":
         _probe_asyncssh()
-        if value == "auto":
-            cls = _BACKEND_REGISTRY.get("asyncssh") or _BACKEND_REGISTRY["paramiko"]
-        elif value == "asyncssh":
-            if "asyncssh" not in _BACKEND_REGISTRY:
-                # Fail loud -- a silent fallback to paramiko would hide a
-                # deployment misconfiguration (asyncssh extra not installed
-                # where the operator explicitly asked for it).
-                raise ImportError(
-                    f"{_ENV_VAR}=asyncssh but the asyncssh package is not "
-                    "installed -- install the 'sftp-async' extra, or unset "
-                    f"{_ENV_VAR} to auto-detect (falls back to paramiko)."
-                )
-            cls = _BACKEND_REGISTRY["asyncssh"]
-        else:
-            raise ValueError(
-                f"{_ENV_VAR}={value!r} is not a recognized SFTP backend "
-                f"(expected one of {sorted({'auto', *_BACKEND_REGISTRY})!r})"
+        if "asyncssh" not in _BACKEND_REGISTRY:
+            # Fail loud -- a silent fallback to paramiko would hide a
+            # deployment misconfiguration (asyncssh extra not installed
+            # where the operator explicitly asked for it).
+            raise ImportError(
+                f"{_ENV_VAR}=asyncssh but the asyncssh package is not "
+                "installed -- install the 'sftp-async' extra, or unset "
+                f"{_ENV_VAR} to auto-detect (falls back to paramiko)."
+            )
+        cls = _BACKEND_REGISTRY["asyncssh"]
+    elif value == "auto":
+        _probe_asyncssh()
+        if "asyncssh" not in _BACKEND_REGISTRY:
+            _probe_paramiko()
+        cls = _BACKEND_REGISTRY.get("asyncssh") or _BACKEND_REGISTRY.get("paramiko")
+        if cls is None:
+            raise ImportError(
+                "no SFTP backend available -- install the 'sftp-async' "
+                "(asyncssh) or 'sftp' (paramiko) extra."
             )
+    else:
+        raise ValueError(
+            f"{_ENV_VAR}={value!r} is not a recognized SFTP backend "
+            "(expected one of 'auto', 'asyncssh', 'paramiko')"
+        )
     _resolved_backend_cls = cls
     return cls
 
 
 def __getattr__(name: str):
-    # PEP 562 lazy module attribute: `from .sftp import AsyncsshSftpBackend`
-    # (or `sftp.AsyncsshSftpBackend`) only imports asyncssh at the point
-    # it's actually referenced -- importing `pathlib_next.uri.schemes.sftp`
-    # itself (which happens for every `sftp:` URL, regardless of which
-    # backend ends up selected) must not eagerly import asyncssh.
+    # PEP 562 lazy module attributes: referencing `AsyncsshSftpBackend`,
+    # `SftpBackend` (paramiko), or `_DEFAULT_SSH_CONFIG` via
+    # `from .sftp import ...` imports the relevant backend only at that point --
+    # importing the scheme module itself pulls in neither SSH library.
     if name == "AsyncsshSftpBackend":
         from ._asyncssh import AsyncsshSftpBackend
 
         return AsyncsshSftpBackend
+    if name == "SftpBackend":
+        from ._paramiko import SftpBackend
+
+        return SftpBackend
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/src/pathlib_next/uri/schemes/sftp/_asyncssh.py

@@ -15,7 +15,7 @@ import asyncssh as _asyncssh
 from ... import Source
 from ....utils.stat import FileStat
 from . import BaseSftpBackend
-from ._paramiko import _DEFAULT_SSH_CONFIG
+from ._sshconfig import _DEFAULT_SSH_CONFIG
 
 # --- shared background event loop -------------------------------------
 # asyncssh is asyncio-only end to end (connect(), every SFTPClient method,

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/src/pathlib_next/uri/schemes/sftp/_paramiko.py

@@ -9,20 +9,11 @@ from .... import utils as _utils
 from ... import Source
 from . import BaseSftpBackend
 
-
-_DEFAULT_SSH_CONFIG = object()
-
-
-def _normalize_config_paths(
-    ssh_config: "object",
-) -> "tuple[str, ...] | None":
-    if ssh_config is _DEFAULT_SSH_CONFIG:
-        return (str(_pathlib.Path.home() / ".ssh" / "config"),)
-    if ssh_config is None:
-        return None
-    if isinstance(ssh_config, (str, _pathlib.PurePath)):
-        return (str(ssh_config),)
-    return tuple(str(path) for path in ssh_config)
+# The sentinel + path normalization are paramiko-free and now live in
+# ``_sshconfig`` so the asyncssh backend and the scheme ``__init__`` can use them
+# without importing paramiko. Re-exported here for backward compatibility (older
+# code did ``from ._paramiko import _DEFAULT_SSH_CONFIG``).
+from ._sshconfig import _DEFAULT_SSH_CONFIG, _normalize_config_paths
 
 
 @_utils.LRU

pathlib_next-0.8.2/src/pathlib_next/uri/schemes/sftp/_sshconfig.py

@@ -0,0 +1,34 @@
+"""Backend-agnostic SSH-config helpers (no paramiko/asyncssh import).
+
+The default-config sentinel and path normalization live here, separate from
+``_paramiko.py``, so the asyncssh backend and the scheme's ``__init__`` can
+reference them **without importing paramiko**. Only the actual config *parsing*
+(``_load_ssh_config``/``_lookup_ssh_config`` in ``_paramiko.py``) needs
+``paramiko.SSHConfig``; the sentinel and the "which files" logic do not.
+"""
+
+from __future__ import annotations
+
+import pathlib as _pathlib
+
+#: Sentinel meaning "use the default SSH config location(s)". A bare ``object()``
+#: so it is distinct from ``None`` (explicitly no config) and from any real path.
+#: Shared by both backends; kept paramiko-free on purpose (see module docstring).
+_DEFAULT_SSH_CONFIG = object()
+
+
+def _normalize_config_paths(
+    ssh_config: "object",
+) -> "tuple[str, ...] | None":
+    """Resolve an ``ssh_config`` argument to a tuple of file paths, or ``None``.
+
+    ``_DEFAULT_SSH_CONFIG`` -> the user's ``~/.ssh/config``; ``None`` -> no config;
+    a str/path -> that one file; an iterable -> those files. No paramiko needed.
+    """
+    if ssh_config is _DEFAULT_SSH_CONFIG:
+        return (str(_pathlib.Path.home() / ".ssh" / "config"),)
+    if ssh_config is None:
+        return None
+    if isinstance(ssh_config, (str, _pathlib.PurePath)):
+        return (str(ssh_config),)
+    return tuple(str(path) for path in ssh_config)

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/tests/test_sftp_asyncssh.py

@@ -137,6 +137,13 @@ def _reset_backend_resolution(monkeypatch):
 
 from pathlib_next.uri.schemes import sftp as sftp_pkg  # noqa: E402
 
+import importlib.util as _importutil  # noqa: E402
+
+_HAS_PARAMIKO = _importutil.find_spec("paramiko") is not None
+_needs_paramiko = pytest.mark.skipif(
+    not _HAS_PARAMIKO, reason="paramiko not installed (asyncssh-only install)"
+)
+
 
 def test_resolve_default_backend_auto_prefers_asyncssh(monkeypatch):
     monkeypatch.delenv(sftp_pkg._ENV_VAR, raising=False)
@@ -144,6 +151,7 @@ def test_resolve_default_backend_auto_prefers_asyncssh(monkeypatch):
     assert cls is backend_mod.AsyncsshSftpBackend
 
 
+@_needs_paramiko
 def test_resolve_default_backend_explicit_paramiko(monkeypatch):
     monkeypatch.setenv(sftp_pkg._ENV_VAR, "paramiko")
     cls = sftp_pkg._resolve_default_backend_cls(reload=True)
@@ -164,7 +172,6 @@ def test_resolve_default_backend_invalid_value_raises(monkeypatch):
 
 def test_resolve_default_backend_asyncssh_unavailable_raises_importerror(monkeypatch):
     monkeypatch.setenv(sftp_pkg._ENV_VAR, "asyncssh")
-    monkeypatch.setitem(sftp_pkg._BACKEND_REGISTRY, "paramiko", sftp_pkg.SftpBackend)
     monkeypatch.delitem(sftp_pkg._BACKEND_REGISTRY, "asyncssh", raising=False)
     monkeypatch.setattr(sftp_pkg, "_asyncssh_probed", True)  # skip the real probe
     with pytest.raises(ImportError, match="sftp-async"):
@@ -172,13 +179,16 @@ def test_resolve_default_backend_asyncssh_unavailable_raises_importerror(monkeyp
 
 
 def test_resolve_default_backend_result_is_cached(monkeypatch):
-    monkeypatch.setenv(sftp_pkg._ENV_VAR, "paramiko")
-    first = sftp_pkg._resolve_default_backend_cls(reload=True)
+    # asyncssh first (always available in this test module), then flip the env
+    # and confirm no-reload returns the cached asyncssh result.
     monkeypatch.setenv(sftp_pkg._ENV_VAR, "asyncssh")
+    first = sftp_pkg._resolve_default_backend_cls(reload=True)
+    monkeypatch.setenv(sftp_pkg._ENV_VAR, "auto")
     second = sftp_pkg._resolve_default_backend_cls()  # no reload -- cached
-    assert first is second is sftp_pkg.SftpBackend
+    assert first is second is backend_mod.AsyncsshSftpBackend
 
 
+@_needs_paramiko
 def test_default_backend_cls_class_attribute_wins_over_env(monkeypatch):
     monkeypatch.setenv(sftp_pkg._ENV_VAR, "asyncssh")
 
@@ -191,6 +201,42 @@ def test_default_backend_cls_class_attribute_wins_over_env(monkeypatch):
     assert isinstance(backend, sftp_pkg.SftpBackend)
 
 
+def test_sftp_scheme_imports_and_resolves_without_paramiko():
+    """Regression: an asyncssh-only install (no paramiko) must still import
+    SftpPath and auto-resolve to the asyncssh backend.
+
+    Runs in a subprocess with ``paramiko`` masked (blocked in sys.modules) so the
+    guard holds even in a CI env where paramiko happens to be installed. Before
+    the fix, ``uri/schemes/sftp/__init__`` imported ``._paramiko`` eagerly, so
+    merely importing ``SftpPath`` raised ModuleNotFoundError without paramiko.
+    """
+    import subprocess
+    import sys
+    import textwrap
+
+    script = textwrap.dedent(
+        """
+        import sys
+        # Make `import paramiko` fail, simulating an asyncssh-only install.
+        sys.modules["paramiko"] = None
+        from pathlib_next.uri.schemes.sftp import SftpPath
+        from pathlib_next.uri.schemes import sftp as pkg
+        sp = SftpPath("sftp://root@h:22/etc/hosts")
+        assert sp.source.host == "h" and sp.path == "/etc/hosts"
+        cls = pkg._resolve_default_backend_cls(reload=True)
+        assert cls.__name__ == "AsyncsshSftpBackend", cls
+        print("OK")
+        """
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, result.stderr
+    assert "OK" in result.stdout
+
+
 def test_explicit_backend_kwarg_wins_over_everything(monkeypatch):
     monkeypatch.setenv(sftp_pkg._ENV_VAR, "asyncssh")
     explicit = backend_mod.AsyncsshSftpBackend()
@@ -219,6 +265,7 @@ def test_asyncssh_backend_supports_lchmod_and_hardlink():
     assert backend.supports_hardlink is True
 
 
+@_needs_paramiko
 def test_paramiko_backend_does_not_support_lchmod_or_hardlink():
     assert sftp_pkg.SftpBackend.supports_lchmod is False
     assert sftp_pkg.SftpBackend.supports_hardlink is False

{pathlib_next-0.8.1 → pathlib_next-0.8.2}/tests/test_smoke.py

@@ -108,12 +108,16 @@ def test_optional_schemes_presence_or_absence():
     except ImportError:
         assert not hasattr(schemes, "HttpPath")
 
-    # Check sftp
-    try:
-        import paramiko  # noqa: F401
-        assert hasattr(schemes, "SftpPath")
-    except ImportError:
-        assert not hasattr(schemes, "SftpPath")
+    # Check sftp: as of 0.8.2 importing SftpPath no longer requires an SSH
+    # backend (paramiko/asyncssh) -- those are resolved lazily at USE time. The
+    # scheme is a UriPath, so its import gate is `uritools` (the `uri` extra);
+    # SftpPath is present exactly when that is importable. Using it without any
+    # SSH backend installed is what raises (covered by the backend-selection
+    # tests), not importing it.
+    import importlib.util as _importutil
+
+    _has_uri = _importutil.find_spec("uritools") is not None
+    assert hasattr(schemes, "SftpPath") == _has_uri
 
     # Check s3 -- S3Path only needs botocore at import time (boto3 itself is
     # a lazy import inside S3Backend.client()), so that's what gates it.