cliV1 0.0.6__py3-none-any.whl

swagger_petstore_open_api_3_1_0/core/_internal/redaction.py

@@ -0,0 +1,208 @@
+"""Masking, for what the runtime prints: header values, URLs and form fields.
+
+The rule is vocabulary knowability: a value is shown only when its name is known-safe, so a credential
+under a name nobody predicted is hidden by default. Every denylist in the research leaked
+in a real run; the allowlist is the one rule that held. A form body is the one denylist: it prints only on
+the caller's opt-in, and no vocabulary of safe form keys exists, so there only the names ``mask_keys`` lists
+are hidden. Stdlib-only on purpose: ``transport.py`` imports this module for ``HttpRequest.__repr__``, and
+``logging.py`` imports ``transport.py``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from collections.abc import Set as AbstractSet
+from typing import Final
+from urllib.parse import unquote_plus, urlsplit, urlunsplit
+
+DEFAULT_PLACEHOLDER: Final = "REDACTED"
+"""What a hidden value prints as unless ``LoggingOptions.redaction_placeholder`` says otherwise -- the OpenTelemetry
+semantic conventions' word for one (ADR-0070, rule 4). A repr and an abandonment warning, which read no options,
+always print this one."""
+
+SAFE_HEADERS: Final = frozenset(
+    {
+        "accept",
+        "accept-charset",
+        "accept-encoding",
+        "accept-language",
+        "accept-ranges",
+        "age",
+        "allow",
+        "cache-control",
+        "connection",
+        "content-disposition",
+        "content-encoding",
+        "content-language",
+        "content-length",
+        "content-md5",
+        "content-range",
+        "content-type",
+        "date",
+        "etag",
+        "expect",
+        "expires",
+        "host",
+        "idempotency-key",
+        "if-match",
+        "if-modified-since",
+        "if-none-match",
+        "if-range",
+        "if-unmodified-since",
+        "keep-alive",
+        "last-modified",
+        "max-forwards",
+        "origin",
+        "pragma",
+        "range",
+        "ratelimit-limit",
+        "ratelimit-policy",
+        "ratelimit-remaining",
+        "ratelimit-reset",
+        "request-id",
+        "retry-after",
+        "server",
+        "te",
+        "trailer",
+        "transfer-encoding",
+        "upgrade",
+        "user-agent",
+        "vary",
+        "via",
+        "warning",
+        "www-authenticate",
+        # W3C trace context
+        "traceparent",
+        "tracestate",
+        # correlation and rate-limit headers outside the standards
+        "x-correlation-id",
+        "x-ratelimit-limit",
+        "x-ratelimit-remaining",
+        "x-ratelimit-reset",
+        "x-request-id",
+        # the runtime's own identification headers (ADR-0045)
+        "x-apimatic-lang",
+        "x-apimatic-package-version",
+        "x-apimatic-gen-version",
+        "x-apimatic-os",
+        "x-apimatic-runtime",
+    }
+)
+"""The 61 header names whose values may be printed: the standard request and response headers that carry no
+credential, lowercased."""
+
+SAFE_QUERY_KEYS: Final = frozenset(
+    {"cursor", "dates", "datetime", "limit", "offset", "page", "since", "size", "strings"}
+)
+"""The nine query keys whose values may be printed: a fixed vocabulary of paging and filter names, as ``SAFE_HEADERS``
+is for headers, the same in every SDK this runtime is vendored into and never derived from a spec. A key an endpoint
+declares but the vocabulary lacks is masked like any other -- the safe direction."""
+
+
+def redact_headers(
+    headers: Mapping[str, str], *, unmask: AbstractSet[str], mask: AbstractSet[str], placeholder: str
+) -> dict[str, str]:
+    """``headers`` with every value replaced by ``placeholder`` unless its name may be shown.
+
+    Precedence: ``unmask`` wins, then ``mask``, then the safe list, then the placeholder. Names
+    are compared as given: the runtime lowercases every header name as it resolves it, and the option
+    sets are lowercased once at the client, so a name that arrives otherwise is masked -- the safe
+    direction.
+
+    Args:
+        headers: The headers to describe, names lowercased by the layer that resolved them.
+        unmask: Names to show regardless of the safe list.
+        mask: Names to hide regardless of the safe list.
+        placeholder: What a hidden value prints as -- the client's ``redaction_placeholder``.
+
+    Returns:
+        The same names in the same order, each value shown or ``placeholder``."""
+    return {
+        name: value if name in unmask or (name not in mask and name in SAFE_HEADERS) else placeholder
+        for name, value in headers.items()
+    }
+
+
+def redact_query(query: str, *, mask_keys: AbstractSet[str], placeholder: str) -> str:
+    """``key=value&...`` with every value replaced by ``placeholder`` unless its key may be shown.
+
+    A value is shown only when its key is in ``SAFE_QUERY_KEYS`` and not in ``mask_keys``: unknown means
+    hidden, the header rule again, so a credential's key -- never a paging name -- is masked without a
+    list naming it. A key is matched by its :func:`base_name`, once unquoted, so the keys a collection
+    explodes into (``strings[0]``, ``strings[]``, ``dates[0]``) answer to the ``strings`` the vocabulary
+    holds, and ``PAGE`` answers to ``page``. Keys are never rewritten; a pair without ``=`` and an empty
+    pair are left as they are.
+
+    Args:
+        query: The encoded pairs, without the leading ``?``.
+        mask_keys: Lowercased names whose values are hidden even when known-safe.
+        placeholder: What a hidden value prints as.
+
+    Returns:
+        The pairs in their order, each value shown or ``placeholder``."""
+    redacted_pairs: list[str] = []
+    for pair in query.split("&"):
+        key, separator, _ = pair.partition("=")
+        name = base_name(unquote_plus(key))
+        redacted_pairs.append(
+            f"{key}={placeholder}" if separator and (name in mask_keys or name not in SAFE_QUERY_KEYS) else pair
+        )
+    return "&".join(redacted_pairs)
+
+
+def redact_form(form: bytes, *, mask_keys: AbstractSet[str], placeholder: str) -> bytes:
+    """A form body's bytes with the value of every key ``mask_keys`` names replaced by ``placeholder``.
+
+    The form-body rule: the walk :func:`redact_query` makes, over the bytes the body carries and with the
+    opposite list -- every value is shown unless its key is named. A key is matched by its :func:`base_name`,
+    once unquoted, as there, so the ``password[0]`` this runtime's INDEXED format writes answers to
+    ``password``, and a key nested in a map answers to its outer name. Keys are never rewritten; a pair
+    without ``=`` and an empty pair are left as they are. Only a key is decoded, to read its name; the body
+    itself is never decoded here.
+
+    Args:
+        form: The encoded pairs of an ``application/x-www-form-urlencoded`` body.
+        mask_keys: Lowercased names whose values are hidden.
+        placeholder: What a hidden value prints as; it is written as UTF-8.
+
+    Returns:
+        The pairs in their order, each value kept or replaced by ``placeholder``."""
+    placeholder_bytes = placeholder.encode("utf-8")
+    redacted_pairs: list[bytes] = []
+    for pair in form.split(b"&"):
+        key, separator, _ = pair.partition(b"=")
+        name = base_name(unquote_plus(key.decode("utf-8", errors="replace")))
+        redacted_pairs.append(key + b"=" + placeholder_bytes if separator and name in mask_keys else pair)
+    return b"&".join(redacted_pairs)
+
+
+def redact_url(url: str, *, mask_keys: AbstractSet[str] = frozenset(), placeholder: str = DEFAULT_PLACEHOLDER) -> str:
+    """The form of ``url`` that may be printed: userinfo dropped, query values masked, keys kept.
+
+    The one printable-URL rule, for a log line, a repr and the abandonment warnings alike. The query
+    goes through :func:`redact_query`; the defaults are the form a repr or a warning uses, having no
+    options to read, and print what a client with default options logs, since no known-safe key is
+    among the default ``mask_keys``. Total: a URL the parser refuses is described rather than raised
+    on, since this runs inside a log call and a finalizer.
+
+    Args:
+        url: The URL to describe.
+        mask_keys: Query keys whose values are hidden even when known-safe.
+        placeholder: What a hidden value prints as.
+
+    Returns:
+        ``scheme://host[:port]/path[?masked query][#fragment]``, or ``<unparseable url>``."""
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return "<unparseable url>"
+    query = redact_query(parts.query, mask_keys=mask_keys, placeholder=placeholder) if parts.query else ""
+    return urlunsplit(parts._replace(netloc=parts.netloc.rpartition("@")[2], query=query))
+
+
+def base_name(key: str) -> str:
+    """The name ``mask_keys`` and ``SAFE_QUERY_KEYS`` match ``key`` by: cut before the first ``[``, lowercased.
+
+    So the keys a collection explodes into (``strings[0]``, ``strings[]``) and a key nested in a map
+    (``filter[name]``) answer to their outer name, and ``PAGE`` answers to ``page``. A query or form key is
+    unquoted before it comes here; a multipart field name is not, since it is never percent-encoded."""
+    return key.partition("[")[0].lower()

swagger_petstore_open_api_3_1_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)."""
+
+_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_1_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}"
+            )

swagger_petstore_open_api_3_1_0/core/_internal/urls.py

@@ -0,0 +1,172 @@
+"""Turning a :class:`UrlTemplate` plus parameters into a request URL.
+
+Five pure functions in four 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 six 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 urlencode_params(params: Sequence[Param[Any]] | None) -> str:
+    """Flatten ``params`` and percent-encode them as ``application/x-www-form-urlencoded`` pairs.
+
+    One encoder for both destinations that carry pairs -- a query string (:func:`build_url`, which
+    adds the ``?``) and a form body (``form_body``) -- so one parameter renders to the same bytes
+    wherever it goes. Pair order is the parameters' order, a repeated key once per value. Non-ASCII
+    text is UTF-8 encoded and then percent-encoded (``urlencode``'s default, and the WHATWG rule),
+    so the result is ASCII.
+
+    Args:
+        params: The parameters to render; ``None`` is treated as none at all.
+
+    Returns:
+        The encoded pairs, 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 = urlencode_params(query_params)
+    return f"{url}?{query}" if query else url