pathapi-uri 0.1.0__py3-none-any.whl

uripath/schemes/_file.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import os as _os
+
+from pathapi import FsPathLike
+from pathapi import LocalPath as _Local
+from ..source import Source
+from ..source import is_drive
+from ._delegate import DelegatingURIPath
+
+
+class FileURIPath(DelegatingURIPath):
+    """`file:` scheme: a `URIPath` wrapping a `LocalPath` (`filepath`),
+    delegating all I/O to it."""
+
+    __SCHEMES = ("file",)
+    __slots__ = ()
+    _DELEGATED = ("_scandir", "_chown", "_utime", "unlink", "rmdir", "chmod")
+    _RELABEL = False
+
+    def _make_core(self):
+        return _Local(self.__fspath__())
+
+    @property
+    def filepath(self):
+        return self._core_path
+
+    def _unc_share(self) -> "str | None":
+        """The share of a UNC path ("/share" under a named host), else None.
+        On Windows a named host is a server and `//server/share` is the anchor
+        of everything below it. Only the text is looked at; nothing is
+        resolved."""
+        host = self.source.host
+        segments = self.segments
+        if (
+            _os.name == "nt"
+            and host
+            and not (isinstance(host, str) and host.lower() == "localhost")
+            and segments[:1] == ("",)
+            and len(segments) > 1
+            and segments[1]
+        ):
+            return "/" + segments[1]
+        return None
+
+    @property
+    def parent(self):
+        if _os.name == "nt" and is_drive(self.path.removeprefix("/")):
+            # A bare drive is its own parent, as in `PureWindowsPath("C:")`.
+            return self
+        share = self._unc_share()
+        if share is not None:
+            if self.path.rstrip("/") == share:
+                return self
+            parent = super().parent
+            if parent.path == share:
+                # The parent of a top-level name in a share is the share root.
+                return parent.with_path(share + "/")
+            return parent
+        parent = super().parent
+        path = parent.path
+        if _os.name == "nt" and is_drive(path.removeprefix("/")):
+            # "C:" alone is drive-RELATIVE (the current directory on C:); the
+            # parent of a top-level "C:/Windows" is the drive root "C:/".
+            return parent.with_path(path + "/")
+        return parent
+
+    def _anchor_segments(self):
+        # The drive is the anchor of "C:/a/b" (and "/C:/a/b" under a host),
+        # so `parents` ends at the drive root "C:/" like `parent` does; the
+        # share is the anchor of a UNC path.
+        segments = self.segments
+        if _os.name == "nt":
+            if segments[:1] and is_drive(segments[0]):
+                return segments[:1]
+            if segments[:1] == ("",) and len(segments) > 1 and is_drive(segments[1]):
+                return segments[:2]
+            if self._unc_share() is not None:
+                return segments[:2]
+        return super()._anchor_segments()
+
+    def with_segments(self, *segments):
+        # A Windows path string separates its names with backslashes.
+        if _os.name == "nt":
+            segments = tuple(
+                item.replace("\\", "/") if isinstance(item, str) else item
+                for item in segments
+            )
+        return super().with_segments(*segments)
+
+    def _join_decoded(self, key: str):
+        # A Windows path string separates its names with backslashes;
+        # elsewhere a backslash is an ordinary character of a file name.
+        if _os.name == "nt" and "\\" in key:
+            key = key.replace("\\", "/")
+        return super()._join_decoded(key)
+
+    def _is_absolute_decoded(self, path: str) -> bool:
+        """A drive path restarts a join, as `PureWindowsPath` does: joining
+        "C:/Temp/x" onto "D:/proj" gives "C:/Temp/x", not a child of it.
+        `is_absolute()` already answers True for such a path, so the join
+        has to agree with it."""
+        if _os.name == "nt":
+            drive, sep, _ = path.partition("/")
+            if is_drive(drive):
+                return bool(sep)
+        return super()._is_absolute_decoded(path)
+
+    def is_absolute(self):
+        """Also True for a Windows drive path ("C:/x"), which `_init()`
+        stores without the "/" a URI path gets in front of it. "C:" alone is
+        drive-relative, as for `PureWindowsPath`."""
+        path = self.path
+        if _os.name == "nt":
+            drive, sep, _ = path.partition("/")
+            if is_drive(drive):
+                return bool(sep)
+        return super().is_absolute()
+
+    def _init(
+        self,
+        source: Source,
+        path: str,
+        query: str,
+        fragment: str,
+        /,
+        **kwargs,
+    ):
+        # With a host ("file://localhost/C:/x") the "/" before the drive
+        # stays: a path under an authority must start with "/", and without
+        # it str()/repr()/hash() raised ValueError. `__fspath__` drops it.
+        if _os.name == "nt" and path and path[0] == "/" and not source.host:
+            root, *_ = path[1:].split("/", maxsplit=1)
+            if root and root[-1] == ":":
+                path = path.removeprefix("/")
+        super()._init(source, path, query, fragment, **kwargs)
+
+    @classmethod
+    def _format_parsed_parts(cls, source, path, query, fragment, /, sanitize=True):
+        if _os.name == "nt" and is_drive(path.partition("/")[0]):
+            # Render "C:/x" as "file:/C:/x", the spelling `URI` itself
+            # parses it to, so `URI(p) == URIPath(p)` for a local path.
+            path = "/" + path
+        return super()._format_parsed_parts(
+            source, path, query, fragment, sanitize=sanitize
+        )
+
+    def _listdir(self):
+        yield from _os.listdir(self.filepath)
+
+    def is_junction(self) -> bool:
+        return self.filepath.is_junction()
+
+    def is_mount(self) -> bool:
+        return self.filepath.is_mount()
+
+    def stat(self, *, follow_symlinks=True):
+        # LocalPath.stat() itself shims the 3.10+-only follow_symlinks= kwarg
+        # for pathlib.Path (see fspath.py), so just delegate.
+        return self.filepath.stat(follow_symlinks=follow_symlinks)
+
+    def open(self, mode="r", buffering=-1, encoding=None, errors=None, newline=None):
+        return self.filepath.open(mode, buffering, encoding, errors, newline)
+
+    def mkdir(self, mode=511, parents=False, exist_ok=False):
+        return self.filepath.mkdir(mode, parents, exist_ok)
+
+    def touch(self, mode=None, exist_ok=True):
+        # pathlib's touch: the mode goes through os.open(), so the umask
+        # applies, and an existing file's mtime is bumped. The generic
+        # Path.touch can do neither.
+        if mode is None:
+            return self.filepath.touch(exist_ok=exist_ok)
+        return self.filepath.touch(mode, exist_ok)
+
+    def rename(self, target: FsPathLike | str):
+        # Through `_rename_target()` like every scheme: a relative str is a sibling rename
+        # (not relative to the process cwd), a local path is accepted, and a remote URI
+        # raises NotImplementedError so move() copies.
+        dest = self._rename_target(target)
+        if not isinstance(dest, FileURIPath):
+            dest = self._from_parsed_parts(
+                dest.source or self.source, dest.path, None, None
+            )
+        self.filepath.rename(dest.filepath)
+        return dest

uripath/schemes/_ftp.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import logging as _logging
+import threading as _thread
+import typing as _ty
+import weakref as _weakref
+
+import netimps as _netimps
+
+from pathapi.ftp import DEFAULT_TIMEOUT as DEFAULT_TIMEOUT
+from pathapi.ftp import BaseFTPBackend, FTPBackend, FTPPath
+from pathapi.providers import notimplemented as _notimplemented
+from .._uri import URI
+from ..source import Source, fold_host
+from ._delegate import DelegatingURIPath
+
+if _ty.TYPE_CHECKING:
+    import ssl as _ssl
+
+_log = _logging.getLogger(__name__)
+
+
+class BaseFTPURIBackend(object):
+    """Protocol for obtaining a connected+logged-in FTP client (or
+    its TLS variant) for a `Source`. Subclass this to plug in custom connection
+    handling (e.g. tests mock it directly, no real server);
+    `FTPURIBackend` is the real implementation. A path to each endpoint
+    (`Source` and `tls`) runs on a core `pathapi.ftp.BaseFTPBackend`
+    that asks `client()` for its connections.
+
+    A context manager: leaving the block calls `close()`. One backend may be
+    shared between threads; each thread keeps its own connection per server."""
+
+    # Weakly referenceable so `URIPath` can record which backends a path
+    # derived for itself (see `URIPath._supplied_backend()`).
+    __slots__ = ("__weakref__",)
+
+    @_notimplemented
+    def client(self, source: Source, tls: bool) -> "_ty.Any":
+        """The connected, logged-in client for `source`; `tls` asks for `ftps:`."""
+
+    def close(self) -> None:
+        """Closes every control connection the paths of this backend hold,
+        whichever thread opened it; one a command is running on closes when
+        that command ends. Harmless when called again; a later use connects
+        afresh."""
+        for endpoint in _endpoints_of(self):
+            endpoint.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+
+class FTPURIBackend(BaseFTPURIBackend):
+    """Connects via the stdlib FTP client (`ftp:`) or its TLS variant
+    (`ftps:`, with `PROT P` for an encrypted data channel too).
+
+    `timeout` (seconds, default `DEFAULT_TIMEOUT` = 30) bounds connect,
+    every reply and every transfer read; `None` blocks forever.
+
+    `ftps:` verifies the server certificate and host name by default
+    (`ssl.create_default_context()`), before `USER`/`PASS` are sent. To
+    trust a private CA or a self-signed certificate, pass your own
+    `ssl_context` (e.g. `ssl.create_default_context(cafile=...)`). To turn
+    verification off entirely -- accepting any certificate, so anyone on
+    the network path can read the password -- pass `verify=False`.
+    `ssl_context` wins over `verify` when both are given. Data connections
+    reuse the control connection's TLS session."""
+
+    __slots__ = ("timeout", "ssl_context", "verify")
+
+    def __init__(
+        self,
+        timeout: "float | None" = DEFAULT_TIMEOUT,
+        ssl_context: "_ssl.SSLContext | None" = None,
+        verify: bool = True,
+    ) -> None:
+        self.timeout = timeout
+        self.ssl_context = ssl_context
+        self.verify = verify
+        if not verify and ssl_context is None:
+            _log.warning(
+                "FTPURIBackend(verify=False): TLS certificates are not verified"
+            )
+
+    def client(self, source: Source, tls: bool):
+        user, password = source.parsed_userinfo()
+        return FTPBackend(
+            str(source.host),
+            source.port or _netimps.get_default_port("ftp"),
+            user=user,
+            password=password,
+            tls=tls,
+            timeout=self.timeout,
+            ssl_context=self.ssl_context,
+            verify=self.verify,
+        ).client()
+
+
+_DEFAULT_BACKEND = FTPURIBackend()
+"""The backend every `FTPURIPath` built without `backend=` shares, so separately
+constructed paths to one server reuse one connection per thread instead of
+opening (and keeping) one each."""
+
+
+class _EndpointBackend(BaseFTPBackend):
+    """The core backend of one endpoint of a `BaseFTPURIBackend`: its connections
+    are the ones the owner's `client(source, tls)` opens, and its endpoint is
+    the `Source`, so paths to one server through one owner share them."""
+
+    __slots__ = ("owner", "source", "tls", "endpoint")
+
+    def __init__(self, owner: BaseFTPURIBackend, source: Source, tls: bool):
+        self.owner = owner
+        self.source = source
+        self.tls = tls
+        # The key of the connections: `ftp://NAS/` and `ftp://nas/` are one server.
+        self.endpoint = _endpoint(source)
+
+    def client(self):
+        return self.owner.client(self.source, self.tls)
+
+
+def _endpoint(source: Source) -> Source:
+    """`source` with its host name folded, to key what is shared per server."""
+    return source._replace(host=fold_host(source.host))
+
+
+_ENDPOINTS: "_weakref.WeakValueDictionary[tuple, _EndpointBackend]" = (
+    _weakref.WeakValueDictionary()
+)
+_ENDPOINTS_LOCK = _thread.Lock()
+
+
+def _endpoint_backend(owner: BaseFTPURIBackend, source: Source, tls: bool):
+    """The one core backend for `owner`, `source` and `tls`, while any path or
+    cached connection holds it. The owner is held by the entry, so its `id`
+    names it for as long as the entry lives."""
+    key = (id(owner), _endpoint(source), tls)
+    with _ENDPOINTS_LOCK:
+        found = _ENDPOINTS.get(key)
+        if found is None:
+            found = _ENDPOINTS[key] = _EndpointBackend(owner, source, tls)
+        return found
+
+
+def _endpoints_of(owner: BaseFTPURIBackend) -> "list[_EndpointBackend]":
+    """The core backends that `owner` has made and that something still holds."""
+    with _ENDPOINTS_LOCK:
+        return [found for key, found in list(_ENDPOINTS.items()) if key[0] == id(owner)]
+
+
+class FTPURIPath(DelegatingURIPath):
+    """`ftp:`/`ftps:` scheme: full read/write access via the stdlib FTP client,
+    done by a `pathapi.ftp.FTPPath` on the connections of `backend`
+    (a thread-keyed LRU cache; a thread's connections close when it ends). A
+    listing prefers MLSD (RFC 3659 -- type/size/modify facts in one round
+    trip) and a stat MLST of the entry itself where FEAT lists it, else its
+    parent's MLSD; servers that don't support them fall back to NLST for
+    listing (names only) and SIZE/CWD for stat (no portable "not found vs. is
+    a directory" distinction in that path)."""
+
+    __SCHEMES = ("ftp", "ftps")
+    __slots__ = ()
+    _DELEGATED = (
+        "_scandir",
+        "_listdir",
+        "_open",
+        "_mkdir",
+        "unlink",
+        "rmdir",
+        "chmod",
+        "_utime",
+    )
+
+    if _ty.TYPE_CHECKING:
+        backend: BaseFTPURIBackend
+
+    def _initbackend(self):
+        return _DEFAULT_BACKEND
+
+    def _make_core(self) -> FTPPath:
+        source = self.source
+        backend = _endpoint_backend(self.backend, source, source.scheme == "ftps")
+        return FTPPath(self.path or "/", backend=backend)
+
+    def rename(self, target: "FTPURIPath | URI | str"):
+        # A plain str target is a sibling rename (relative to self's
+        # parent), matching sftp.py's rename() semantics.
+        target = self._rename_target(target)
+        destination = self.with_path(target.path)
+        core = self._core_path
+        moved = core.with_segments(target.path or "/")
+        with self._delegated((str(moved), str(destination))):
+            core.rename(moved)
+        # pathlib returns the new path.
+        return destination

uripath/schemes/_http/__init__.py

@@ -0,0 +1,4 @@
+"""HTTP for `http:` and `dav:`, on the transport of `pathapi.http`. Private: the public names are exported
+by `uripath.schemes`."""
+
+from __future__ import annotations

uripath/schemes/_http/_backend.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import typing as _ty
+
+from pathapi.http import HTTPClient, HTTPResponse, split_userinfo
+
+from ..._version import __version__
+from .._path import DerivedBackend
+from . import _settings
+
+if _ty.TYPE_CHECKING:
+    from ._path import HTTPURIPath
+
+
+_UNSET = object()
+"""The `timeout` of a call that did not give one: the backend's own."""
+
+
+class HTTPBackend(HTTPClient):
+    """The transport and the settings shared by an `HTTPURIPath` tree (see
+    `with_transport()` and `with_session()`): a `pathapi.http.HTTPClient`
+    that takes a path or a URL for its address and adds `write_method` and
+    `append_mode`.
+
+    `transport` is any object with a `send()` method as
+    `pathapi.http.HTTPTransport.send()`; without one the backend builds the
+    built-in `HTTPTransport` on first use and closes it with `close()` or at the
+    end of a `with` block. A transport it was given stays the caller's.
+    `headers` are sent with every request, request-specific headers merged
+    over them by name; every request gets `timeout=(10, 60)` seconds unless
+    `timeout` here or in the call says otherwise (`None` waits without limit).
+    URL userinfo (`http://user:password@host/`) is never sent inside the
+    request URL: it is stripped and sent as an `Authorization: Basic` header
+    unless `headers` or the call name one.
+
+    The backend, through `HTTPClient`, follows redirects. `GET`, `HEAD` and
+    `OPTIONS` follow up to 30; a redirect that changes the scheme, host or
+    port drops `Authorization` (and nothing else). Any other method
+    (`PROPFIND`, `PUT`, `PATCH`, `DELETE`, `MKCOL`, `MOVE`, a `write_method`
+    such as `POST`) is sent without following: a 307 or 308 (for `PROPFIND` also
+    a 301, 302 or 303) to the same scheme, host and port is sent once more
+    with the same method and body, and any other 3xx, a redirect to another
+    origin or a second redirect raises `OSError(EIO)`."""
+
+    __slots__ = ("write_method", "append_mode")
+
+    def __init__(
+        self,
+        transport=None,
+        *,
+        headers=None,
+        timeout=_settings.DEFAULT_TIMEOUT,
+        write_method: str = "PUT",
+        append_mode: str = "rewrite",
+    ):
+        super().__init__(
+            transport,
+            headers=headers,
+            timeout=timeout,
+            user_agent=f"uripath/{__version__}",
+        )
+        self.write_method = write_method
+        self.append_mode = append_mode
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(write_method={self.write_method!r})"
+
+    def request(
+        self,
+        method,
+        uri: "HTTPURIPath|str",
+        *,
+        data=None,
+        headers=None,
+        stream: bool = False,
+        allow_redirects=None,
+        timeout=_UNSET,
+    ) -> HTTPResponse:
+        """Send `method` to `uri` and return the final response. A `data`
+        that is not `bytes` (a file, an iterable) cannot be sent twice, so it
+        is not re-sent after a redirect or a dropped connection.
+        `allow_redirects=False` returns the first answer of a `GET`, `HEAD`
+        or `OPTIONS` as it is. `ValueError` for a URL or header with a control
+        character, before anything is sent.
+
+        With `stream=False` the body is read before this returns, and a decoded
+        body over `pathapi.http.MAX_REPLY_BYTES` is `OSError(EFBIG)`; with
+        `stream=True` the caller reads it, and closes the response."""
+        url, auth = split_userinfo(uri if isinstance(uri, str) else uri.as_uri(False))
+        return super().request(
+            method,
+            url,
+            data=data,
+            headers=headers,
+            stream=stream,
+            allow_redirects=allow_redirects,
+            timeout=self.timeout if timeout is _UNSET else timeout,
+            auth=auth,
+        )
+
+    def redirect(
+        self,
+        method,
+        uri: "HTTPURIPath|str",
+        resp: HTTPResponse,
+        *,
+        headers=None,
+        stream: bool = False,
+        timeout=_UNSET,
+    ) -> HTTPResponse:
+        """Send `method` to where `resp`, the answer to a request for `uri`,
+        redirects to, and follow what it redirects to in turn. The request
+        carries what `uri` is sent with, except that `Authorization` is left
+        off whenever it goes to another scheme, host or port than `uri`'s.
+        A redirect with no usable `Location` is `OSError(EIO)`."""
+        url, auth = split_userinfo(uri if isinstance(uri, str) else uri.as_uri(False))
+        return super().redirect(
+            method,
+            url,
+            resp,
+            headers=headers,
+            stream=stream,
+            timeout=self.timeout if timeout is _UNSET else timeout,
+            auth=auth,
+        )
+
+
+class _DerivedHTTPBackend(HTTPBackend, DerivedBackend):
+    """What `HTTPURIPath._initbackend()` returns: the class itself says the path
+    derived this backend for itself (see `URIPath._supplied_backend()`)."""
+
+    __slots__ = ()

uripath/schemes/_http/_headers.py

@@ -0,0 +1,8 @@
+"""Headers the HTTP schemes send for their own purposes."""
+
+from __future__ import annotations
+
+_IDENTITY_ENCODING = {"Accept-Encoding": "identity"}
+"""Sent on content GETs and `stat()` probes: a transport advertises
+gzip/deflate by default, and a stored blob must not come back as its encoded
+form, while `Content-Length` would count the encoded bytes."""