pathapi-uri 0.1.0__py3-none-any.whl

uripath/schemes/_registry.py

@@ -0,0 +1,134 @@
+"""Which class a scheme name belongs to: the classes that registered, the
+built-in table and the `uripath.schemes` entry points."""
+
+from __future__ import annotations
+
+import threading as _threading
+import typing as _ty
+
+if _ty.TYPE_CHECKING:
+    from ._path import URIPath
+
+#: `(entry_points function, {scheme: entry point})` for the
+#: `uripath.schemes` group, read once per lookup function; a scheme no
+#: plugin declares is a dictionary miss and adds nothing to it.
+_ENTRY_POINTS: "tuple[object, dict[str, object]] | None" = None
+
+
+#: Schemes whose entry point loaded without registering them: loading it
+#: again cannot help.
+_ENTRY_POINTS_LOADED: "set[str]" = set()
+
+
+#: Built-in scheme -> the module that defines its class. A name listed here is
+#: resolved from this table before any entry point is consulted.
+_BUILTIN_SCHEMES = {
+    "file": "uripath.schemes._file",
+    "data": "uripath.schemes._data",
+    "zip": "uripath.schemes._archive",
+    "tar": "uripath.schemes._archive",
+    "archive": "uripath.schemes._archive",
+    "archive+zip": "uripath.schemes._archive",
+    "archive+tar": "uripath.schemes._archive",
+    "ftp": "uripath.schemes._ftp",
+    "ftps": "uripath.schemes._ftp",
+    "http": "uripath.schemes._http._path",
+    "https": "uripath.schemes._http._path",
+    "dav": "uripath.schemes._dav",
+    "davs": "uripath.schemes._dav",
+}
+
+
+#: Scheme -> the class that registered it, filled when the class is defined.
+_CLAIMS: "dict[str, type[URIPath]]" = {}
+
+
+#: Schemes a class took with `replace=True`; a built-in class defined after
+#: one of them leaves it with the replacement.
+_REPLACED: "set[str]" = set()
+
+
+#: Makes checking a claim and recording it one step.
+_CLAIMS_LOCK = _threading.Lock()
+
+
+def _forget_entry_points() -> None:
+    global _ENTRY_POINTS
+    _ENTRY_POINTS = None
+    _ENTRY_POINTS_LOADED.clear()
+
+
+def _declared_entry_points() -> "dict[str, object]":
+    """The `uripath.schemes` entry points by scheme name, the first
+    declaration of a name winning. Scanning every distribution cost 13-29 ms
+    per construction with an unregistered scheme (`C:/x` on Windows
+    included), so the group is read once per lookup function and dropped when
+    a `URIPath` subclass is defined (`_forget_entry_points`)."""
+    global _ENTRY_POINTS
+    import importlib.metadata as _metadata
+
+    cached = _ENTRY_POINTS
+    if cached is None or cached[0] is not _metadata.entry_points:
+        try:
+            eps = _metadata.entry_points(group="uripath.schemes")
+        except TypeError:
+            # Python 3.9 fallback
+            eps = _metadata.entry_points().get("uripath.schemes", ())
+        declared: "dict[str, object]" = {}
+        for ep in eps:
+            declared.setdefault(ep.name, ep)
+        cached = _ENTRY_POINTS = (_metadata.entry_points, declared)
+    return cached[1]
+
+
+def _is_builtin_class(scheme: str, cls: type) -> bool:
+    """Whether `cls` is defined in the module (or package) the built-in
+    table names for `scheme`."""
+    module = _BUILTIN_SCHEMES.get(scheme)
+    return module is not None and (
+        cls.__module__ == module or cls.__module__.startswith(module + ".")
+    )
+
+
+def _same_definition(a: type, b: type) -> bool:
+    """Whether two classes come from one `class` statement run twice (a
+    reload, a function body called again): same module, same qualified name."""
+    return a.__module__ == b.__module__ and a.__qualname__ == b.__qualname__
+
+
+def _claim_schemes(cls: type, replace: bool) -> None:
+    """Register the schemes `cls` lists in its own `__SCHEMES`.
+
+    A name a different class holds, or a built-in name whose class is not the
+    built-in one, is a `ValueError` unless `replace` is true; the same
+    definition run again takes its names over. Nothing is registered when any
+    name is refused.
+    """
+    names = tuple(dict.fromkeys(cls.__dict__.get(f"_{cls.__name__}__SCHEMES", ())))
+    with _CLAIMS_LOCK:
+        taking = []
+        for name in names:
+            held = _CLAIMS.get(name)
+            if replace:
+                taking.append(name)
+            elif held is None:
+                if name in _BUILTIN_SCHEMES and not _is_builtin_class(name, cls):
+                    raise ValueError(
+                        f"{name!r} is a built-in URI scheme; pass replace=True "
+                        f"in the class statement of {cls.__qualname__} to replace it"
+                    )
+                taking.append(name)
+            elif _same_definition(held, cls):
+                taking.append(name)
+            elif name in _REPLACED and _is_builtin_class(name, cls):
+                continue
+            else:
+                raise ValueError(
+                    f"URI scheme {name!r} is already registered by "
+                    f"{held.__module__}.{held.__qualname__}; pass replace=True "
+                    f"in the class statement of {cls.__qualname__} to replace it"
+                )
+        for name in taking:
+            _CLAIMS[name] = cls
+            if replace:
+                _REPLACED.add(name)

uripath/source/__init__.py

@@ -0,0 +1,20 @@
+"""`Source` (the scheme, userinfo, host and port of a URI) and the helpers that
+read and compose the text of one."""
+
+from __future__ import annotations
+
+from ._compose import SAFE_PATH, compose_host, compose_uri, percent_encode
+from ._parse import ERRORS, fold_host, is_drive
+from ._source import Source, same_authority
+
+__all__ = [
+    "ERRORS",
+    "SAFE_PATH",
+    "Source",
+    "compose_host",
+    "compose_uri",
+    "fold_host",
+    "is_drive",
+    "percent_encode",
+    "same_authority",
+]

uripath/source/_compose.py

@@ -0,0 +1,212 @@
+"""Composing URI text from decoded components.
+
+Direct string assembly instead of `uricompose()`'s per-call re-validation, which
+only matters for untrusted input: these parts come from a parse or a join.
+"""
+
+from __future__ import annotations
+
+import ipaddress as _ip
+import re as _re
+
+from .. import _rfc3986
+from ._parse import (
+    ERRORS,
+    _IPAddress,
+    _ipv6_from_literal,
+    _parse_port,
+    _split_userinfo_text,
+)
+
+_SUB_DELIMS = "!$&'()*+,;="
+_SAFE_USER = _SUB_DELIMS
+_SAFE_USERINFO = _SUB_DELIMS + ":"
+_SAFE_HOST = _SUB_DELIMS
+#: The characters `percent_encode()` leaves as they are in a path.
+SAFE_PATH = _SUB_DELIMS + ":@/"
+_SAFE_PATH = SAFE_PATH
+_SAFE_QUERY = _SUB_DELIMS + ":@/?"
+_SAFE_FRAGMENT = _SAFE_QUERY
+
+
+_PERCENT_ESCAPE = _re.compile("(%[0-9A-Fa-f]{2})")
+_SCHEME_RE = _re.compile(r"[A-Za-z][A-Za-z0-9+.\-]*")
+
+
+def _lenient_utf8(text: str) -> bytes:
+    """`text` as UTF-8 where a surrogate that `surrogateescape` cannot carry
+    (a lone U+D800-U+DBFF or U+DC00-U+DC7F, which an NTFS name may hold) is
+    written the way `surrogatepass` writes it, and an escaped byte
+    (U+DC80-U+DCFF) is that byte again."""
+    out = bytearray()
+    for char in text:
+        code = ord(char)
+        if 0xDC80 <= code <= 0xDCFF:
+            out.append(code - 0xDC00)
+        else:
+            out += char.encode("utf-8", "surrogatepass")
+    return bytes(out)
+
+
+def percent_encode(text: str, safe: str) -> str:
+    """`text` percent-encoded as UTF-8, keeping the characters of `safe`.
+    A decoded path may hold escaped bytes (`ERRORS`) and, from a Windows
+    listing, a lone surrogate; neither may make the composer raise."""
+    try:
+        return _rfc3986.encode(text, safe, errors=ERRORS)
+    except UnicodeEncodeError:
+        return _rfc3986.encode(_lenient_utf8(text), safe)
+
+
+_encode = percent_encode
+
+
+def _encode_userinfo(userinfo: str) -> str:
+    """A userinfo for composition: the user name escapes its colons, the
+    password keeps them (RFC 3986 3.2.1)."""
+    user, password = _split_userinfo_text(userinfo)
+    text = _encode(user, _SAFE_USER)
+    if password is not None:
+        text += ":" + _encode(password, _SAFE_USERINFO)
+    return text
+
+
+def _encode_raw_query(query: str) -> str:
+    """Emit a stored query for the wire: it is kept in its received,
+    still-percent-encoded form (see `URI.query`), so an existing `%XX`
+    escape and every delimiter (`&`, `=`, `+`, `;`) go out unchanged. Only
+    characters that cannot appear in a query at all (a space, non-ASCII, a
+    `%` that starts no escape) are encoded.
+
+    Decoding at parse time and re-encoding here with `&`/`=`/`+` as safe
+    characters turned `name=a%26b&sig=ab%2Bcd%3D%3D` into
+    `name=a&b&sig=ab+cd==` on the wire, corrupting signed URLs."""
+    pieces = _PERCENT_ESCAPE.split(query)
+    for index in range(0, len(pieces), 2):
+        if pieces[index]:
+            pieces[index] = _encode(pieces[index], _SAFE_QUERY)
+    return "".join(pieces)
+
+
+def _compose_ipv6(address: _ip.IPv6Address) -> str:
+    """A bracketed IPv6 literal; a zone is written after `%25` and
+    percent-encoded (RFC 6874)."""
+    text, sep, zone = address.compressed.partition("%")
+    if sep:
+        text = f"{text}%25{_encode(zone, '')}"
+    return f"[{text}]"
+
+
+def compose_host(host: "str | _IPAddress") -> str:
+    """Encode a host for composition: an IPv6 address is bracketed, and so is a
+    bare (non-bracketed) string that parses as one, as a manually constructed
+    `Source(..., host="::1", ...)` holds it. Deliberately not netimps'
+    `join_host`/`FQDN`: those would reject names this composes. An IPv6 zone is
+    written as RFC 6874 says."""
+    if isinstance(host, _ip.IPv6Address):
+        return _compose_ipv6(host)
+    if isinstance(host, _ip.IPv4Address):
+        return host.compressed
+    if host.startswith("[") and host.endswith("]"):
+        return _compose_ipv6(_ipv6_from_literal(host[1:-1]))
+    try:
+        return _compose_ipv6(_ip.IPv6Address(host))
+    except ValueError:
+        pass
+    if not host.isascii():
+        # RFC 3986 3.2.2: a non-ASCII registered name meant for DNS is produced in its
+        # IDNA form (HTTP clients IDNA-encode only a non-ASCII host). A name the codec
+        # rejects (an empty or over-long label, a surrogate-escaped byte) stays percent-encoded.
+        try:
+            return _idna_encode(host)
+        except UnicodeError:
+            pass
+    return _encode(host, _SAFE_HOST)
+
+
+_compose_host = compose_host
+
+
+def _idna_encode(host: str) -> str:
+    """`host` in IDNA (ASCII) form: IDNA 2008 with UTS #46 mapping through
+    the `idna` package when installed (what `requests` itself uses), else
+    the stdlib IDNA 2003 codec. Raises UnicodeError for an invalid name."""
+    try:
+        import idna as _idna
+    except ImportError:
+        return host.encode("idna").decode("ascii")
+    # idna.IDNAError subclasses UnicodeError.
+    return _idna.encode(host, uts46=True).decode("ascii")
+
+
+def _port_text(port: "int | str") -> str:
+    """The digits of a port that is 0-65535 (an int, or a `str` of digits);
+    anything else is a `ValueError`, so a field that did not come from a
+    parse cannot add a path or a second authority to the result."""
+    if isinstance(port, str):
+        if not port.isascii() or not port.isdigit():
+            raise ValueError("invalid port: it must be digits")
+        return str(_parse_port(port))
+    if isinstance(port, bool) or not isinstance(port, int):
+        raise ValueError("invalid port: it must be an integer")
+    if not 0 <= port <= 65535:
+        raise ValueError("port out of range 0-65535")
+    return str(port)
+
+
+def compose_uri(
+    scheme: "str | None",
+    userinfo: "str | None",
+    host: "str | _IPAddress | None",
+    port: "int | str | None",
+    path: str,
+    query: "str | None",
+    fragment: "str | None",
+) -> str:
+    """The URI text of already-decoded components, percent-encoding each as
+    its part of RFC 3986 asks. `None` leaves a component out; a path that
+    cannot sit beside the authority given (or beside none) is a `ValueError`,
+    as is an invalid scheme or port.
+
+    This is direct string assembly, with no re-validation of every component
+    (a scheme regex, authority re-parsing, IP-literal detection), which only
+    matters for untrusted input. It replicates only what changes the output
+    string (IP-literal bracketing, the "./" escape of a colon in the first
+    segment); the tests compare it with `uritools.uricompose()` on generated
+    (scheme, userinfo, host, port, path, query, fragment) combinations."""
+    parts = []
+    if scheme is not None:
+        if not _SCHEME_RE.fullmatch(scheme):
+            raise ValueError("invalid scheme")
+        parts.append(scheme)
+        parts.append(":")
+    has_authority = userinfo is not None or host is not None or port is not None
+    if has_authority:
+        parts.append("//")
+        if userinfo is not None:
+            parts.append(_encode_userinfo(userinfo))
+            parts.append("@")
+        if host is not None:
+            parts.append(_compose_host(host))
+        if port is not None:
+            parts.append(":")
+            parts.append(_port_text(port))
+    path_enc = _encode(path, _SAFE_PATH) if path else ""
+    if has_authority and path_enc and not path_enc.startswith("/"):
+        raise ValueError("Invalid path with authority component")
+    if not has_authority and path_enc.startswith("//"):
+        raise ValueError("Invalid path without authority component")
+    if scheme is None and not has_authority and not path_enc.startswith("/"):
+        if ":" in path_enc.partition("/")[0]:
+            path_enc = "./" + path_enc
+    parts.append(path_enc)
+    if query is not None:
+        parts.append("?")
+        parts.append(_encode_raw_query(query))
+    if fragment is not None:
+        parts.append("#")
+        parts.append(_encode(fragment, _SAFE_FRAGMENT))
+    return "".join(parts)
+
+
+_compose_uri = compose_uri

uripath/source/_locality.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import threading as _threading
+import time as _time
+
+from ._parse import _IPAddress
+
+#: How long `Source.is_local()` remembers an answer, in seconds, and for how
+#: many hosts.
+_LOCAL_TTL = 60.0
+_LOCAL_CACHE_SIZE = 256
+_local_cache: "dict[object, tuple[float, bool]]" = {}
+_local_lock = _threading.Lock()
+
+
+def _host_is_local(host: "str | _IPAddress") -> bool:
+    now = _time.monotonic()
+    with _local_lock:
+        entry = _local_cache.get(host)
+    if entry is not None and entry[0] > now:
+        return entry[1]
+    answer = _resolve_is_local(host)
+    with _local_lock:
+        if len(_local_cache) >= _LOCAL_CACHE_SIZE:
+            for key in [k for k, (until, _) in _local_cache.items() if until <= now]:
+                del _local_cache[key]
+        while len(_local_cache) >= _LOCAL_CACHE_SIZE:
+            del _local_cache[next(iter(_local_cache))]
+        _local_cache[host] = (now + _LOCAL_TTL, answer)
+    return answer
+
+
+def _resolve_is_local(host: "str | _IPAddress") -> bool:
+    # Imported here, not at module top: only this needs netimps, and every
+    # `import uripath` would otherwise pay for its import.
+    import netimps as _netimps
+
+    if not isinstance(host, str):
+        return _netimps.is_local_address(host)
+    literal = _netimps.try_parse(host)
+    if literal is not None:
+        return _netimps.is_local_address(literal)
+    addresses = _netimps.resolve(host, "a") + _netimps.resolve(host, "aaaa")
+    return any(_netimps.is_local_address(address) for address in addresses)

uripath/source/_parse.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import ipaddress as _ip
+import typing as _ty
+
+from .. import _rfc3986
+from ..exceptions import URISyntaxError
+
+_IPAddress = _ty.Union[_ip.IPv4Address, _ip.IPv6Address]
+
+
+_DIGITS = "0123456789"
+
+
+#: Error handler for percent-escapes. A valid URI may escape bytes that are not
+#: UTF-8 (`caf%E9.html`); `surrogateescape` carries each through the decoded `str`
+#: and back out to the same escape, where `strict` would raise UnicodeDecodeError.
+ERRORS = "surrogateescape"
+_ERRORS = ERRORS
+
+
+class _Userinfo(str):
+    """A decoded userinfo that remembers which colon separated the user name
+    from the password. It equals, hashes and prints as the plain
+    `user:password` text, so code that treats `Source.userinfo` as a `str`
+    is unaffected; only the composer and `Source.parsed_userinfo()` read
+    the split. Without it a user name holding an escaped colon (`us%3Aer`)
+    could not be told from a password separator once decoded."""
+
+    __slots__ = ("user", "password")
+
+    def __new__(cls, user: str, password: "str | None" = None):
+        obj = str.__new__(cls, user if password is None else f"{user}:{password}")
+        obj.user = user
+        obj.password = password
+        return obj
+
+    def __reduce__(self):
+        return _Userinfo, (self.user, self.password)
+
+
+def _split_userinfo_text(userinfo: str) -> "tuple[str, str | None]":
+    """`(user, password)` of a userinfo: the split `_Userinfo` recorded, else
+    at the first colon. `password` is None when there is no colon."""
+    if isinstance(userinfo, _Userinfo):
+        return userinfo.user, userinfo.password
+    user, colon, password = userinfo.partition(":")
+    return user, (password if colon else None)
+
+
+def _decode_userinfo(raw: str) -> _Userinfo:
+    """Decode a raw userinfo: split at the first literal colon FIRST, then
+    decode each half, so an escaped `%3A` stays part of the name."""
+    user, colon, password = raw.partition(":")
+    return _Userinfo(
+        _rfc3986.decode(user, _ERRORS),
+        _rfc3986.decode(password, _ERRORS) if colon else None,
+    )
+
+
+def _parse_port(text: str) -> "int | None":
+    """The port a run of ASCII digits names (None for no digits), which must
+    be 0-65535 (RFC 3986 3.2.3 leaves it open; TCP and UDP do not). The
+    message names no part of the input: it may sit beside a password."""
+    if not text:
+        return None
+    digits = text.lstrip("0") or "0"
+    if len(digits) > 5 or int(digits) > 65535:
+        raise URISyntaxError("port out of range 0-65535")
+    return int(digits)
+
+
+def _split_authority(
+    authority: "str | None",
+) -> "tuple[str | None, str | None, int | None]":
+    """One-pass split of a raw URI authority into (userinfo, host, port) --
+    RAW/undecoded strings, port as int-or-None. It follows the RFC 3986
+    reading of `userinfo@host:port` with one split of the authority; the tests
+    compare it with the `uritools` reading and name where it differs:
+
+    * a host is followed by a port only when a ':' was found, so a host of
+      digits alone (`s3://20240101/key`) stays the host, where `uritools`
+      reads it as a port and returns an empty host;
+    * the port is 0-65535; a ':' followed by anything else that is not a
+      bracketed address is an invalid port (`URISyntaxError`), not part of the
+      host name."""
+    if authority is None:
+        return None, None, None
+    userinfo, at_sep, hostinfo = authority.rpartition("@")
+    if not at_sep:
+        userinfo = None
+    host, colon, tail = hostinfo.rpartition(":")
+    if colon and not tail.lstrip(_DIGITS):
+        return userinfo, host, _parse_port(tail)
+    if colon and not hostinfo.startswith("["):
+        raise URISyntaxError("invalid port: it must be digits")
+    return userinfo, hostinfo, None
+
+
+def _ipv6_from_literal(literal: str) -> _ip.IPv6Address:
+    """The address a bracketed IPv6 literal names. A zone is introduced by
+    `%25` (RFC 6874: the `%` of `address%zone` is escaped inside a URI) and
+    is percent-decoded; a bare `%` is read as the delimiter as well, as
+    `ipaddress` does."""
+    address, sep, zone = literal.partition("%25")
+    if sep:
+        literal = f"{address}%{_rfc3986.decode(zone, _ERRORS)}"
+    try:
+        return _ip.IPv6Address(literal)
+    except ValueError:
+        raise URISyntaxError("invalid IPv6 address in the host") from None
+
+
+def _decode_host(host: str) -> "str | _IPAddress":
+    """Decode a raw (still percent-encoded) host string. A bracketed
+    literal is an IPv6 address; mismatched brackets and a literal that starts
+    with a lower-case `v` (an IPvFuture version flag; RFC 3986 spells it in
+    either case, and only the lower-case one is refused) raise
+    `URISyntaxError`; a dotted quad is an IPv4 address; anything else is a
+    name, percent-decoded. An IPv6 zone is read as RFC 6874 says
+    (`_ipv6_from_literal`)."""
+    if host.startswith("[") and host.endswith("]"):
+        literal = host[1:-1]
+        if literal.startswith("v"):
+            raise URISyntaxError("address mechanism not supported")
+        return _ipv6_from_literal(literal)
+    if host.startswith("[") or host.endswith("]"):
+        raise URISyntaxError(f"Invalid host {host!r}: mismatched brackets")
+    try:
+        return _ip.IPv4Address(host)
+    except ValueError:
+        return _rfc3986.decode(host, _ERRORS)
+
+
+def fold_host(host: "str | _IPAddress | None") -> "str | _IPAddress | None":
+    """`host` as a comparison or a key reads it: a name in lower case, since
+    host names are case-insensitive (RFC 3986 3.2.2), and an address as it is.
+    `Source.host` keeps the spelling it was given, so anything that compares
+    hosts or uses one as a key folds it at that place."""
+    return host.lower() if isinstance(host, str) else host
+
+
+def is_drive(segment: str) -> bool:
+    """Whether a path segment is a Windows drive ("C:")."""
+    return len(segment) == 2 and segment[1] == ":" and segment[0].isalpha()
+
+
+_is_drive = is_drive
+
+
+def _remove_dot_segments(path: str, *, drive: bool = False) -> str:
+    """RFC 3986 5.2.4 dot-segment removal on a path. Apply it to a raw
+    (still percent-encoded) path before decoding,
+    and again to the decoded path: a `%2e` only becomes a `.` segment
+    once decoded. A `..` that would pass the root of an absolute path is
+    dropped; a relative path keeps its leading `..`.
+
+    `drive=True` (a `file:` path on Windows) makes a leading drive segment
+    ("C:/x", "/C:/x") the anchor, which `..` never climbs above, as for
+    `PureWindowsPath`."""
+    if drive:
+        head = path[1:] if path.startswith("/") else path
+        letter, sep, rest = head.partition("/")
+        if sep and _is_drive(letter):
+            lead = path[: len(path) - len(head)]
+            return lead + letter + _remove_dot_segments("/" + rest)
+    pseg = []
+    for s in path.split("/"):
+        if s == ".":
+            continue
+        elif s != "..":
+            pseg.append(s)
+        elif len(pseg) == 1 and not pseg[0]:
+            continue
+        elif pseg and pseg[-1] != "..":
+            pseg.pop()
+        else:
+            pseg.append(s)
+    if path.rpartition("/")[2] in (".", ".."):
+        pseg.append("")
+    if path and len(pseg) == 1 and pseg[0] == "":
+        pseg.insert(0, ".")
+    return "/".join(pseg)