cliV1 0.1.1__py3-none-any.whl

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/urls.py

@@ -0,0 +1,166 @@
+"""Turning a :class:`UrlTemplate` plus parameters into a request URL.
+
+Five pure functions in three groups. :func:`resolve_params` combines the parameters an API applies
+to every request with the ones a single call declares; :func:`render_segments` turns each of those
+into the URL segments it contributes, reading its declared type; :func:`build_url` then renders the
+result, with server variables filling the base URL's placeholders, path parameters filling the
+path's, and query parameters flattened and encoded onto the end. Resolution stays separate from
+rendering so each can be tested on its own, and none of the five holds state -- there is nothing to
+configure, so there is nothing to construct."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any, Final
+from urllib.parse import quote, urlencode
+
+from ..params import Param, UrlTemplate
+from .flattening import flatten
+from .wire import text_values
+
+_PLACEHOLDER: Final = re.compile(r"\{([^{}]+)\}")
+
+
+def expand_template(template: str, segments: Mapping[str, tuple[str, ...]]) -> str:
+    """Substitute every ``{placeholder}`` in ``template`` from ``segments``.
+
+    Each value is the sequence of *unencoded* members its placeholder expands from. Members are
+    percent-encoded with no safe characters and joined with ``,``, so a collection fills one path
+    segment rather than several -- OpenAPI's ``style: simple`` with ``explode: false``, the default
+    for a path parameter, and the same rule ``headers.py`` applies to a header array.
+
+    Encoding happens per member, *before* the join, which is what keeps the two commas apart: the
+    separator is written here and stays literal (a sub-delimiter under RFC 3986), while a comma
+    carried by a value is encoded to ``%2C`` along with everything else non-unreserved. A value
+    still cannot inject a path separator, for the same reason.
+
+    Any ``{name}`` is a placeholder -- the braces delimit it, so the name is not restricted to word
+    characters and a kebab-case or dotted path parameter resolves like any other. A name with no
+    segment raises rather than passing through: unencoded braces are not valid in a URL anyway.
+
+    Deciding what a value's members *are* belongs to :func:`render_segments`, which is the only
+    thing holding a declared type. This function therefore has one rule rather than four, and both
+    the join and the encoding live in exactly one place.
+
+    Args:
+        template: The URL or path holding the ``{placeholder}`` tokens.
+        segments: Each placeholder name mapped to its unencoded members.
+
+    Returns:
+        ``template`` with every placeholder substituted, each member percent-encoded.
+
+    Raises:
+        ValueError: If ``template`` is empty, or names a placeholder ``segments`` has no entry
+            for."""
+    if not template:
+        raise ValueError("URL template must not be empty")
+
+    def replace(match: re.Match[str]) -> str:
+        key = match.group(1)
+        if key not in segments:
+            raise ValueError(f"Missing template parameter: {key}")
+        return ",".join(quote(segment, safe="") for segment in segments[key])
+
+    return _PLACEHOLDER.sub(replace, template)
+
+
+def render_segments(params: Sequence[Param[Any]] | None) -> dict[str, tuple[str, ...]]:
+    """Render each parameter into the URL segments its ``{placeholder}`` expands to.
+
+    Serves a path parameter and a base URL's server variable alike -- both fill a placeholder and
+    both name the type they were declared as, so there is one rule rather than two.
+
+    Members, not finished text: :func:`expand_template` owns the ``,`` join and the
+    percent-encoding, so neither is written twice and no value can inject a path separator.
+
+    Args:
+        params: The path parameters or server variables; ``None`` is treated as none at all.
+
+    Returns:
+        Each parameter's key mapped to the unencoded members its placeholder expands to.
+
+    Raises:
+        ValueError: If a parameter contributes no value at all -- a placeholder cannot be left
+            unfilled -- or if its value does not match its declared type."""
+    rendered: dict[str, tuple[str, ...]] = {}
+    for param in params or ():
+        segments = text_values(param)
+        if not segments:
+            raise ValueError(f"URL parameter has no value: {param.key}")
+        rendered[param.key] = segments
+    return rendered
+
+
+def encode_query(params: Sequence[Param[Any]] | None) -> str:
+    """Flatten ``params`` and percent-encode them into a query string (no leading ``?``).
+
+    Args:
+        params: The query parameters; ``None`` is treated as none at all.
+
+    Returns:
+        The encoded query string, empty when nothing was contributed.
+
+    Raises:
+        ValueError: If a parameter's value does not match its declared type."""
+    return urlencode(flatten(params))
+
+
+def resolve_params(
+    global_params: Sequence[Param[Any]], call_params: Sequence[Param[Any]] | None
+) -> tuple[Param[Any], ...]:
+    """Return the parameters for one call, the call's winning per key.
+
+    One function for both kinds that need it: a path parameter and a query parameter are the same
+    type, so they are the same rule -- a call's parameter replaces a global of the same key but
+    keeps the global's position, so what an endpoint produces does not depend on which side supplied
+    a parameter. Keys are unique within either side -- a collection is carried by a single
+    :class:`Param` and expanded by its destination, never by repeating the key -- so replacing
+    rather than appending is unambiguous.
+
+    Both arguments share a type, so the precedence lives in their names rather than in the function
+    name: ``global_params`` is what the API prescribes, ``call_params`` what this one call declares.
+
+    Headers resolve separately, since they merge case-insensitively -- which ``render_headers`` gets
+    by lowercasing as it renders. Placeholders in a *base URL* are server variables, carried on the
+    :class:`UrlTemplate` itself and rendered by :func:`build_url`.
+
+    Args:
+        global_params: What the API prescribes for every call.
+        call_params: What this one call declares; wins per key.
+
+    Returns:
+        The effective parameters, each key once, in the order the global set established."""
+    by_key = {param.key: param for param in (*global_params, *(call_params or ()))}
+    return tuple(by_key.values())
+
+
+def build_url(
+    url_template: UrlTemplate,
+    *,
+    path_params: Sequence[Param[Any]] | None = None,
+    query_params: Sequence[Param[Any]] | None = None,
+) -> str:
+    """Resolve ``url_template`` into a complete request URL.
+
+    Args:
+        url_template: The unresolved URL, carrying its base URL, path and server variables.
+        path_params: The call's path parameters.
+        query_params: The call's query parameters.
+
+    Returns:
+        The absolute URL, base and path joined on exactly one ``/``, query appended when non-empty.
+
+    Raises:
+        ValueError: If a placeholder is unfilled or a parameter's value does not match its
+            declared type."""
+    base = expand_template(url_template.base_url, render_segments(url_template.variables))
+    path = expand_template(url_template.path, render_segments(path_params))
+
+    # Join on exactly one separator. Plain urljoin would be wrong here: it treats the base as a
+    # document reference and discards its last path segment, so a base of ".../v2" with path
+    # "users" would resolve to ".../users", silently dropping the version.
+    url = f"{base.rstrip('/')}/{path.lstrip('/')}"
+
+    query = encode_query(query_params)
+    return f"{url}?{query}" if query else url

swagger_petstore_open_api_3_0/core/_internal/wire.py

@@ -0,0 +1,173 @@
+"""One declared value, one wire-ready form.
+
+Every request parameter -- query, form, path, header, or a base URL's server variable -- reaches
+the wire the same way: validated against the type the endpoint declared, dumped through that
+type's adapter, and turned into text. Only the *arrangement* differs, and that stays with each
+destination: :mod:`.form` explodes values into ``key[sub]`` pairs, :mod:`.urls` joins them into
+``/``-separated segments, :mod:`.headers` folds them into one field value.
+
+That shared prefix lives here, which is why a ``datetime`` declared ``RFC1123DateTime`` renders as
+its GMT string at every destination without any of them knowing what a datetime is -- and why a
+fifth destination would need no serialization code of its own."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import Any, TypeGuard
+
+from pydantic import ValidationError
+
+from ..optionality import strip_unset
+from ..params import Param
+
+
+def wire_value(param: Param[Any]) -> object:
+    """``param``'s value in wire form: validated against its declared type, then dumped.
+
+    The same two steps, in the same order, as :func:`json_body` -- and the reason a parameter
+    holds its resolved adapter rather than the type expression it came from. Validation coerces
+    dict-shaped input (``Model | FooDict`` companions) through the model's own rules; the dump
+    applies the type's serializer, which is what renders an ``RFC1123DateTime`` as its GMT string,
+    an enum as its value and a model under its wire aliases.
+
+    A validation failure is re-raised naming the parameter: pydantic titles the error by the
+    *type* (``1 validation error for int``), which on an endpoint with five parameters leaves the
+    caller guessing which one failed. ``ValidationError`` subclasses ``ValueError``, so a caller's
+    ``except ValueError`` covers both spellings, and the full per-field detail rides ``__cause__``.
+
+    ``strip_unset`` is what drops a field the caller never touched, and the only thing that can:
+    ``UnsetType`` is not ``None``, so the dump keeps the key and it serializes as ``null``, which a
+    JSON-encoded path segment or header value would carry verbatim. An *explicit* ``None`` is
+    kept -- see docs/designs/optional-nullable-fields.md. Which of those nulls survives is the
+    destination's own decision, taken in :func:`text_values` and ``flattening.flatten``: compact
+    JSON can spell one, a query pair or a flat path segment cannot.
+
+    The result is still structured -- a collection stays a list, a model stays a mapping -- because
+    the query and form destination needs that shape to explode into ``key[sub]`` keys.
+
+    Args:
+        param: The parameter to render, carrying its declared type's adapter.
+
+    Returns:
+        The dumped value, still structured; a top-level set is sorted so one call yields one URL.
+
+    Raises:
+        ValueError: If the value does not match its declared type. The message names the
+            parameter; pydantic's per-field detail rides ``__cause__``."""
+    try:
+        validated = param.adapter.validate_python(param.value)
+    except ValidationError as error:
+        raise ValueError(f"Parameter value does not match its declared type: {param.key}") from error
+
+    dumped: object = strip_unset(validated, param.adapter.dump_python(validated, mode="json"))
+
+    # JSON has no set, so the dump has already flattened one into a list in hash-iteration order.
+    # Sorting is what keeps one call producing one URL across runs. A *top-level* set is the whole
+    # reach on purpose: a set nested inside a container is not an emittable declared type --
+    # ``adapters.py``'s ``_CONTAINERS`` and ``strip_unset`` close at ``list``/``dict`` for the same
+    # reason -- so walking deeper would be speculative surface for a shape no spec yields.
+    if isinstance(validated, (set, frozenset)) and isinstance(dumped, list):
+        return sorted(dumped, key=str)
+
+    return dumped
+
+
+def text_values(param: Param[Any]) -> tuple[str, ...]:
+    """``param`` as the flat texts it contributes -- one per path segment or header list member.
+
+    Empty means it contributes nothing: its value was ``None``, or its collection was. A scalar is
+    one text, a flat collection is one text per member, and anything structured -- a mapping, a
+    model, or a collection holding either -- is one text of compact JSON, since neither a path
+    segment nor a header value can carry a nested shape any other way.
+
+    The arrangement is settled *before* the ``None`` rule, because the two arrangements can
+    represent different things: compact JSON spells ``null``, so a structured collection carries a
+    ``None`` member as one, while a flat collection has no such spelling and refuses it.
+
+    Args:
+        param: The parameter to render.
+
+    Returns:
+        One text per segment or header member; empty when the parameter contributes nothing.
+
+    Raises:
+        ValueError: If the value does not match its declared type, or if a *flat* collection holds
+            a ``None`` -- neither a path segment nor a header member can spell one."""
+    value = wire_value(param)
+    if value is None:
+        return ()
+
+    if isinstance(value, Mapping):
+        return (compact_json(value),)
+
+    if not is_collection(value):
+        return (to_text(value),)
+
+    members = list(value)
+    if any(isinstance(member, Mapping) or is_collection(member) for member in members):
+        return (compact_json(members),)
+
+    if any(member is None for member in members):
+        # Query and form encoding can drop a member, because it can also repeat or omit a key.
+        # Neither of these destinations can: a path would address a different route and a header
+        # would carry an empty list slot, both silently.
+        raise ValueError(f"Parameter value contains None: {param.key}")
+
+    return tuple(to_text(member) for member in members)
+
+
+def to_text(value: object) -> str:
+    """One dumped scalar as the text a URL or a header carries.
+
+    The adapter has already applied wire aliases, enum values and temporal formats, so only
+    booleans are left: every destination here is text and expects JSON's ``true``/``false``,
+    whereas ``str(True)`` would emit ``True``. Called only where a value actually becomes text,
+    which is what lets the structured branches above keep real booleans for :func:`compact_json`.
+
+    Args:
+        value: One already-dumped scalar.
+
+    Returns:
+        Its text form, with booleans lowercased to JSON's spelling."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+
+    return str(value)
+
+
+def compact_json(value: object) -> str:
+    """JSON-encode a structured value with no insignificant whitespace.
+
+    ``ensure_ascii`` stays at its default: a header field value is ISO-8859-1 by RFC 9110 and the
+    transport rejects anything outside it, so escaping non-ASCII is the only encoding that
+    survives. ``allow_nan`` is turned off: at its default a non-finite float encodes as
+    ``Infinity`` or ``NaN`` -- a Python dialect no RFC 8259 parser accepts -- so the call would
+    fail server-side, far from the line that produced the value.
+
+    Args:
+        value: The structured value to encode.
+
+    Returns:
+        Its JSON text, non-ASCII escaped and no insignificant whitespace.
+
+    Raises:
+        ValueError: If ``value`` holds a non-finite float, which has no RFC 8259 spelling."""
+    return json.dumps(value, separators=(",", ":"), allow_nan=False)
+
+
+def is_collection(value: object) -> TypeGuard[Iterable[object]]:
+    """True for an iterable that should expand into several wire values.
+
+    ``TypeGuard``, deliberately not the newer ``TypeIs``: ``TypeIs`` also narrows the *negative*
+    branch, which would be unsound here -- ``str`` is ``Iterable`` yet this returns ``False`` for
+    it, so a checker told "not an ``Iterable``" would wrongly rule out strings. ``TypeGuard``
+    narrows only where this returns ``True``, which is exactly what the caller needs to iterate.
+
+    Args:
+        value: The dumped value to classify.
+
+    Returns:
+        ``True`` for an iterable that expands into several wire values -- a ``str``, ``bytes`` or
+        ``Mapping`` is one value, not several."""
+    return isinstance(value, Iterable) and not isinstance(value, (str, bytes, Mapping))