pathapi-uri 0.1.0__py3-none-any.whl

uripath/query.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import collections.abc as _abc
+import typing as _ty
+
+from . import _rfc3986
+from .source import ERRORS
+
+if _ty.TYPE_CHECKING:
+    from typing import TypeAlias
+else:
+    TypeAlias = _ty.Any
+
+__all__ = ["Query", "QueryLike"]
+
+# The sub-delimiters, ":", "@", "/" and "?" (RFC 3986 3.4) stay literal in a query.
+_SAFE_QUERY = "!$&'()*+,;=:@/?"
+
+
+def _querylist(
+    items: _ty.Sequence[_ty.Tuple[str, _ty.Any]], sep: str, encoding: str
+) -> str:
+    # Escaped in every name and value: the separator; "=", which ends a name
+    # ({"a=b": "c"} would decode as ("a", "b=c")); and "+", which a form-urlencoded
+    # reader takes for a space (a base64 signature or "+00:00" would arrive altered).
+    safe = _SAFE_QUERY.replace(sep, "").replace("=", "").replace("+", "")
+    name_safe = safe
+    terms = []
+    for key, value in items:
+        name = _rfc3986.encode(key, name_safe, encoding=encoding)
+        if value is None:
+            terms.append(name)
+        elif isinstance(value, (bytes, str)):
+            terms.append(name + "=" + _rfc3986.encode(value, safe, encoding=encoding))
+        else:
+            terms.append(
+                name + "=" + _rfc3986.encode(str(value), safe, encoding=encoding)
+            )
+    return sep.join(terms)
+
+
+def _querydict(mapping: _ty.Mapping[str, _ty.Any], sep: str, encoding: str) -> str:
+    items = []
+    for key, value in mapping.items():
+        if isinstance(value, (bytes, str)):
+            items.append((key, value))
+        elif isinstance(value, _abc.Iterable):
+            items.extend((key, v) for v in value)
+        else:
+            items.append((key, value))
+    return _querylist(items, sep, encoding)
+
+
+class Query:
+    """A URI query as an immutable value: the percent-encoded text and the
+    `(name, value)` pairs it stands for.
+
+    Build one from pairs or a mapping (a sequence value repeats the name, a
+    `None` value is a bare name) with `Query(...)`, which encodes them so that
+    `to_pairs()` returns what was given, or from text with `Query.parse()`,
+    which keeps the text byte for byte: it is what `URI.query` holds, as
+    received, and what is sent. `str(query)` is that text.
+
+    Two queries are equal, and hash alike, when they decode to the same pairs,
+    whatever their spelling (`a=%41` and `a=A`); a query is never equal to a
+    `str`, and has no length, items or iteration. `to_pairs()` and `to_dict()`
+    follow RFC 3986, not `application/x-www-form-urlencoded`: only `%XX`
+    escapes are decoded and a `+` stays a plus (`urllib.parse.parse_qsl` reads
+    form text), and an escape that is not valid in `encoding` survives as a
+    surrogate escape instead of raising.
+
+    `separator` splits the text into terms (default `&`) and `encoding` is the
+    charset of the escapes (default `utf-8`); both say how the text is read
+    and are not part of the value."""
+
+    __slots__ = ("_text", "_separator", "_encoding", "_pairs")
+    SEPARATOR = "&"
+    ENCODING = "utf-8"
+
+    def __init__(
+        self,
+        pairs: (
+            _ty.Mapping[str, str | None | _ty.Sequence[str | None]]
+            | _ty.Sequence[tuple[str, str | None]]
+            | Query
+        ) = (),
+        *,
+        separator: str | None = None,
+        encoding: str | None = None,
+    ):
+        if isinstance(pairs, (str, bytes)):
+            raise TypeError(
+                "a Query is built from pairs or a mapping; "
+                "use Query.parse() for query text"
+            )
+        text = None
+        if isinstance(pairs, Query):
+            separator = separator or pairs._separator
+            encoding = encoding or pairs._encoding
+            if separator == pairs._separator and encoding == pairs._encoding:
+                text = pairs._text
+            else:
+                pairs = pairs.to_pairs()
+        else:
+            separator = separator or self.SEPARATOR
+            encoding = encoding or self.ENCODING
+        if text is None:
+            if isinstance(pairs, _abc.Mapping):
+                text = _querydict(pairs, separator, encoding)
+            else:
+                text = _querylist(pairs, separator, encoding)
+        self._set(text, separator, encoding)
+
+    def _set(self, text: str, separator: str, encoding: str) -> None:
+        object.__setattr__(self, "_text", text)
+        object.__setattr__(self, "_separator", separator)
+        object.__setattr__(self, "_encoding", encoding)
+        object.__setattr__(self, "_pairs", None)
+
+    @classmethod
+    def parse(
+        cls, text: str, *, separator: str = SEPARATOR, encoding: str = ENCODING
+    ) -> Query:
+        """The query that `text` spells, percent-encoded as received and kept
+        byte for byte. Any text parses; `TypeError` for what is not a `str`."""
+        if not isinstance(text, str):
+            raise TypeError(f"query text must be a str, not {type(text).__name__!r}")
+        query = object.__new__(cls)
+        query._set(text, separator, encoding)
+        return query
+
+    @property
+    def separator(self) -> str:
+        """What splits the text into terms."""
+        return self._separator
+
+    @property
+    def encoding(self) -> str:
+        """The charset the escapes of the text are read in."""
+        return self._encoding
+
+    def to_pairs(self) -> list[tuple[str, str | None]]:
+        """The decoded `(name, value)` pairs in order; `value` is `None` for a
+        name with no `=`."""
+        return list(self._decoded())
+
+    def to_dict(self, *, single: bool = False):
+        """The pairs by name: each name maps to the list of its values, or with
+        `single` to its last value."""
+        query_: dict[str, list[str | None]] = {}
+        for k, v in self._decoded():
+            if single:
+                query_[k] = v
+            else:
+                query_.setdefault(k, []).append(v)
+        return query_
+
+    def _decoded(self) -> "tuple[tuple[str, str | None], ...]":
+        pairs = self._pairs
+        if pairs is None:
+            found = []
+            for term in self._text.split(self._separator):
+                if not term:
+                    continue
+                name, equals, value = term.partition("=")
+                found.append(
+                    (
+                        _rfc3986.decode(name, ERRORS, self._encoding),
+                        (
+                            _rfc3986.decode(value, ERRORS, self._encoding)
+                            if equals
+                            else None
+                        ),
+                    )
+                )
+            pairs = tuple(found)
+            object.__setattr__(self, "_pairs", pairs)
+        return pairs
+
+    def __str__(self) -> str:
+        return self._text
+
+    def __repr__(self) -> str:
+        extra = ""
+        if self._separator != self.SEPARATOR:
+            extra += f", separator={self._separator!r}"
+        if self._encoding != self.ENCODING:
+            extra += f", encoding={self._encoding!r}"
+        return f"{type(self).__name__}.parse({self._text!r}{extra})"
+
+    def __bool__(self) -> bool:
+        return bool(self._text)
+
+    def __eq__(self, other: object):
+        if not isinstance(other, Query):
+            return NotImplemented
+        return self._decoded() == other._decoded()
+
+    def __hash__(self) -> int:
+        return hash(self._decoded())
+
+    def __setattr__(self, name, value):
+        raise AttributeError(f"{type(self).__name__} is immutable")
+
+    def __delattr__(self, name):
+        raise AttributeError(f"{type(self).__name__} is immutable")
+
+    def __reduce__(self):
+        return (_rebuild, (self._text, self._separator, self._encoding))
+
+    def __copy__(self) -> Query:
+        return self
+
+    def __deepcopy__(self, memo) -> Query:
+        return self
+
+
+def _rebuild(text: str, separator: str, encoding: str) -> Query:
+    return Query.parse(text, separator=separator, encoding=encoding)
+
+
+QueryLike: TypeAlias = (
+    "str | Query | _ty.Mapping[str, str | None | _ty.Sequence[str | None]]"
+    " | _ty.Sequence[tuple[str, str | None]]"
+)
+"""What `URI.with_query()` accepts in place of a `Query`: query text (taken as
+already percent-encoded), a mapping or a sequence of pairs, or a `Query`; `None`
+removes the query."""
+
+
+def _coerce(query: "QueryLike | None") -> Query:
+    """`query` as a `Query`: text is parsed, pairs and mappings are encoded,
+    and `None` is the empty query."""
+    if isinstance(query, Query):
+        return query
+    if query is None:
+        return Query.parse("")
+    if isinstance(query, str):
+        return Query.parse(query)
+    return Query(query)

uripath/schemes/__init__.py

@@ -0,0 +1,120 @@
+"""The contract of a URI scheme, the registry of schemes and the built-in schemes.
+
+`URIPath` is the class a scheme subclasses: defining a subclass that lists
+`__SCHEMES` registers it. A built-in scheme is a private module that
+`URIPath` imports the first time its scheme is used; the names below are
+exported from here and resolved lazily (PEP 562), so importing this package,
+or building a `file:` path, imports no other scheme and a `file:` path never
+pays for the HTTP client.
+"""
+
+from __future__ import annotations
+
+import importlib as _importlib
+import sys as _sys
+import types as _types
+import typing as _ty
+
+from ._delegate import DelegatingURIPath as DelegatingURIPath
+from ._path import DerivedBackend
+from ._path import URIPath as URIPath
+
+if _ty.TYPE_CHECKING:
+    from ._archive import ArchiveTarURIPath as ArchiveTarURIPath
+    from ._archive import ArchiveURIPath as ArchiveURIPath
+    from ._archive import ArchiveZipURIPath as ArchiveZipURIPath
+    from ._archive import TarURIPath as TarURIPath
+    from ._archive import ZipURIPath as ZipURIPath
+    from ._data import DataURIPath as DataURIPath
+    from ._dav import DAVURIPath as DAVURIPath
+    from ._file import FileURIPath as FileURIPath
+    from ._ftp import BaseFTPURIBackend as BaseFTPURIBackend
+    from ._ftp import FTPURIBackend as FTPURIBackend
+    from ._ftp import FTPURIPath as FTPURIPath
+    from ._http._backend import HTTPBackend as HTTPBackend
+    from ._http._path import HTTPURIPath as HTTPURIPath
+    from ._http._streams import HTTPAppendStream as HTTPAppendStream
+    from ._http._streams import HTTPWriteStream as HTTPWriteStream
+
+#: Public name -> the private submodule that defines it, loaded on first use.
+_EXPORTS = {
+    "ArchiveTarURIPath": "_archive",
+    "ArchiveURIPath": "_archive",
+    "ArchiveZipURIPath": "_archive",
+    "TarURIPath": "_archive",
+    "ZipURIPath": "_archive",
+    "DataURIPath": "_data",
+    "DAVURIPath": "_dav",
+    "FileURIPath": "_file",
+    "BaseFTPURIBackend": "_ftp",
+    "FTPURIBackend": "_ftp",
+    "FTPURIPath": "_ftp",
+    "HTTPAppendStream": "_http._streams",
+    "HTTPBackend": "_http._backend",
+    "HTTPURIPath": "_http._path",
+    "HTTPWriteStream": "_http._streams",
+}
+
+__all__ = [
+    "ArchiveTarURIPath",
+    "ArchiveURIPath",
+    "ArchiveZipURIPath",
+    "BaseFTPURIBackend",
+    "DAVURIPath",
+    "DataURIPath",
+    "DelegatingURIPath",
+    "DerivedBackend",
+    "FTPURIBackend",
+    "FTPURIPath",
+    "FileURIPath",
+    "HTTPAppendStream",
+    "HTTPBackend",
+    "HTTPURIPath",
+    "HTTPWriteStream",
+    "MEMBER_SPOOL_BYTES",
+    "TarURIPath",
+    "ZipURIPath",
+]
+
+
+class _Module(_types.ModuleType):
+    """The module, with the setting that is read where it takes effect
+    (`MEMBER_SPOOL_BYTES` in `pathapi.archive`) read from and written to
+    there."""
+
+    @property
+    def MEMBER_SPOOL_BYTES(self) -> int:
+        from pathapi import archive
+
+        return archive.MEMBER_SPOOL_BYTES
+
+    @MEMBER_SPOOL_BYTES.setter
+    def MEMBER_SPOOL_BYTES(self, value: int) -> None:
+        from pathapi import archive
+
+        archive.MEMBER_SPOOL_BYTES = value
+
+
+_sys.modules[__name__].__class__ = _Module
+
+
+def __getattr__(name: str):
+    submodule = _EXPORTS.get(name)
+    if submodule is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = _importlib.import_module(f"{__name__}.{submodule}")
+    except ImportError as error:
+        # Only ImportError: a dependency that fails at import for any other
+        # reason is a real defect and must stay visible.
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}"
+            f" (its optional dependency is not importable: {error})"
+        ) from error
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_EXPORTS))