cliV1 0.0.8__py3-none-any.whl

swagger_petstore_open_api_3_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_0/core/_internal/flattening.py

@@ -0,0 +1,139 @@
+"""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, for both destinations that need it: query strings
+(``urls.encode_query`` encodes the pairs) and form bodies
+(:func:`to_fields` collects them into a mapping).
+
+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 to_fields(params: Sequence[Param[Any]]) -> dict[str, str | list[str]]:
+    """Flatten ``params`` into a mapping, collecting repeated keys into a list.
+
+    This is the shape a form body takes: unlike a query string, which can repeat a key, a form
+    mapping needs the repeats gathered under one entry.
+
+    Every value is text or a list of text, never anything richer: :func:`flatten` has already
+    reduced each parameter to ``(key, value)`` pairs of ``str``, so the only structure left to
+    add here is the list a repeated key collects into.
+
+    Args:
+        params: The parameters to flatten into fields.
+
+    Returns:
+        Each key mapped to its text, or to the list of texts it collected.
+
+    Raises:
+        ValueError: If a parameter's value does not match its declared type."""
+    fields: dict[str, str | list[str]] = {}
+
+    for key, value in flatten(params):
+        if key not in fields:
+            fields[key] = value
+            continue
+
+        existing = fields[key]
+        if isinstance(existing, list):
+            existing.append(value)
+        else:
+            fields[key] = [existing, value]
+
+    return fields
+
+
+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_0/core/_internal/headers.py

@@ -0,0 +1,144 @@
+"""Rendering, normalizing and resolving request 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
+
+from ..params import Param
+from .wire import text_values
+
+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

swagger_petstore_open_api_3_0/core/_internal/sse_parser.py

@@ -0,0 +1,124 @@
+"""Parsing the ``text/event-stream`` grammar: bytes in, event data out.
+
+The WHATWG algorithm ("Server-sent events", HTML Standard) written as a push parser, so one
+implementation serves both flavours: a consumer hands over each chunk the transport delivers and takes
+back the events those bytes completed, and nothing here touches the wire. Per the standard: one leading
+UTF-8 BOM is dropped; a line ends at CRLF, LF or CR; a line starting with ``:`` is a comment; ``data``
+accumulates and its values join with LF; a blank line dispatches, but only when a ``data`` line was seen,
+otherwise it resets; ``event``, ``id`` and ``retry`` are recognised so they are ignored correctly, and so
+is any other field -- only ``data`` reaches the consumer.
+
+Lines are found with ``bytes.splitlines``, which knows exactly the standard's three terminators and no
+others -- unlike ``str.splitlines``, which also cuts on ``\\x0b``, ``\\x0c``, ``\\x1c`` to ``\\x1e``,
+``\\x85`` and U+2028/9 and would split a payload holding one of them. It is one C pass per chunk,
+measured at a twelfth of a regex loop's cost, and only the new chunk is ever scanned: the unfinished tail
+of the previous chunk is carried and joined onto the first line the next chunk completes, so parsing
+stays linear in the bytes received however small the chunks.
+
+Two things the standard leaves to the client. A CR at the very end of a chunk is a terminator on its own,
+and the LF that may follow it in the next chunk is then skipped, so a CRLF split across two reads is one
+terminator, never two -- and the event dispatches the moment its CR arrives rather than waiting for the
+next chunk. And an event still pending at EOF is dropped, as the standard's processing model says and as
+the .NET parser does: a truncated final event is not delivered as if it were whole.
+
+Each completed line is decoded as UTF-8 on its own, strictly. That is exact rather than a shortcut: both
+terminator bytes are ASCII, and in UTF-8 an ASCII byte is never part of a multi-byte sequence, so a line
+boundary cannot fall inside a character and no incremental decoder is needed. A line that is not UTF-8
+raises the stdlib's ``UnicodeDecodeError``, unwrapped: it already names the offending byte and position.
+The one bound is on bytes held for an event that has not dispatched -- the carried tail plus the ``data``
+already collected -- so a server that never sends a blank line is refused at 1 MiB with a ``ValueError``
+instead of growing the buffer without limit."""
+
+from __future__ import annotations
+
+from typing import Final
+
+MAX_EVENT_BYTES: Final = 1 << 20
+"""Bytes held for one undispatched event before the stream is refused (1 MiB, Fern's bound)."""
+
+_BOM: Final = b"\xef\xbb\xbf"
+_LINE_ENDS: Final = (b"\n", b"\r")
+
+
+class SseParser:
+    """The push parser: ``parse_chunk`` each chunk as the transport delivers it, take back the events it completed."""
+
+    __slots__ = ("_at_start", "_data", "_pending", "_skip_lf", "_tail")
+
+    def __init__(self) -> None:
+        self._tail = bytearray()  # the unfinished line of the last chunk; never holds a terminator
+        self._at_start = True
+        self._skip_lf = False
+        self._data: list[str] = []
+        self._pending = 0
+
+    def parse_chunk(self, chunk: bytes) -> list[str]:
+        """Consume ``chunk`` and return the data of every event it completed, in order.
+
+        Args:
+            chunk: The next bytes off the wire, of any length including zero.
+
+        Returns:
+            Each dispatched event's ``data``, its lines already joined with LF.
+
+        Raises:
+            ValueError: If the pending event outgrows :data:`MAX_EVENT_BYTES`, or -- as a
+                ``UnicodeDecodeError`` -- if a line is not valid UTF-8."""
+        if chunk and self._skip_lf:
+            # The previous chunk ended on a CR that was treated as a terminator; a leading LF now is the
+            # other half of that CRLF, not a blank line. An empty chunk decides nothing, so the flag waits.
+            self._skip_lf = False
+            if chunk[:1] == b"\n":
+                chunk = chunk[1:]
+        if self._at_start:
+            self._tail += chunk
+            if len(self._tail) < len(_BOM) and _BOM.startswith(self._tail):
+                return []
+            if self._tail.startswith(_BOM):
+                del self._tail[: len(_BOM)]
+            self._at_start = False
+            chunk = bytes(self._tail)
+            self._tail.clear()
+
+        # bytes.splitlines knows exactly SSE's three terminators; keepends tells the last piece apart --
+        # terminated, or an unfinished tail to carry into the next chunk.
+        pieces = chunk.splitlines(keepends=True)
+        unfinished = pieces.pop() if pieces and not pieces[-1].endswith(_LINE_ENDS) else b""
+        if pieces:
+            pieces[0] = bytes(self._tail) + pieces[0]
+            self._tail.clear()
+            self._skip_lf = not unfinished and pieces[-1].endswith(b"\r")
+        self._tail += unfinished
+
+        events: list[str] = []
+        for piece in pieces:
+            data = self._line(piece)
+            if data is not None:
+                events.append(data)
+        if len(self._tail) + self._pending > MAX_EVENT_BYTES:
+            raise ValueError(
+                f"an event exceeded {MAX_EVENT_BYTES} bytes without dispatching -- refusing to buffer further"
+            )
+        return events
+
+    def _line(self, raw: bytes) -> str | None:
+        # ``raw`` is one terminated line, so the strip removes exactly its CRLF, LF or CR. Strict decode:
+        # bad bytes raise UnicodeDecodeError straight out of parse_chunk.
+        line = raw.rstrip(b"\r\n").decode("utf-8")
+        if not line:
+            return self._dispatch()
+        if line.startswith(":"):
+            return None
+        name, colon, value = line.partition(":")
+        if name == "data":
+            self._data.append(value[1:] if colon and value.startswith(" ") else value)
+            self._pending += len(raw)
+        return None
+
+    def _dispatch(self) -> str | None:
+        if not self._data:
+            return None
+        data = "\n".join(self._data)
+        self._data = []
+        self._pending = 0
+        return data

swagger_petstore_open_api_3_0/core/_internal/subscripts.py

@@ -0,0 +1,50 @@
+"""What every subscripted factory shares: refusing to be called.
+
+The fence itself is static and lives in each factory's *absence* of a ``__call__``; this module
+carries only the message a caller sees when they trip it at runtime."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+class SubscriptOnly:
+    """A factory whose declared type is structurally mandatory.
+
+    Fourteen factories across ``params``, ``bodies`` and ``decoding`` name their type in a subscript
+    (ADR-0013). Thirteen of the fourteen declare no ``__call__`` a type checker can see, so omitting
+    the subscript is an ``[operator]`` error at the call site -- that is the fence, and it is entirely
+    static; ``decode_text`` is the exception, and the last paragraph says why. What this
+    class carries is the *courtesy*: a runtime ``__call__``, invisible to the checker, turning
+    Python's bare "object is not callable" into a message that names the right spelling.
+
+    Subclasses supply the two facts the message is built from, as class attributes or as fields of
+    their own. What a base may **not** share is a ``__getitem__``'s *return shape*: it depends on the
+    subscripted type, and Python has no higher-kinded types, so no base can parametrise over it --
+    the precision ADR-0013 exists for, the reason ``json_decoder[int]`` is rejected where
+    ``ApiResult[str, ...]`` is declared. Two factories over the *same* shape may share a class and
+    tell themselves apart by a field, because what they then differ in -- a body's format, say, or
+    which adapter entry point reads an event's ``data`` -- carries no type at all. Only a shape
+    does.
+
+    ``decode_text`` is the one member of the family that does **not** inherit this: its bare call is
+    the ``str`` default, so its ``__call__`` is real, typed, and meant to be reached."""
+
+    # Empty rather than naming the two attributes below: a subclass supplies them either as class
+    # attributes or as its own dataclass fields, and claiming them here would collide with the
+    # latter. Without this line the ``slots=True`` the dataclass subclasses declare buys nothing --
+    # a slotted class over an unslotted base still gets a ``__dict__`` per instance.
+    __slots__ = ()
+
+    factory_name: str
+    """How the caller spells the factory -- ``json_decoder``, ``param``."""
+
+    spelling: str
+    """The correct form, with an example: ``param[T](key, value), e.g. param[bool]("array", True)``."""
+
+    if not TYPE_CHECKING:
+
+        def __call__(self, *args, **kwargs):
+            raise TypeError(
+                f"{self.factory_name} is not called -- name the declared type in its subscript: {self.spelling}"
+            )