pathlib-next 0.5.0__tar.gz → 0.6.0__tar.gz

{pathlib_next-0.5.0 → pathlib_next-0.6.0}/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-11
+
+### Added (Phase 7a new schemes, stdlib-only, no new deps)
+- `data:` scheme (RFC 2397, `pathlib_next.uri.schemes.data.DataUri`):
+  read-only, no backend/connection -- the entire file content is embedded
+  in the URI (`data:[<mediatype>][;base64],<data>`). `stat().st_size` is
+  the decoded payload length; `iterdir()` raises `NotADirectoryError`
+  (it's always a single file); write operations raise `NotImplementedError`.
+- `ftp:`/`ftps:` scheme (`pathlib_next.uri.schemes.ftp.FtpPath`): full
+  read/write/list access via stdlib `ftplib`, with a thread-keyed LRU
+  connection cache mirroring `sftp.py`. Listing/stat prefer MLSD (RFC
+  3659); servers without it fall back to NLST (listing) and SIZE
+  (file-only stat). Writes buffer in memory and upload via STOR/APPE on
+  `close()`. `chmod()` uses the common but non-standard `SITE CHMOD`
+  extension (may not be supported by every server).
+- `zip:`/`tar:` archive paths (`pathlib_next.uri.schemes.archive`):
+  `<scheme>:<archive-uri>!/<inner-path>` (Java-style `!/` separator,
+  URI form proposed to and confirmed by the user before implementation).
+  The archive half is itself any absolute URI with an explicit scheme, so
+  archives are readable straight off any other backend (`file:`, `http:`,
+  `sftp:`, `ftp:`, `data:`, ...). Read is supported for both schemes.
+  Write is `zip:`-only, and only for brand-new entries in a local (`file:`)
+  outer archive (overwriting/deleting/renaming an existing entry would
+  need a full-archive rewrite -- not implemented, raises
+  `NotImplementedError`). `tar:` auto-detects `.tar.gz`/`.tar.bz2`/`.tar.xz`
+  compression and is always read-only.
+
 ## [0.5.0] - 2026-07-11
 
 ### Fixed (critical -- found while writing Phase 6 examples)
@@ -208,7 +235,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.5.0...HEAD
+[Unreleased]: https://github.com/jose-pr/pathlib_next/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/jose-pr/pathlib_next/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/jose-pr/pathlib_next/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/jose-pr/pathlib_next/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/jose-pr/pathlib_next/releases/tag/v0.4.0

{pathlib_next-0.5.0 → pathlib_next-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pathlib_next
-Version: 0.5.0
+Version: 0.6.0
 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.6.0/docs/guides/schemes.md

@@ -0,0 +1,62 @@
+# Schemes
+
+Capability matrix for every built-in `Path`/`UriPath` implementation. A
+"No" means the method raises `NotImplementedError` (or, for `http:`, isn't
+meaningful for a read-only scheme) -- everything else (name/suffix parsing,
+`glob()`, `walk()`, `copy()`, ...) is derived from these primitives and
+works identically across all of them.
+
+| Capability | `LocalPath` | `file:` (`FileUri`) | `mem:` (`MemPath`) | `http(s):` (`HttpPath`) | `sftp:` (`SftpPath`) | `data:` (`DataUri`) | `ftp(s):` (`FtpPath`) | `zip:` (`ZipUri`) | `tar:` (`TarUri`) |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Read (`read_text`/`read_bytes`/`open`) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| Write (`write_text`/`write_bytes`/`open("w")`) | Yes | Yes | Yes | No | Yes | No | Yes | New entries only, local outer archive only | No |
+| List (`iterdir`) | Yes | Yes | Yes | Yes (scrapes an HTML index) | Yes | No (`NotADirectoryError`) | Yes (MLSD, falls back to NLST) | Yes | Yes |
+| Stat (`stat`, `exists`, `is_dir`, `is_file`, ...) | Yes | Yes | Yes | Yes (via `HEAD`, falls back to `GET`) | Yes | Yes (`st_size` from decoded payload) | Yes (MLSD, falls back to SIZE for files) | Yes | Yes |
+| `mkdir` | Yes | Yes | Yes | No | Yes | No | Yes | Local outer archive only (zero-length `name/` entry) | No |
+| Delete (`unlink`/`rmdir`/`rm`) | Yes | Yes | Yes | No | Yes | No | Yes | No | No |
+| `rename` | Yes | Yes | No (`move()` falls back to copy+unlink) | No | Yes | No | Yes | No | No |
+| `chmod` | Yes | Yes | No | No | Yes (no `follow_symlinks=False`; paramiko has no `lchmod`) | No | Yes (`SITE CHMOD`, server-dependent) | No | No |
+| Extra required | none | none | none | `http` | `sftp` | none (stdlib) | none (stdlib `ftplib`) | none (stdlib `zipfile`) | none (stdlib `tarfile`) |
+
+Notes:
+
+- **`file:`** is a thin `UriPath` wrapper around `LocalPath` -- it has
+  identical capabilities, just addressed by URI instead of a native path.
+- **`mem:` (`MemPath`)** isn't a `UriPath` at all -- it's a plain `Path`
+  subclass (Track A of [Extending](extending.md)), backed by nested dicts
+  (`MemPathBackend`). No `as_uri()` scheme is registered for it; construct
+  it directly via `MemPath(...)`.
+- **`http(s):`** is inherently read-only: there's no portable "create/
+  delete/rename a resource" over plain HTTP. Directory listing depends on
+  the server producing an Apache/nginx-style HTML index that
+  `htmllistparse` can parse (confirmed against Python's own
+  `http.server.SimpleHTTPRequestHandler`).
+- **`sftp:`** has the fullest capability set of the URI schemes (it's a
+  real remote filesystem protocol). Connections are cached per
+  `(backend, source, thread)` (see `pathlib_next.uri.schemes.sftp`).
+- **`data:`** (RFC 2397) has no server or connection at all -- the entire
+  "file" content lives in the URI string itself
+  (`data:[<mediatype>][;base64],<data>`). It's always a single file, never a
+  directory.
+- **`ftp(s):`** uses the same connection-cache pattern as `sftp:` (stdlib
+  `ftplib`, no extra required). Prefers MLSD (RFC 3659) for listing/stat --
+  gives type/size/modify in one round trip -- and falls back to NLST/SIZE on
+  servers that don't support it (that fallback path can't distinguish "file
+  doesn't exist" from "is a directory" for `stat()`, since SIZE only works on
+  files).
+- **`zip:`/`tar:`** address an entry *inside* an archive:
+  `zip:<archive-uri>!/<inner-path>` (Java-style `!/` separator, as in JAR
+  URLs / NIO `ZipFileSystem`). The `<archive-uri>` half is itself any
+  absolute URI with an explicit scheme -- `file:`, `http:`, `sftp:`,
+  `ftp:`, even `data:` -- so an archive is readable straight off any other
+  backend; `zip:file:///backups/site.zip!/index.html` and
+  `zip:sftp://host/nightly.zip!/index.html` both work the same way.
+  `segments`/`name`/`parent`/`glob()`/... all operate on the *inner* path.
+  Writing a brand-new entry (not overwriting/deleting/renaming an existing
+  one -- that would need a full-archive rewrite, not implemented) only
+  works when the outer archive is itself a local `file:` URI; every other
+  outer scheme is read-only. `tar:` (with transparent `.tar.gz`/`.tar.bz2`/
+  `.tar.xz` decompression) is read-only regardless of the outer scheme.
+- See [Divergences from pathlib](../divergences.md) for the "explicitly out
+  of scope" list (`resolve`, `symlink_to`, `owner`, `expanduser`, ...) that
+  applies uniformly across every non-`LocalPath` implementation.

{pathlib_next-0.5.0 → pathlib_next-0.6.0}/pyproject.toml

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

{pathlib_next-0.5.0 → pathlib_next-0.6.0}/src/pathlib_next/uri/schemes/__init__.py

@@ -1,4 +1,8 @@
+from .archive import TarUri as TarUri
+from .archive import ZipUri as ZipUri
+from .data import DataUri as DataUri
 from .file import FileUri as FileUri
+from .ftp import FtpPath as FtpPath
 
 try:
     from .http import HttpPath as HttpPath

pathlib_next-0.6.0/src/pathlib_next/uri/schemes/archive.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import io as _io
+import re as _re
+import tarfile as _tarfile
+import time as _time
+import zipfile as _zipfile
+
+from ...utils.stat import FileStat
+from .. import UriPath
+from .file import FileUri
+
+_SEP = "!/"
+_SCHEME_RE = _re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*:")
+
+
+def _split_archive_path(path: str) -> "tuple[str, str]":
+    """Split `<archive-uri>!/<inner-path>` (Java-style separator, as used
+    for JAR URLs / NIO ZipFileSystem) into its two halves. No separator (or
+    a bare trailing "!") means the archive root."""
+    if _SEP in path:
+        archive, inner = path.split(_SEP, 1)
+    elif path.endswith("!"):
+        archive, inner = path[:-1], ""
+    else:
+        archive, inner = path, ""
+    return archive, inner
+
+
+def _open_outer(archive_uri: str) -> "UriPath":
+    if not _SCHEME_RE.match(archive_uri):
+        raise ValueError(
+            f"Archive URI {archive_uri!r} has no scheme -- prefix it "
+            "explicitly, e.g. 'file:///path/to/archive.zip'."
+        )
+    return UriPath(archive_uri)
+
+
+class _ArchiveBackend:
+    """Lazily opens+caches the archive handle for one outer archive URI.
+    Shared by every `ArchiveUri` instance derived from the same one (backend
+    propagation is the existing `UriPath` machinery -- see `ArchiveUri._init`).
+    NOT deduplicated across independently-constructed top-level `UriPath(...)`
+    strings pointing at the same archive -- derive sibling members via `/`/
+    `joinpath` from a shared instance rather than reparsing the same archive
+    URI twice, especially for writable zips (two separate handles writing
+    the same underlying file can corrupt it)."""
+
+    __slots__ = ("outer", "_handle")
+
+    def __init__(self, outer: "UriPath"):
+        self.outer = outer
+        self._handle = None
+
+    def _open(self):
+        raise NotImplementedError
+
+    @property
+    def handle(self):
+        if self._handle is None:
+            self._handle = self._open()
+        return self._handle
+
+    @property
+    def writable(self) -> bool:
+        return False
+
+    def names(self) -> "list[str]":
+        raise NotImplementedError
+
+    def read_member(self, path: str):
+        raise NotImplementedError
+
+    def member_stat(self, path: str) -> FileStat:
+        raise NotImplementedError
+
+
+class _ZipBackend(_ArchiveBackend):
+    __slots__ = ()
+
+    @property
+    def writable(self) -> bool:
+        # Writing individual entries in place (via ZipFile.open(name, "w"))
+        # only works when we hold the archive open in "a" mode against a
+        # real seekable local file -- not for remote/embedded outer URIs.
+        return isinstance(self.outer, FileUri)
+
+    def _open(self):
+        if self.writable:
+            return _zipfile.ZipFile(str(self.outer.filepath), mode="a")
+        return _zipfile.ZipFile(_io.BytesIO(self.outer.read_bytes()), mode="r")
+
+    def names(self):
+        return self.handle.namelist()
+
+    def read_member(self, path):
+        return self.handle.open(path, "r")  # raises KeyError if missing
+
+    def write_member(self, path: str, data: bytes):
+        # zipfile only persists the central directory to disk when the
+        # *archive* (not just the entry) is closed -- close and drop the
+        # cached handle so both this backend's next operation and any
+        # independently-opened ZipUri see the write.
+        self.handle.writestr(path, data)
+        self.handle.close()
+        self._handle = None
+
+    def member_stat(self, path):
+        info = self.handle.getinfo(path)
+        mtime = int(_time.mktime((*info.date_time, 0, 0, -1))) if info.date_time else 0
+        return FileStat(st_size=info.file_size, st_mtime=mtime, is_dir=path.endswith("/"))
+
+
+class _TarBackend(_ArchiveBackend):
+    __slots__ = ()
+
+    def _open(self):
+        return _tarfile.open(fileobj=_io.BytesIO(self.outer.read_bytes()), mode="r:*")
+
+    def names(self):
+        return self.handle.getnames()
+
+    def read_member(self, path):
+        try:
+            member = self.handle.getmember(path)
+        except KeyError:
+            raise
+        f = self.handle.extractfile(member)
+        if f is None:
+            raise IsADirectoryError(path)
+        return f
+
+    def member_stat(self, path):
+        info = self.handle.getmember(path)
+        return FileStat(st_size=info.size, st_mtime=int(info.mtime), is_dir=info.isdir())
+
+
+class ArchiveUri(UriPath):
+    """Common base for `zip:`/`tar:` archive paths:
+    `<scheme>:<archive-uri>!/<inner-path>` (Java-style separator; the
+    `<archive-uri>` half is itself any absolute URI with an explicit scheme
+    -- `file:`, `http:`, `sftp:`, `ftp:`, ... -- so archives are readable
+    straight off any existing backend). `segments`/`name`/`parent`/`glob`/
+    ... all operate on the *inner* path; the outer archive handle is the
+    `backend` (`_ZipBackend`/`_TarBackend`), propagated through the normal
+    backend machinery to every path derived from this one."""
+
+    __slots__ = ()
+    _backend_cls: type = None
+
+    def _init(self, source, path, query, fragment, /, **kwargs):
+        backend = kwargs.get("backend", None) or self._backend
+        if backend is None:
+            # Fresh top-level construction (e.g. UriPath("zip:...!/...")) --
+            # `path` is still the raw "<archive-uri>!/<inner>" string.
+            archive_str, inner = _split_archive_path(path)
+            backend = self._backend_cls(_open_outer(archive_str))
+        else:
+            # Derived instance (with_segments/joinpath/_make_child_relpath)
+            # -- backend already known, `path` is already just the inner
+            # path (no "archive!/" prefix to strip).
+            inner = path
+        kwargs["backend"] = backend
+        super()._init(source, inner, query, fragment, **kwargs)
+
+    def as_uri(self, /, sanitize=False):
+        outer_uri = self.backend.outer.as_uri(sanitize=sanitize)
+        return f"{self.source.scheme}:{outer_uri}!/{self.path}"
+
+    def _names(self):
+        return self.backend.names()
+
+    def _listdir(self):
+        prefix = f"{self.path}/" if self.path else ""
+        seen = set()
+        for name in self._names():
+            if not name.startswith(prefix):
+                continue
+            rest = name[len(prefix) :]
+            if not rest:
+                continue
+            child = rest.split("/", 1)[0]
+            if child and child not in seen:
+                seen.add(child)
+                yield child
+
+    def stat(self, *, follow_symlinks=True):
+        path = self.path
+        if path == "":
+            return FileStat(is_dir=True)
+        names = self._names()
+        if path in names:
+            return self.backend.member_stat(path)
+        dirmarker = f"{path}/"
+        if dirmarker in names or any(n.startswith(dirmarker) for n in names):
+            return FileStat(is_dir=True)
+        raise FileNotFoundError(self)
+
+    def _open(self, mode="r", buffering=-1):
+        if "r" in mode:
+            try:
+                return self.backend.read_member(self.path)
+            except KeyError as error:
+                raise FileNotFoundError(self) from error
+        raise NotImplementedError(f"open(mode={mode!r}) on {self.source.scheme}:")
+
+
+class _ZipWriteStream(_io.BytesIO):
+    """Buffers a new entry's content in memory; on close(), writes it via
+    `writestr()` and flushes+reopens the archive (see
+    `_ZipBackend.write_member`)."""
+
+    def __init__(self, backend: "_ZipBackend", path: str):
+        super().__init__()
+        self._backend = backend
+        self._path = path
+
+    def close(self):
+        if not self.closed:
+            self._backend.write_member(self._path, self.getvalue())
+        super().close()
+
+
+class ZipUri(ArchiveUri):
+    """`zip:` scheme. Read/write: writing a new entry works when the outer
+    archive is a local `file:` URI (opened in `zipfile`'s "a" -- append --
+    mode, so existing entries are untouched); every other outer scheme is
+    read-only (fetched fully into memory first). Overwriting/deleting/
+    renaming an existing entry is not implemented (would require rewriting
+    the whole archive) -- only adding new entries and (for directories)
+    zero-length `"name/"` marker entries."""
+
+    __SCHEMES = ("zip",)
+    __slots__ = ()
+    _backend_cls = _ZipBackend
+
+    def _open(self, mode="r", buffering=-1):
+        if "r" in mode:
+            return super()._open(mode, buffering)
+        if not self.backend.writable:
+            raise NotImplementedError(
+                "zip: write support requires a local (file:) outer archive"
+            )
+        if mode not in ("w", "x"):
+            raise NotImplementedError(f"open(mode={mode!r})")
+        if mode == "x" and self.exists():
+            raise FileExistsError(self)
+        return _ZipWriteStream(self.backend, self.path)
+
+    def _mkdir(self, mode):
+        if not self.backend.writable:
+            raise NotImplementedError(
+                "zip: write support requires a local (file:) outer archive"
+            )
+        if self.exists():
+            raise FileExistsError(self)
+        self.backend.write_member(f"{self.path}/", b"")
+
+
+class TarUri(ArchiveUri):
+    """`tar:` scheme (also handles `.tar.gz`/`.tar.bz2`/`.tar.xz` via
+    `tarfile`'s auto-detected "r:*" mode). Read-only."""
+
+    __SCHEMES = ("tar",)
+    __slots__ = ()
+    _backend_cls = _TarBackend

pathlib_next-0.6.0/src/pathlib_next/uri/schemes/data.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import io as _io
+import urllib.parse as _urlparse
+from base64 import b64decode as _b64decode
+
+from ...utils.stat import FileStat
+from .. import UriPath
+
+_DEFAULT_MEDIATYPE = "text/plain;charset=US-ASCII"
+
+
+class DataUri(UriPath):
+    """`data:` scheme (RFC 2397): a read-only "file" whose entire content is
+    embedded in the URI itself (`data:[<mediatype>][;base64],<data>`) -- no
+    filesystem, no directories, no backend/connection. Percent-encoded
+    reserved characters (`?`/`#`) in the payload are only decoded correctly
+    if the URI was built with them escaped, per RFC 2397/3986."""
+
+    __SCHEMES = ("data",)
+    __slots__ = ()
+
+    @property
+    def _header(self) -> str:
+        header, _, _ = self.path.partition(",")
+        return header
+
+    @property
+    def _is_base64(self) -> bool:
+        return self._header.rsplit(";", 1)[-1].strip().lower() == "base64"
+
+    @property
+    def mediatype(self) -> str:
+        header = self._header
+        if not header:
+            return _DEFAULT_MEDIATYPE
+        if self._is_base64:
+            header = header.rsplit(";", 1)[0]
+        return header or _DEFAULT_MEDIATYPE
+
+    def _content(self) -> bytes:
+        header, sep, data = self.path.partition(",")
+        if not sep:
+            raise FileNotFoundError(self)
+        if self._is_base64:
+            return _b64decode(_urlparse.unquote_to_bytes(data))
+        return _urlparse.unquote_to_bytes(data)
+
+    def stat(self, *, follow_symlinks=True):
+        return FileStat(st_size=len(self._content()), is_dir=False)
+
+    def _open(self, mode="r", buffering=-1):
+        if "r" not in mode:
+            raise NotImplementedError("data: URIs are read-only")
+        return _io.BytesIO(self._content())
+
+    def _listdir(self):
+        raise NotADirectoryError(self)

pathlib_next-0.6.0/src/pathlib_next/uri/schemes/ftp.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import datetime as _dt
+import ftplib as _ftplib
+import io as _io
+import threading as _thread
+import typing as _ty
+
+from ... import utils as _utils
+from ...utils.stat import FileStat
+from .. import Source, Uri, UriPath
+
+
+class BaseFtpBackend(object):
+    """Protocol for obtaining a connected+logged-in `ftplib.FTP` (or
+    `FTP_TLS`) for a `Source`. Subclass this to plug in custom connection
+    handling (e.g. tests mock it directly, no real server);
+    `FtpBackend` is the real implementation."""
+
+    __slots__ = ()
+
+    @_utils.notimplemented
+    def client(self, source: Source, tls: bool) -> "_ftplib.FTP": ...
+
+
+class FtpBackend(BaseFtpBackend):
+    """Connects via stdlib `ftplib.FTP` (`ftp:`) or `ftplib.FTP_TLS`
+    (`ftps:`, with `PROT P` for an encrypted data channel too)."""
+
+    __slots__ = ("timeout",)
+
+    def __init__(self, timeout: float = None) -> None:
+        self.timeout = timeout
+
+    def client(self, source: Source, tls: bool):
+        cls = _ftplib.FTP_TLS if tls else _ftplib.FTP
+        client = cls(timeout=self.timeout)
+        client.connect(str(source.host), source.port or 21)
+        user, password = source.parsed_userinfo()
+        client.login(user or "anonymous", password or "")
+        if tls:
+            client.prot_p()
+        client.set_pasv(True)
+        return client
+
+
+def _create_ftpclient(backend: BaseFtpBackend, source: Source, tls: bool, thread_id: int):
+    return backend.client(source, tls)
+
+
+_CACHED_CLIENTS = _utils.LRU(_create_ftpclient, maxsize=128)
+
+
+def _parse_mlsd_time(value: str) -> int:
+    # MLSD "modify" fact: YYYYMMDDHHMMSS[.sss], always UTC (RFC 3659).
+    try:
+        return int(
+            _dt.datetime.strptime(value[:14], "%Y%m%d%H%M%S").timestamp()
+        )
+    except ValueError:
+        return 0
+
+
+class _FtpWriteStream(_io.BytesIO):
+    """Buffers the whole write in memory, uploads on close() via
+    STOR/APPE. Simple and works with any ftplib client, at the cost of
+    holding the full file content in memory for the duration of the write."""
+
+    def __init__(self, client: "_ftplib.FTP", path: str, append: bool = False):
+        super().__init__()
+        self._client = client
+        self._path = path
+        self._cmd = "APPE" if append else "STOR"
+
+    def close(self):
+        if not self.closed:
+            self.seek(0)
+            self._client.storbinary(f"{self._cmd} {self._path}", self)
+        super().close()
+
+
+class FtpPath(UriPath):
+    """`ftp:`/`ftps:` scheme: full read/write access via stdlib `ftplib`,
+    with a thread-keyed LRU connection cache (`_CACHED_CLIENTS`, mirroring
+    `sftp.py`). Directory listing and stat prefer MLSD (RFC 3659 -- gives
+    type/size/modify facts in one round trip); servers that don't support it
+    fall back to NLST for listing (names only) and SIZE for file stat
+    (no portable "not found vs. is a directory" distinction in that path)."""
+
+    __SCHEMES = ("ftp", "ftps")
+    __slots__ = ()
+
+    if _ty.TYPE_CHECKING:
+        backend: BaseFtpBackend
+
+    def _initbackend(self):
+        return FtpBackend()
+
+    @property
+    def _tls(self):
+        return self.source.scheme == "ftps"
+
+    @property
+    def _ftpclient(self) -> "_ftplib.FTP":
+        thread_id = _thread.get_ident()
+        client = _CACHED_CLIENTS(self.backend, self.source, self._tls, thread_id)
+        try:
+            client.voidcmd("NOOP")
+        except (OSError, EOFError, _ftplib.error_temp, _ftplib.error_proto):
+            client = _CACHED_CLIENTS.invalidate(
+                self.backend, self.source, self._tls, thread_id
+            )
+        return client
+
+    def _mlsd_entry(self):
+        """This entry's MLSD facts from its parent's listing, or None if
+        not found or the server doesn't support MLSD."""
+        parent = self.path.rsplit("/", 1)[0] or "/"
+        try:
+            for name, facts in self._ftpclient.mlsd(parent):
+                if name == self.name:
+                    return facts
+        except _ftplib.error_perm:
+            return None
+        return None
+
+    def _listdir(self):
+        try:
+            for name, _facts in self._ftpclient.mlsd(self.path):
+                if name not in (".", ".."):
+                    yield name
+        except _ftplib.error_perm:
+            for name in self._ftpclient.nlst(self.path):
+                base = name.rsplit("/", 1)[-1]
+                if base not in (".", ".."):
+                    yield base
+
+    def stat(self, *, follow_symlinks=True):
+        facts = self._mlsd_entry()
+        if facts is not None:
+            kind = facts.get("type", "file")
+            size = int(facts.get("size", 0) or 0)
+            modify = facts.get("modify")
+            mtime = _parse_mlsd_time(modify) if modify else 0
+            return FileStat(
+                st_size=size, st_mtime=mtime, is_dir=kind in ("dir", "cdir", "pdir")
+            )
+        # MLSD unsupported (or entry not found via it) -- SIZE only works
+        # for files, so this can't tell "missing" apart from "is a
+        # directory"; either way there's no file to report a size for.
+        try:
+            size = self._ftpclient.size(self.path)
+        except _ftplib.error_perm as error:
+            raise FileNotFoundError(self) from error
+        if size is None:
+            raise FileNotFoundError(self)
+        return FileStat(st_size=size, is_dir=False)
+
+    def _open(self, mode="r", buffering=-1):
+        if "r" in mode:
+            buf = _io.BytesIO()
+            try:
+                self._ftpclient.retrbinary(f"RETR {self.path}", buf.write)
+            except _ftplib.error_perm as error:
+                raise FileNotFoundError(self) from error
+            buf.seek(0)
+            return buf
+        if mode not in ("w", "x", "a"):
+            raise NotImplementedError(f"open(mode={mode!r})")
+        if mode == "x" and self.exists():
+            raise FileExistsError(self)
+        return _FtpWriteStream(self._ftpclient, self.path, append=(mode == "a"))
+
+    def _mkdir(self, mode):
+        try:
+            self._ftpclient.mkd(self.path)
+        except _ftplib.error_perm as error:
+            if self.exists():
+                raise FileExistsError(self) from error
+            raise FileNotFoundError(self) from error
+
+    def unlink(self, missing_ok=False):
+        try:
+            self._ftpclient.delete(self.path)
+        except _ftplib.error_perm as error:
+            if missing_ok and not self.exists():
+                return
+            raise FileNotFoundError(self) from error
+
+    def rmdir(self):
+        self._ftpclient.rmd(self.path)
+
+    def rename(self, target: "FtpPath | Uri | str"):
+        # A plain str target is a sibling rename (relative to self's
+        # parent), matching sftp.py's rename() semantics.
+        if not isinstance(target, Uri):
+            target = Uri(self.parent, target)
+        self._ftpclient.rename(self.path, target.path)
+
+    def chmod(self, mode, *, follow_symlinks=True):
+        # SITE CHMOD is a common but non-standard FTP extension; not every
+        # server supports it (ftplib.error_perm propagates uncaught if so).
+        if not follow_symlinks:
+            raise NotImplementedError("chmod(follow_symlinks=False)")
+        self._ftpclient.voidcmd(f"SITE CHMOD {mode:o} {self.path}")