cliV1 0.0.7__py3-none-any.whl

swagger_petstore_open_api_3_1_0/core/_internal/content_disposition.py

@@ -0,0 +1,154 @@
+"""``Content-Disposition``, both directions: the filename a response suggests, and the one a
+request carries.
+
+One header, one module. The RFC 6266/8187 grammar is the shared asset, so reading it and writing
+it stay together rather than putting one table in two files. ``headers.py`` remains the
+*parameter*-layer module, resolving the outbound layers a caller and the spec contribute; what
+this module renders is a value a body carries, exactly as its media type is.
+
+The standard library gets the reading wrong twice, both reproduced during planning
+(docs/plans/file-handling.md, verified facts). ``Message.get_filename()`` returns the plain
+``filename`` when both forms are present -- RFC 6266 §4.3 requires the extended ``filename*`` to
+win -- and the RFC 2231 machinery percent-decodes the extended value as latin-1 whatever charset
+it declares, so the text must be re-encoded through latin-1 and decoded with the declared charset
+to come back intact.
+
+The two readers treat their input as attacker-controlled. The parser is **total**: any malformed
+header yields ``None`` rather than raising, because it runs while a streamed connection is held
+and a raise there would leak it. The sanitiser is the paranoid half: a server-suggested name is
+reduced to a basename, stripped of everything Windows refuses, and refused outright when what
+survives is empty, a reserved device name, or too long to create.
+
+The writer needs no such paranoia, and by construction rather than by trust: every byte outside
+RFC 8187's ``attr-char`` is percent-encoded, so no name can splice a header and there is nothing
+to refuse."""
+
+from __future__ import annotations
+
+import re
+from email.message import Message
+from typing import Final
+from urllib.parse import quote
+
+_SEPARATORS: Final = re.compile(r"[\\/]")
+_WINDOWS_ILLEGAL: Final = frozenset('<>:"|?*')
+_WINDOWS_RESERVED: Final = frozenset(
+    {"CON", "PRN", "AUX", "NUL"} | {f"COM{d}" for d in "123456789"} | {f"LPT{d}" for d in "123456789"}
+)
+
+
+def content_disposition_filename(header: str | None) -> str | None:
+    """The filename a ``Content-Disposition`` suggests, or ``None``.
+
+    Prefers the RFC 8187 extended ``filename*`` (RFC 6266 §4.3) and recovers its text from the
+    standard library's latin-1 percent-decode; RFC 8187 §3.2.1 permits only UTF-8, so any other
+    declared charset falls back to the plain ``filename`` rather than guessing. Continuation
+    segments (``filename*0*``, ``filename*1*``) are collapsed by the same machinery.
+
+    Total by design: a malformed header returns ``None``, never raises -- this runs between a
+    streamed response's head arriving and its owner returning, where a raise would leak the
+    connection. The result is *not* trusted as a path; see :func:`safe_filename`.
+
+    Args:
+        header: The header's value, or ``None`` when the response carried none.
+
+    Returns:
+        The suggested filename, or ``None`` when there is no usable one."""
+    if header is None:
+        return None
+    try:
+        message = Message()
+        message["content-disposition"] = header
+        params = message.get_params(header="content-disposition")
+        if params is None:
+            return None
+
+        plain: str | None = None
+        extended: str | None = None
+        for name, raw in params:
+            if name != "filename":
+                continue
+            # The parser hands back a plain parameter as ``str`` and an RFC 2231 extended one as a
+            # ``(charset, language, text)`` tuple. A duplicated plain form keeps its first
+            # occurrence; duplicated extended forms never reach here -- the stdlib merges them as
+            # continuations before ``get_params`` returns.
+            value: object = raw
+            if isinstance(value, str) and plain is None:
+                plain = value
+            elif isinstance(value, tuple) and extended is None:
+                extended = _decode_extended(value)
+        return (extended or plain) or None
+    except Exception:
+        # Total by design -- the docstring says why. Bad wire data degrades, never raises.
+        return None
+
+
+def _decode_extended(value: tuple[object, ...]) -> str | None:
+    # (charset, language, text) -- text percent-decoded as latin-1 by the parser regardless of the
+    # declared charset, which is the mojibake the round trip below undoes.
+    if len(value) != 3:
+        return None
+    charset, _language, text = value
+    if not isinstance(charset, str) or not isinstance(text, str):
+        return None
+    if charset.lower() not in ("utf-8", "utf8"):
+        return None
+    try:
+        return text.encode("latin-1").decode("utf-8")
+    except (UnicodeEncodeError, UnicodeDecodeError):
+        return None
+
+
+def render_content_disposition(filename: str) -> str:
+    """The ``Content-Disposition`` value naming a raw request body.
+
+    RFC 6266's dual form: a quoted ``filename`` holding what a quoted-string can, and, whenever
+    that reduction lost something, the RFC 8187 ``filename*`` that did not. A conformant receiver
+    prefers the extended parameter (§4.3) and recovers the name exactly; one reading only the plain
+    parameter still gets a usable name.
+
+    Percent-encoding is what makes this safe rather than a character check: every byte outside
+    RFC 8187's ``attr-char`` becomes ``%XX``, so a CR, an LF or a ``"`` cannot reach the header
+    however the caller spelled the name. There is nothing to refuse.
+
+    Args:
+        filename: The name the caller gave the file, as ``NamedFile.filename`` holds it.
+
+    Returns:
+        The header value -- ``attachment``, and whichever parameters can carry the name."""
+    plain = "".join(c for c in filename if c.isascii() and c.isprintable() and c not in '"\\')
+    parameters = [f'filename="{plain}"'] if plain else []
+    if plain != filename:
+        parameters.append(f"filename*=UTF-8''{quote(filename, safe='', encoding='utf-8')}")
+    return "; ".join(["attachment", *parameters])
+
+
+def safe_filename(filename: str) -> str:
+    """Reduce a server-supplied filename to a name safe to create in a directory.
+
+    Basename first, under both separator flavours -- ``Content-Disposition`` is
+    attacker-controlled and ``filename="../../etc/passwd"`` reaches the parser unchanged -- then
+    strip what Windows refuses: ``<>:"|?*``, unprintable characters, and trailing dots or spaces.
+    Dropping the colon also neutralises an NTFS alternate-data-stream name. What remains is
+    refused rather than mangled when it cannot safely name a file: a reserved device-name stem
+    (``CON``, ``NUL``, ``COM1``... -- Windows 10 resolves even ``CON.pdf`` to the console device,
+    and a bare ``NUL`` open "succeeds" while the bytes go to the null device) or a name past 255
+    characters, the per-component ceiling on NTFS and most POSIX filesystems.
+
+    Args:
+        filename: The server's suggestion, as :func:`content_disposition_filename` returned it.
+
+    Returns:
+        The reduced name, never empty.
+
+    Raises:
+        ValueError: If nothing safe remains -- an empty reduction, ``.`` or ``..``, a reserved
+            device name, or a name too long to create."""
+    basename = _SEPARATORS.split(filename)[-1]
+    cleaned = "".join(ch for ch in basename if ch not in _WINDOWS_ILLEGAL and ch.isprintable())
+    cleaned = cleaned.rstrip(". ")
+    # A reserved stem is matched as Windows does: up to the first dot, trailing spaces ignored.
+    stem = cleaned.split(".", 1)[0].rstrip(" ")
+    if not cleaned or stem.upper() in _WINDOWS_RESERVED or len(cleaned) > 255:
+        raise ValueError(f"{filename!r} reduces to nothing safe to create -- pass an explicit file path instead")
+    return cleaned

swagger_petstore_open_api_3_1_0/core/_internal/flattening.py

@@ -0,0 +1,104 @@
+"""Flattening parameters into wire pairs.
+
+A parameter's value can be a scalar, a model, a mapping, or a collection of any of those, and how a
+*collection* explodes into keys depends on the parameter's :class:`SerializationFormat`. This module
+does that flattening once; both destinations that carry pairs -- a query string and a form body --
+then reach the wire through ``urls.urlencode_params``.
+
+Each parameter arrives carrying the adapter for its declared type, so the wire *format* is decided
+there rather than here: :func:`wire_value` dumps through that adapter -- the same step the path and
+header renderers use -- and this module is then concerned only with how the result explodes into
+keys.
+
+Stateless module functions rather than a class: there is nothing to configure, so there was nothing
+for an instance to hold."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Final, TypeAlias
+
+from ..params import Param, SerializationFormat
+from .wire import is_collection, to_text, wire_value
+
+Pairs: TypeAlias = list[tuple[str, str]]
+
+_SEPARATORS: Final = {
+    SerializationFormat.CSV: ",",
+    SerializationFormat.TSV: "\t",
+    SerializationFormat.PSV: "|",
+}
+
+
+def flatten(params: Sequence[Param[Any]] | None) -> Pairs:
+    """Flatten every parameter into ``(key, value)`` pairs, in order.
+
+    Args:
+        params: The parameters to flatten; ``None`` is treated as none at all.
+
+    Returns:
+        ``(key, text)`` pairs, a repeated key appearing once per value.
+
+    Raises:
+        ValueError: If a parameter's value does not match its declared type."""
+    pairs: Pairs = []
+    for param in params or ():
+        pairs.extend(_flatten_value(key=param.key, value=wire_value(param), fmt=param.serialization_format))
+    return pairs
+
+
+def _flatten_value(*, key: str, value: object, fmt: SerializationFormat) -> Pairs:
+    if value is None:
+        return []
+
+    if isinstance(value, Mapping):
+        return [
+            pair
+            for child_key, child_value in value.items()
+            for pair in _flatten_value(key=f"{key}[{child_key}]", value=child_value, fmt=fmt)
+        ]
+
+    if is_collection(value):
+        values = [v for v in value if v is not None]
+        if not values:
+            return []
+
+        joined = _try_join(values, fmt)
+        if joined is not None:
+            return [(key, joined)]
+
+        if fmt is SerializationFormat.INDEXED:
+            return [
+                pair
+                for index, item in enumerate(values)
+                for pair in _flatten_value(key=f"{key}[{index}]", value=item, fmt=fmt)
+            ]
+
+        if fmt is SerializationFormat.UNINDEXED:
+            return [pair for item in values for pair in _flatten_value(key=f"{key}[]", value=item, fmt=fmt)]
+
+        return [pair for item in values for pair in _flatten_value(key=key, value=item, fmt=fmt)]
+
+    return [(key, to_text(value))]
+
+
+def _try_join(values: Sequence[object], fmt: SerializationFormat) -> str | None:
+    """Join ``values`` with ``fmt``'s separator, or ``None`` if ``fmt`` does not join.
+
+    Args:
+        values: The already-dumped members to join.
+        fmt: The parameter's serialization format.
+
+    Returns:
+        The joined text, or ``None`` when ``fmt`` does not join or a member is itself
+        structured -- both cases leave the caller to explode the members instead."""
+    separator = _SEPARATORS.get(fmt)
+    if separator is None:
+        return None
+
+    # A nested collection or mapping cannot be represented inside a joined scalar, so the
+    # caller falls back to exploding the members under the repeated bare key.
+    if any(isinstance(v, Mapping) or is_collection(v) for v in values):
+        return None
+
+    return separator.join(to_text(v) for v in values)

swagger_petstore_open_api_3_1_0/core/_internal/headers.py

@@ -0,0 +1,243 @@
+"""Rendering, normalizing and resolving request headers, plus reading response headers.
+
+One place decides how header names reach the wire, so the choice is made once rather than at each
+endpoint. Names are lowercased: HTTP/1.1 treats them case-insensitively and HTTP/2 requires
+lowercase, so lowercasing is correct for both and makes the produced mapping comparable.
+
+Lowercasing is also what makes :func:`resolve_headers` case-insensitive by construction: once every
+layer is normalized, an ordinary dict merge cannot let a differently-cased duplicate through.
+
+The layers are not all the same kind, and that asymmetry is deliberate. The API's and the endpoint's
+headers are :class:`Param`s -- spec-derived, so each names the type it was declared as and is
+rendered through it by :func:`render_headers`. A caller's ``extra_headers`` arrives as a plain
+mapping of strings, because a caller-supplied value carries no declared type for an adapter to act
+on.
+
+``Cookie`` is the one field this module knows by name. Every other field takes the later layer and
+discards the earlier; RFC 6265 §5.4 permits at most one ``Cookie``, so its contributors fold into a
+single jar instead."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Final, TypeVar
+
+from pydantic import ValidationError
+from typing_extensions import TypeForm
+
+from ..adapters import adapter_for, validation_target
+from ..params import Param
+from .wire import text_values
+
+T = TypeVar("T")
+
+COOKIE_HEADER: Final = "cookie"
+"""The one field name this module knows, lowercased as every rendered name is.
+
+RFC 6265 §5.4 permits a user agent at most one ``Cookie`` field, so two contributors of a cookie are
+two entries in one jar rather than two claims on one slot -- the only field where a later layer folds
+into an earlier one instead of replacing it."""
+
+
+def fold_cookie_jars(*jars: str | None) -> str:
+    """Join what each layer contributed to the cookie jar, skipping those that contributed nothing.
+
+    Args:
+        jars: Each layer's ``Cookie`` field value, in precedence order.
+
+    Returns:
+        One RFC 6265 §5.4 field value, empty when no layer contributed a cookie."""
+    return "; ".join(jar for jar in jars if jar)
+
+
+def render_headers(headers: Sequence[Param[Any]] | None) -> dict[str, str]:
+    """Render each header parameter into a lowercased name and one field value.
+
+    Rendering and lowercasing in one pass is what keeps :func:`resolve_headers` an ordinary dict
+    merge; within one layer the later of two same-named headers wins, which falls out of the dict.
+    ``Cookie`` is the exception: its contributors fold into one jar, so an endpoint's own cookie and
+    the credential a scheme appended after it survive each other.
+
+    A header contributing nothing -- a ``None`` value, or a collection with no members -- is omitted
+    rather than sent empty, so a lower layer's value survives. Several values fold into one
+    comma-separated field value: RFC 9110's own rule for a repeated header, and OpenAPI's default
+    ``style: simple`` for a header array, with no space after the comma. Folding here is also what
+    keeps ``HttpRequest.headers`` a plain ``Mapping[str, str]``, so no transport has to learn that a
+    header can be multi-valued.
+
+    Args:
+        headers: The header parameters; ``None`` is treated as none at all.
+
+    Returns:
+        Lowercased header names mapped to one field value each; a header contributing nothing is
+        absent.
+
+    Raises:
+        ValueError: If a header's value does not match its declared type, or a flat collection
+            holds a ``None``."""
+    rendered: dict[str, str] = {}
+    for header in headers or ():
+        values = text_values(header)
+        if values:
+            name = header.key.lower()
+            field_value = ",".join(values)
+            if name == COOKIE_HEADER:
+                field_value = fold_cookie_jars(rendered.get(name), field_value)
+            rendered[name] = field_value
+    return rendered
+
+
+def normalize_headers(headers: Mapping[str, str] | None) -> dict[str, str]:
+    """Return already-string headers as a plain dict with lowercased names.
+
+    One layer reaches :func:`resolve_headers` this way and only one: the caller's ``extra_headers``.
+    Every spec-derived layer arrives as a :class:`Param` and goes through :func:`render_headers`.
+
+    Args:
+        headers: Already-string headers, typically a caller's ``extra_headers``.
+
+    Returns:
+        The same mapping with every name lowercased."""
+    return {key.lower(): value for key, value in (headers or {}).items()}
+
+
+def resolve_headers(
+    global_headers: Sequence[Param[Any]],
+    local_headers: Sequence[Param[Any]] | None,
+    *,
+    extra_headers: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Return the headers for one call: the API's, then the endpoint's, then the caller's.
+
+    Every layer is normalized before merging, so a global ``X-Tenant`` is overridden by an
+    endpoint's ``x-tenant`` rather than reaching the wire alongside it -- and a caller's
+    ``extra_headers`` wins over both. That it can override a header the endpoint set is the point of
+    passing it, not an oversight.
+
+    ``Cookie`` is the one field a later layer does not replace. RFC 6265 §5.4 permits at most one of
+    them, so the layers' cookies are several entries in a single jar rather than competing claims on
+    one slot: a caller adding a cookie adds to the credential a scheme contributed instead of
+    silently discarding it.
+
+    ``extra_headers`` is keyword-only. It no longer shares a type with the two layers below it, so
+    an inversion would now be caught -- but it stays keyword-only regardless: the two spec-derived
+    layers are still same-typed and positional, and a caller layer reading as a third peer would
+    misrepresent it as something the API prescribes.
+
+    Args:
+        global_headers: What the API prescribes for every call.
+        local_headers: What this one endpoint declares, plus whatever its scheme contributed; wins
+            over the API's.
+        extra_headers: What the caller passed for this one request; wins over both.
+
+    Returns:
+        The effective headers, names lowercased so the merge is case-insensitive.
+
+    Raises:
+        ValueError: If a header's value does not match its declared type."""
+    normalized_global_headers = render_headers(global_headers)
+    normalized_local_headers = render_headers(local_headers)
+    normalized_extra_headers = normalize_headers(extra_headers)
+
+    resolved = normalized_global_headers | normalized_local_headers | normalized_extra_headers
+    jar = fold_cookie_jars(
+        normalized_global_headers.get(COOKIE_HEADER),
+        normalized_local_headers.get(COOKIE_HEADER),
+        normalized_extra_headers.get(COOKIE_HEADER),
+    )
+    if jar:
+        resolved[COOKIE_HEADER] = jar
+    return resolved
+
+
+def read_header(headers: Mapping[str, str], name: str, declared: TypeForm[T]) -> T | None:
+    """Read one response header as its declared type. Paging selectors that read a header use this.
+
+    The value is validated in lax mode, so ``read_header(headers, name, bool)`` accepts ``1``, ``0``,
+    ``true`` and ``false`` in any case.
+
+    Args:
+        headers: The response headers. Names may be in any case.
+        name: The header to read, matched case-insensitively.
+        declared: The type to validate the trimmed value into.
+
+    Returns:
+        The validated value. ``None`` if the header is missing, blank or fails validation, so a bad header
+        from the server never raises in the middle of a walk."""
+    text = find_header(headers, name)
+    if text is None:
+        return None
+    try:
+        return adapter_for(validation_target(declared)).validate_python(text)
+    except ValidationError:
+        return None
+
+
+def find_link_target(headers: Mapping[str, str], *, header_name: str, rel: str) -> str | None:
+    """Return the target of the first entry of an RFC 8288 link header whose ``rel`` includes ``rel``.
+
+    The header is the one the operation's pointer names, ``Link`` when the API follows RFC 8288 to the letter.
+    Entries are split on commas outside quotes, and parameters on semicolons outside quotes. ``rel`` is
+    matched case-insensitively against each entry's space-separated ``rel`` list. Backslash escapes inside
+    quotes are not unescaped. ``header_name`` and ``rel`` are keyword-only: both are strings, so a swap would
+    otherwise type-check.
+
+    Args:
+        headers: The response headers. Names may be in any case.
+        header_name: The header to read, matched case-insensitively.
+        rel: The relation to find, such as ``"next"``.
+
+    Returns:
+        The target as written. ``None`` if the header is missing or blank, no entry has that ``rel``, or a
+        ``<`` has no closing ``>``."""
+    value = find_header(headers, header_name)
+    if value is None:
+        return None
+    index = 0
+    while (index := value.find("<", index)) >= 0:
+        target_end = value.find(">", index + 1)
+        if target_end < 0:
+            return None
+        target = value[index + 1 : target_end]
+        parameters_end = _find_unquoted(value, ",", target_end + 1)
+        if _rel_matches(value[target_end + 1 : parameters_end], rel):
+            return target
+        index = parameters_end
+    return None
+
+
+def find_header(headers: Mapping[str, str], name: str) -> str | None:
+    """Return the trimmed value of the first header named ``name``, matched case-insensitively.
+
+    A blank value counts as missing and returns ``None``. Used by :func:`read_header`,
+    :func:`find_link_target` and ``retries.retry_after_seconds``."""
+    value = next(
+        (field_value for field_name, field_value in headers.items() if field_name.lower() == name.lower()), None
+    )
+    if value is None:
+        return None
+    text = value.strip()
+    return text if text else None
+
+
+def _find_unquoted(text: str, delimiter: str, start: int) -> int:
+    in_quotes = False
+    for i in range(start, len(text)):
+        if text[i] == '"':
+            in_quotes = not in_quotes
+        elif text[i] == delimiter and not in_quotes:
+            return i
+    return len(text)
+
+
+def _rel_matches(parameters: str, rel: str) -> bool:
+    start = 0
+    while start < len(parameters):
+        end = _find_unquoted(parameters, ";", start)
+        parameter = parameters[start:end]
+        start = end + 1
+        name, separator, value = parameter.partition("=")
+        if not separator or name.strip().lower() != "rel":
+            continue
+        return any(rel_type.lower() == rel.lower() for rel_type in value.strip().strip('"').split(" "))
+    return False