lothc 0.2.0__tar.gz → 0.2.2__tar.gz

{lothc-0.2.0 → lothc-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lothc
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lord Of The Http Clients — a typed HTTP client built on pyreqwest, with first-class pydantic and msgspec support
 Project-URL: Homepage, https://github.com/RogerThomas/lothc
 Project-URL: Repository, https://github.com/RogerThomas/lothc
@@ -12,6 +12,7 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: pyreqwest>=0.13.0
@@ -110,7 +111,7 @@ validate yourself. Any type expression works, so `into=list[Pokemon]` decodes a
 | | |
 |---|---|
 | **Two clients, one API** | `HTTPClient` (async) and `SyncHTTPClient` (sync) — identical surface, both backed by pyreqwest. |
-| **Every verb** | `get`, `post`, `put`, `patch`, `delete`, `head`, `download` (each returning a `Response`: `.data`, `.status`, `.headers`) — see [Verbs](https://rogerthomas.github.io/lothc/verbs/). |
+| **Every verb** | `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `download` (each returning a `Response`: `.data`, `.status`, `.headers`) — see [Verbs](https://rogerthomas.github.io/lothc/verbs/). |
 | **Typed params, headers & forms** | A `BaseModel`/`Struct` for query params or headers (with `None`-field omission), or a body sent urlencoded (`data=`) or as a real multipart form (`form=`). |
 | **Precise static types** | Every verb is paired `@overload`s, not a cast-laden generic — your editor knows the exact return type. |
 | **SSE & streaming** | Spec-compliant SSE — automatic reconnect with `Last-Event-ID`, server `retry:` honored, typed decode (discriminated unions included) — plus raw or NDJSON-typed `stream_get`/`stream_post` — see [SSE](https://rogerthomas.github.io/lothc/sse/) / [Streaming](https://rogerthomas.github.io/lothc/streaming/). |

{lothc-0.2.0 → lothc-0.2.2}/README.md

@@ -84,7 +84,7 @@ validate yourself. Any type expression works, so `into=list[Pokemon]` decodes a
 | | |
 |---|---|
 | **Two clients, one API** | `HTTPClient` (async) and `SyncHTTPClient` (sync) — identical surface, both backed by pyreqwest. |
-| **Every verb** | `get`, `post`, `put`, `patch`, `delete`, `head`, `download` (each returning a `Response`: `.data`, `.status`, `.headers`) — see [Verbs](https://rogerthomas.github.io/lothc/verbs/). |
+| **Every verb** | `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `download` (each returning a `Response`: `.data`, `.status`, `.headers`) — see [Verbs](https://rogerthomas.github.io/lothc/verbs/). |
 | **Typed params, headers & forms** | A `BaseModel`/`Struct` for query params or headers (with `None`-field omission), or a body sent urlencoded (`data=`) or as a real multipart form (`form=`). |
 | **Precise static types** | Every verb is paired `@overload`s, not a cast-laden generic — your editor knows the exact return type. |
 | **SSE & streaming** | Spec-compliant SSE — automatic reconnect with `Last-Event-ID`, server `retry:` honored, typed decode (discriminated unions included) — plus raw or NDJSON-typed `stream_get`/`stream_post` — see [SSE](https://rogerthomas.github.io/lothc/sse/) / [Streaming](https://rogerthomas.github.io/lothc/streaming/). |

{lothc-0.2.0 → lothc-0.2.2}/lothc/_client.py

@@ -167,9 +167,9 @@ type SyncAuthProvider = Callable[[], str]
 
 @dataclass(slots=True)
 class RequestInfo:
-    """The request actually sent, attached to `Response.request`/`head`'s result and to
-    `HTTPResponseError.request` — the target you asked for, not necessarily the one a final
-    response came from if redirects were followed.
+    """The request actually sent, attached to `Response.request` (every non-streaming verb's
+    result) and to `HTTPResponseError.request` — the target you asked for, not necessarily the
+    one a final response came from if redirects were followed.
     """
 
     method: str
@@ -190,7 +190,9 @@ class HTTPResponseError[E = object](Exception):
     `.error` is the body decoded: as `E` when a subclass pins it
     (`class APIError(HTTPResponseError[NotFound | Conflict]): pass`, passed as `raises=`), else
     as a JSON object (`dict`), else `None` (HTML, text, an array). When a pinned `E` didn't match,
-    `.parse_error` holds why (the decode library's own `ValueError`). `.parse_error` isn't
+    `.parse_error` holds why (the decode library's own `ValueError`, or a `ValueError` chained to
+    whatever else decoding raised, e.g. a `RecursionError` for a body nested too deep to parse).
+    `.parse_error` isn't
     carried across pickling, since pydantic's `ValidationError` can't be pickled.
     """
 
@@ -310,16 +312,14 @@ def _atomic_download_file(dest: Path) -> Generator[BufferedWriter]:
         raise
 
 
-def _complete_ndjson_lines(pending: bytearray, chunk: Buffer) -> list[bytearray]:
-    """Append `chunk` to `pending` and return the non-blank lines it completes, leaving only the
+def _take_completed_lines(pending: bytearray, chunk: Buffer) -> list[bytearray]:
+    """Append `chunk` to `pending` and return every line it completes, leaving only the
     still-unterminated tail in `pending`.
 
     Linear in the bytes received. The old `line, buffer = buffer.split(b"\\n", 1)` loop copied the
     whole remainder once per line (a 4MB chunk took ~4.7s; this takes ~15ms), and only the newly
     appended bytes are searched for a newline, since everything before the last one has already
-    been consumed; rescanning all of `pending` made one long line quadratic instead. A line that
-    is only whitespace is skipped rather than decoded, which covers the `\\r` a CRLF-terminated
-    stream leaves on its blank lines.
+    been consumed; rescanning all of `pending` made one long line quadratic instead.
     """
     start = len(pending)
     pending += chunk
@@ -328,7 +328,32 @@ def _complete_ndjson_lines(pending: bytearray, chunk: Buffer) -> list[bytearray]
         return []
     lines = pending[:end].split(b"\n")
     del pending[: end + 1]
-    return [line for line in lines if line.strip()]
+    return lines
+
+
+def _complete_ndjson_lines(pending: bytearray, chunk: Buffer) -> list[bytearray]:
+    """The non-blank NDJSON lines `chunk` completes (see `_take_completed_lines`). A line that is
+    only whitespace is skipped rather than decoded, which covers the `\\r` a CRLF-terminated
+    stream leaves on its blank lines; a JSON decoder tolerates the `\\r` ending any other line."""
+    return [line for line in _take_completed_lines(pending, chunk) if line.strip()]
+
+
+def _strip_carriage_return(line: bytearray) -> bytearray:
+    return line[:-1] if line.endswith(b"\r") else line
+
+
+def _complete_text_lines(pending: bytearray, chunk: Buffer) -> list[bytearray]:
+    """The raw text lines `chunk` completes, for `into=str` (see `_take_completed_lines`): every
+    one, blank lines included, with one trailing `\\r` (from a CRLF terminator) stripped."""
+    return [_strip_carriage_return(line) for line in _take_completed_lines(pending, chunk)]
+
+
+def _final_line(pending: bytearray, *, raw_text: bool) -> bytearray | None:
+    """The unterminated tail left in `pending` when a line stream ends, if it holds a line: any
+    bytes at all for `into=str` (CR-stripped like the others), else only a non-blank one."""
+    if raw_text:
+        return _strip_carriage_return(pending) if pending else None
+    return pending if pending.strip() else None
 
 
 def _idle_timeout_error(idle: float) -> HTTPTimeoutError:
@@ -1100,8 +1125,22 @@ class _TextDecoder:
         return data if isinstance(data, str) else str(data, "utf-8")
 
 
+@dataclass(slots=True)
+class _SSEBytesDecoder:
+    """`sse(into=bytes)`: an event's `data`, which arrives as text, back as its UTF-8 bytes.
+    Only `sse()` uses it; everywhere else `bytes` is no decoder at all (`None`)."""
+
+    def decode(self, data: _JSONInput) -> bytes:
+        return data.encode() if isinstance(data, str) else bytes(data)
+
+
 type _Decoder = (
-    Decoder[Any] | TypeAdapter[Any] | _JSONObjectDecoder | _DictSubclassDecoder | _TextDecoder
+    Decoder[Any]
+    | TypeAdapter[Any]
+    | _JSONObjectDecoder
+    | _DictSubclassDecoder
+    | _TextDecoder
+    | _SSEBytesDecoder
 )
 type _Into = TypeForm[Any] | TypeAdapterTyping[Any] | DecoderTyping[Any] | None
 
@@ -1237,6 +1276,53 @@ def _is_bare_dict_subclass(form: object) -> TypeIs[type[dict[Any, Any]]]:
     return _is_class(form) and not is_typeddict(form) and issubclass(form, dict)
 
 
+def _is_json_object_form(form: object) -> bool:
+    """Whether `form` means "any JSON object", which stdlib `json` decodes with no extra: `dict`,
+    `dict[str, Any]` however it's spelled (`typing.Dict[str, Any]`, bare `typing.Dict`), and
+    `Mapping[str, Any]`, since the `dict` it gets is one.
+
+    >>> from typing import Dict
+    >>> [_is_json_object_form(f) for f in (dict, Dict[str, Any], Mapping[str, Any], dict[str, int])]
+    [True, True, True, False]
+    """
+    if form is dict:
+        return True
+    # `in` a tuple, not a set: an argument can be unhashable (`Annotated` with a `dict` in it).
+    return get_origin(form) in {dict, Mapping} and get_args(form) in ((), (str, Any))
+
+
+def _is_tuple(value: object) -> TypeIs[tuple[object, ...]]:
+    # A `TypeIs`, not an inline `isinstance`: that narrows to a partially unknown tuple.
+    return isinstance(value, tuple)
+
+
+def _has_msgspec_custom_type(form: object) -> bool:
+    """Whether msgspec reads some part of `form` as a "custom type" (`Path`, `deque[int]`,
+    `IPv4Address`, a parametrized `dict` subclass such as `OrderedDict[str, int]`): one it only
+    decodes through a `dec_hook`, which lothc doesn't pass, so its `Decoder` builds fine and then
+    rejects every body. Walks `msgspec.inspect.type_info`'s tree, a recursive one ending at the
+    first node seen twice. `object` is a custom type to `type_info` but decodes as `Any`."""
+    try:
+        root = msgspec.inspect.type_info(form)
+    except TypeError:
+        # Not a type msgspec knows at all: its `Decoder` reports that itself.
+        return False
+    seen: set[int] = set()
+    pending: list[object] = [root]
+    while pending:
+        node = pending.pop()
+        if _is_tuple(node):
+            pending.extend(node)
+            continue
+        if not isinstance(node, (msgspec.inspect.Type, msgspec.inspect.Field)) or id(node) in seen:
+            continue
+        if isinstance(node, msgspec.inspect.CustomType) and node.cls is not object:
+            return True
+        seen.add(id(node))
+        pending.extend(getattr(node, name) for name in node.__struct_fields__)
+    return False
+
+
 def _msgspec_decoder(form: object) -> Decoder[Any]:
     try:
         return Decoder(form)
@@ -1253,12 +1339,13 @@ def _pydantic_adapter(form: object) -> TypeAdapter[Any]:
 
 
 def _build_decoder(form: object, model_bases: set[type]) -> _Decoder:
-    """The decoder for a type expression: raw text for `str`, stdlib `json` for `dict` and its
-    bare subclasses, else whichever library the form's models (or pydantic-only metadata) belong
-    to, else msgspec (faster), else pydantic."""
+    """The decoder for a type expression: raw text for `str`, stdlib `json` for a JSON object
+    (`dict`, `dict[str, Any]`, `Mapping[str, Any]`) and bare `dict` subclasses, else whichever
+    library the form's models (or pydantic-only metadata) belong to, else msgspec (faster) unless
+    it can't decode part of the form, else pydantic."""
     if form is str:
         return _TextDecoder()
-    if form is dict or form == dict[str, Any]:
+    if _is_json_object_form(form):
         return _JSONObjectDecoder()
     if _is_bare_dict_subclass(form):
         return _DictSubclassDecoder(form)
@@ -1276,14 +1363,22 @@ def _build_decoder(form: object, model_bases: set[type]) -> _Decoder:
                 " msgspec would silently skip: install lothc[pydantic]."
             )
         return _pydantic_adapter(form)
-    if msgspec_installed:
+    # A Struct form stays with msgspec whatever its fields are: pydantic can't build a Struct.
+    if msgspec_installed and (Struct in model_bases or not _has_msgspec_custom_type(form)):
         return _msgspec_decoder(form)
+    if msgspec_installed and not pydantic_installed:
+        raise TypeError(
+            f"into={form!r} contains a type msgspec can't decode from JSON (e.g. Path, deque,"
+            " IPv4Address, or a parametrized dict subclass such as OrderedDict[str, int]), so"
+            " every response would fail to decode: install lothc[pydantic], which can. A bare"
+            " dict subclass (into=OrderedDict) needs neither extra."
+        )
     if pydantic_installed:
         return _pydantic_adapter(form)
     raise TypeError(
         f"into={form!r} needs msgspec or pydantic to decode it: install lothc[msgspec] or"
-        " lothc[pydantic]. Only bytes, str, dict (and its subclasses) and dict[str, Any] work"
-        " without either."
+        " lothc[pydantic]. Only bytes, str, dict (and its bare subclasses), dict[str, Any] and"
+        " Mapping[str, Any] work without either."
     )
 
 
@@ -1344,11 +1439,18 @@ def _decode_json_line(data: _JSONInput, decoder: _Decoder) -> Any:  # noqa: ANN4
     return decoder.decode(data)
 
 
+def _sse_data_decoder(into: _Into) -> _Decoder:
+    """The decoder for each SSE event's `data`, resolved once per stream. Never `None`, unlike
+    `_decoder_for`'s: `data` arrives as text, so the default (`into=None`) keeps it as text and
+    `into=bytes` encodes it back."""
+    if into is bytes:
+        return _SSEBytesDecoder()
+    decoder = _decoder_for(into)
+    return _TextDecoder() if decoder is None else decoder
+
+
 def _dispatch_sse_record(
-    record: bytes,
-    state: _SSEStreamState,
-    into: _Into,
-    decoder: _Decoder | None,
+    record: bytes, state: _SSEStreamState, decoder: _Decoder
 ) -> SSEEvent[Any] | None:
     """Apply one record's `retry:`/`id:` fields to `state`, then build its event (if it has data).
 
@@ -1364,12 +1466,7 @@ def _dispatch_sse_record(
         state.last_event_id = parsed_record.id
     if parsed_record.data is None:
         return None
-    if decoder is not None:
-        data = _decode_json_line(parsed_record.data, decoder)
-    elif into is bytes:
-        data = parsed_record.data.encode()
-    else:
-        data = parsed_record.data
+    data = _decode_json_line(parsed_record.data, decoder)
     return SSEEvent(id=state.last_event_id, event=parsed_record.event, data=data)
 
 
@@ -2269,7 +2366,7 @@ def _parse_typed_headers(
 
 @dataclass
 class Response[TData, THeaders: TypedHeaders | None = None]:
-    """What `get`/`post`/`put`/`patch`/`delete`/`head`/`download` return: the decoded body
+    """What `get`/`post`/`put`/`patch`/`delete`/`head`/`options`/`download` return: the decoded body
     (`.data`) alongside the status and headers.
 
     `.typed_headers` is `None` unless `response_headers_type` was passed to the call that
@@ -2297,12 +2394,6 @@ class _ErrorBodyDecoding:
     decoder: _Decoder | None
 
 
-# One per `raises=` class, shared by both clients, like `_decoders` (which caches the decoder
-# itself): what this saves is the walk through the class's bases on every error. Unbounded,
-# since the classes come from source code, not data.
-_error_body_decodings: dict[type, _ErrorBodyDecoding] = {}
-
-
 def _is_response_error_class(value: object) -> TypeIs[type[HTTPResponseError[Any]]]:
     return isinstance(value, type) and issubclass(value, HTTPResponseError)
 
@@ -2366,7 +2457,15 @@ def _pinned_error_form(cls: type, bindings: Mapping[TypeVar, object]) -> tuple[(
     return ()
 
 
-def _resolve_error_body_decoding(raises: object) -> _ErrorBodyDecoding:
+# One per `raises=` class, shared by both clients, like `_decoders` (which caches the decoder
+# itself): what this saves is the walk through the class's bases on every error. Unbounded, since
+# the classes come from source code, not data. `cache` stores nothing when the call raises, so an
+# unusable `raises` (not an `HTTPResponseError` subclass, an unbound `E`, an `E` no library can
+# decode) is a `TypeError` on every call: a caller bug, never cached and never swallowed.
+@cache
+def _error_body_decoding(raises: object) -> _ErrorBodyDecoding:
+    """`raises`'s resolved `E` and its decoder. Takes `object`, since nothing has checked yet
+    that `raises` really is an `HTTPResponseError` subclass."""
     if not _is_response_error_class(raises):
         raise TypeError(
             f"raises= must be HTTPResponseError or a subclass of it, got {raises!r}. To decode"
@@ -2385,16 +2484,6 @@ def _resolve_error_body_decoding(raises: object) -> _ErrorBodyDecoding:
     return _ErrorBodyDecoding(pinned=True, decoder=_decoder_for(form))
 
 
-def _error_body_decoding(raises: type[HTTPResponseError[Any]]) -> _ErrorBodyDecoding:
-    """`raises`'s resolved `E` and its decoder, cached per class. An unusable `raises` (not an
-    `HTTPResponseError` subclass, an unbound `E`, an `E` no library can decode) raises
-    `TypeError`: a caller bug, so it's never cached and never swallowed."""
-    decoding = _error_body_decodings.get(raises)
-    if decoding is None:
-        decoding = _error_body_decodings[raises] = _resolve_error_body_decoding(raises)
-    return decoding
-
-
 def _validate_raises(raises: type[HTTPResponseError[Any]] | None) -> None:
     """Resolve a per-call `raises=` before anything is sent, so a bad class is a `TypeError` on
     every call rather than one that only surfaces on a real 4xx/5xx, in place of that error.
@@ -2404,10 +2493,11 @@ def _validate_raises(raises: type[HTTPResponseError[Any]] | None) -> None:
 
 
 def _json_object_or_none(body: bytes) -> dict[str, Any] | None:
-    """`body` as a JSON object, or `None` if it isn't one (HTML, text, an array, `null`)."""
+    """`body` as a JSON object, or `None` if it isn't one (HTML, text, an array, `null`, or
+    nested too deep to parse)."""
     try:
         return _JSONObjectDecoder().decode(body)
-    except ValueError:
+    except (ValueError, RecursionError):  # `RecursionError`: nested too deep for stdlib `json`
         return None
 
 
@@ -2416,6 +2506,18 @@ def _decode_pinned_error(body: bytes, decoder: _Decoder | None) -> Any:  # noqa:
     return body if decoder is None else _decode_json_line(body, decoder)
 
 
+def _as_parse_error(error: Exception) -> ValueError:
+    """`error` as the `ValueError` `.parse_error` promises: itself if it already is one (every
+    decode library's own failure), else a `ValueError` chained to it (`__cause__`), for the
+    `RecursionError` a deeply nested body raises and the `TypeError` a pinned `dict` subclass's
+    own constructor can raise."""
+    if isinstance(error, ValueError):
+        return error
+    parse_error = ValueError(f"error body could not be decoded: {error!r}")
+    parse_error.__cause__ = error
+    return parse_error
+
+
 def _status_error(
     raises: type[HTTPResponseError[Any]],
     status: int,
@@ -2429,21 +2531,26 @@ def _status_error(
     own contract: a body that doesn't match the pinned `E` (a proxy's HTML 502, an error shape
     the union doesn't cover) keeps the decode library's `ValueError` on `.parse_error` and falls
     back to a JSON object, else `None`, rather than replacing the status error with a
-    `ValidationError`. Nothing pinned: a JSON object, else `None`.
+    `ValidationError`. A body too deeply nested to parse, or one a pinned `dict` subclass's
+    constructor rejects, is treated the same, its error wrapped in a `ValueError`. Nothing pinned:
+    a JSON object, else `None`.
     """
     decoding = _error_body_decoding(raises)
     if not decoding.pinned:
         return raises(status, body, request_info, _json_object_or_none(body), headers=headers)
     try:
         error = _decode_pinned_error(body, decoding.decoder)
-    except ValueError as parse_error:
+    # An unusable `E` was already rejected when `raises` was resolved, so anything decoding
+    # raises here is the body's fault: too deeply nested (`RecursionError`), or refused by a
+    # pinned `dict` subclass's own constructor (`TypeError`).
+    except (ValueError, RecursionError, TypeError) as decode_error:
         return raises(
             status,
             body,
             request_info,
             _json_object_or_none(body),
             headers=headers,
-            parse_error=parse_error,
+            parse_error=_as_parse_error(decode_error),
         )
     return raises(status, body, request_info, error, headers=headers)
 
@@ -2454,7 +2561,13 @@ class HTTPClient:
     See `SyncHTTPClient` for the sync mirror — same methods, same overload shapes.
     """
 
-    _default_retry_methods: ClassVar[frozenset[str]] = frozenset({"GET", "PUT", "DELETE", "HEAD"})
+    _default_retry_methods: ClassVar[frozenset[str]] = frozenset({
+        "GET",
+        "PUT",
+        "DELETE",
+        "HEAD",
+        "OPTIONS",
+    })
     # The streaming verbs (`sse`, `stream_get`, `stream_post`, `download`) swap the client's total
     # `timeout` for this per-request one whenever the caller doesn't pass their own: pyreqwest has
     # no "no timeout" override, and a total timeout on a long-lived body kills every healthy
@@ -2522,12 +2635,13 @@ class HTTPClient:
         `bearer_token` is a static token; `bearer_auth` is an async callable resolved fresh on
         every request; `basic_auth` is a `(username, password)` pair — provide at most one of the
         three. `max_retries` enables a real retry middleware (backoff, `Retry-After`-aware); with
-        no `retry_methods`, only the idempotent verbs (`GET`/`PUT`/`DELETE`/`HEAD`) retry, and
-        `backoff_base` scales the wait between attempts (`backoff_base * 2 ** attempt`, so the
-        0.1 default waits 0.1s then 0.2s) — a `Retry-After` header on the response wins over the
-        computed delay, up to `max_retry_after` (60s by default): a server asking for a longer wait
-        ends retrying, and its 429/503 is raised as `HTTPResponseError` so you can schedule a retry
-        from `e.headers["Retry-After"]`. Pass `max_retry_after=None` to honour any wait.
+        no `retry_methods`, only the idempotent verbs (`GET`/`PUT`/`DELETE`/`HEAD`/`OPTIONS`)
+        retry, and `backoff_base` scales the wait between attempts (`backoff_base * 2 **
+        attempt`, so the 0.1 default waits 0.1s then 0.2s) — a `Retry-After` header on the
+        response wins over the computed delay, up to `max_retry_after` (60s by default): a server
+        asking for a longer wait ends retrying, and its 429/503 is raised as `HTTPResponseError`
+        so you can schedule a retry from `e.headers["Retry-After"]`. Pass `max_retry_after=None`
+        to honour any wait.
 
         `connect_timeout` bounds only the TCP connect phase (separate from `timeout`, which
         covers the whole request); `read_timeout` bounds the idle gap between two consecutive
@@ -3662,8 +3776,7 @@ class HTTPClient:
         self,
         request_builder: RequestBuilder,
         state: _SSEStreamState,
-        into: _Into,
-        decoder: _Decoder | None,
+        decoder: _Decoder,
         *,
         error_for_status: bool,
         raises: type[HTTPResponseError[Any]] | None,
@@ -3700,7 +3813,7 @@ class HTTPClient:
                     records, tail = _split_sse_records(bytes(buffer))
                     buffer = bytearray(tail)
                     for record in records:
-                        event = _dispatch_sse_record(record, state, into, decoder)
+                        event = _dispatch_sse_record(record, state, decoder)
                         if event is not None:
                             yield event
         except (PyreqwestRequestError, PyreqwestBuilderError) as error:
@@ -3723,7 +3836,7 @@ class HTTPClient:
     ) -> AsyncGenerator[SSEEvent[Any]]:
         _validate_raises(raises)
         # Resolved once per stream, not per event or per reconnect.
-        decoder = _decoder_for(into)
+        decoder = _sse_data_decoder(into)
         state = _SSEStreamState(retry_delay=reconnect_delay)
         consecutive_reconnects = 0
         effective_timeout = timeout if timeout is not None else self._streaming_default_timeout
@@ -3737,7 +3850,6 @@ class HTTPClient:
             connection = self._sse_connection(
                 request_builder,
                 state,
-                into,
                 decoder,
                 error_for_status=error_for_status,
                 raises=raises,
@@ -3932,15 +4044,18 @@ class HTTPClient:
                         if chunk is None:
                             return
                         yield bytes(chunk)
+                raw_text = isinstance(decoder, _TextDecoder)
+                complete_lines = _complete_text_lines if raw_text else _complete_ndjson_lines
                 pending = bytearray()
                 while True:
                     chunk = await _read_chunk_within(raw_response, idle)
                     if chunk is None:
                         break
-                    for line in _complete_ndjson_lines(pending, chunk):
+                    for line in complete_lines(pending, chunk):
                         yield _decode_json_line(line, decoder)
-                if pending.strip():
-                    yield _decode_json_line(pending, decoder)
+                final_line = _final_line(pending, raw_text=raw_text)
+                if final_line is not None:
+                    yield _decode_json_line(final_line, decoder)
         except (PyreqwestRequestError, PyreqwestBuilderError) as error:
             raise _translate_transport_error(error) from error
 
@@ -4342,6 +4457,76 @@ class HTTPClient:
             elapsed,
         )
 
+    @overload
+    async def options(
+        self,
+        path: str,
+        *,
+        params: Params | None = None,
+        headers: Headers | None = None,
+        timeout: float | None = None,
+        skip_auth: bool = False,
+        error_for_status: bool = True,
+        raises: type[HTTPResponseError[Any]] | None = None,
+    ) -> Response[None]: ...
+    @overload
+    async def options[THeaders: TypedHeaders](
+        self,
+        path: str,
+        *,
+        params: Params | None = None,
+        headers: Headers | None = None,
+        timeout: float | None = None,
+        skip_auth: bool = False,
+        response_headers_type: type[THeaders],
+        error_for_status: bool = True,
+        raises: type[HTTPResponseError[Any]] | None = None,
+    ) -> Response[None, THeaders]: ...
+    async def options(
+        self,
+        path: str,
+        *,
+        params: Params | None = None,
+        headers: Headers | None = None,
+        timeout: float | None = None,
+        skip_auth: bool = False,
+        response_headers_type: type[TypedHeaders] | None = None,
+        error_for_status: bool = True,
+        raises: type[HTTPResponseError[Any]] | None = None,
+    ) -> Response[None, Any]:
+        """OPTIONS `path` (e.g. a CORS preflight) — status and headers only, any body is discarded.
+        Pass `response_headers_type` to get the response headers parsed into `.typed_headers`.
+
+        `timeout` overrides the client's own for this call only; `skip_auth` omits the
+        `Authorization` header (and skips invoking `bearer_auth`) for this call; `raises` overrides
+        the client's own `raises` (the `HTTPResponseError` subclass a 4xx/5xx is raised as) for
+        this call.
+        """
+        _validate_raises(raises)
+        request_builder = await self._prepare_request(
+            self._client.request("OPTIONS", path), params, headers, timeout, skip_auth=skip_auth
+        )
+        started = time.monotonic()
+        raw_response, request_info = await _send(request_builder)
+        elapsed = time.monotonic() - started
+        if error_for_status:
+            await self._check_status(raw_response, raises, request_info)
+        response_headers = _LazyHeaders(raw_response.headers)
+        typed_headers = (
+            None
+            if response_headers_type is None
+            else _parse_typed_headers(response_headers, response_headers_type)
+        )
+        return Response(
+            None,
+            raw_response.status,
+            response_headers,
+            typed_headers,
+            request_info,
+            raw_response.version,
+            elapsed,
+        )
+
 
 class SyncHTTPClient:
     """Sync typed HTTP client: `with SyncHTTPClient(base_url=...) as client:`.
@@ -4349,7 +4534,13 @@ class SyncHTTPClient:
     See `HTTPClient` for the async mirror — same methods, same overload shapes.
     """
 
-    _default_retry_methods: ClassVar[frozenset[str]] = frozenset({"GET", "PUT", "DELETE", "HEAD"})
+    _default_retry_methods: ClassVar[frozenset[str]] = frozenset({
+        "GET",
+        "PUT",
+        "DELETE",
+        "HEAD",
+        "OPTIONS",
+    })
     # The streaming verbs (`sse`, `stream_get`, `stream_post`, `download`) swap the client's total
     # `timeout` for this per-request one whenever the caller doesn't pass their own: pyreqwest has
     # no "no timeout" override, and a total timeout on a long-lived body kills every healthy
@@ -4417,12 +4608,13 @@ class SyncHTTPClient:
         `bearer_token` is a static token; `bearer_auth` is a callable resolved fresh on every
         request; `basic_auth` is a `(username, password)` pair — provide at most one of the
         three. `max_retries` enables a real retry middleware (backoff, `Retry-After`-aware); with
-        no `retry_methods`, only the idempotent verbs (`GET`/`PUT`/`DELETE`/`HEAD`) retry, and
-        `backoff_base` scales the wait between attempts (`backoff_base * 2 ** attempt`, so the
-        0.1 default waits 0.1s then 0.2s) — a `Retry-After` header on the response wins over the
-        computed delay, up to `max_retry_after` (60s by default): a server asking for a longer wait
-        ends retrying, and its 429/503 is raised as `HTTPResponseError` so you can schedule a retry
-        from `e.headers["Retry-After"]`. Pass `max_retry_after=None` to honour any wait.
+        no `retry_methods`, only the idempotent verbs (`GET`/`PUT`/`DELETE`/`HEAD`/`OPTIONS`)
+        retry, and `backoff_base` scales the wait between attempts (`backoff_base * 2 **
+        attempt`, so the 0.1 default waits 0.1s then 0.2s) — a `Retry-After` header on the
+        response wins over the computed delay, up to `max_retry_after` (60s by default): a server
+        asking for a longer wait ends retrying, and its 429/503 is raised as `HTTPResponseError`
+        so you can schedule a retry from `e.headers["Retry-After"]`. Pass `max_retry_after=None`
+        to honour any wait.
 
         `connect_timeout` bounds only the TCP connect phase (separate from `timeout`, which
         covers the whole request); `read_timeout` bounds the idle gap between two consecutive
@@ -5555,8 +5747,7 @@ class SyncHTTPClient:
         self,
         request_builder: SyncRequestBuilder,
         state: _SSEStreamState,
-        into: _Into,
-        decoder: _Decoder | None,
+        decoder: _Decoder,
         *,
         error_for_status: bool,
         raises: type[HTTPResponseError[Any]] | None,
@@ -5589,7 +5780,7 @@ class SyncHTTPClient:
                 records, tail = _split_sse_records(bytes(buffer))
                 buffer = bytearray(tail)
                 for record in records:
-                    event = _dispatch_sse_record(record, state, into, decoder)
+                    event = _dispatch_sse_record(record, state, decoder)
                     if event is not None:
                         yield event
         except (PyreqwestRequestError, PyreqwestBuilderError) as error:
@@ -5613,7 +5804,7 @@ class SyncHTTPClient:
     ) -> Generator[SSEEvent[Any]]:
         _validate_raises(raises)
         # Resolved once per stream, not per event or per reconnect.
-        decoder = _decoder_for(into)
+        decoder = _sse_data_decoder(into)
         state = _SSEStreamState(retry_delay=reconnect_delay)
         consecutive_reconnects = 0
         effective_timeout = timeout if timeout is not None else self._streaming_default_timeout
@@ -5627,7 +5818,6 @@ class SyncHTTPClient:
             connection = self._sse_connection(
                 request_builder,
                 state,
-                into,
                 decoder,
                 error_for_status=error_for_status,
                 raises=raises,
@@ -5841,12 +6031,15 @@ class SyncHTTPClient:
             if decoder is None:
                 yield from chunks
                 return
+            raw_text = isinstance(decoder, _TextDecoder)
+            complete_lines = _complete_text_lines if raw_text else _complete_ndjson_lines
             pending = bytearray()
             for chunk in chunks:
-                for line in _complete_ndjson_lines(pending, chunk):
+                for line in complete_lines(pending, chunk):
                     yield _decode_json_line(line, decoder)
-            if pending.strip():
-                yield _decode_json_line(pending, decoder)
+            final_line = _final_line(pending, raw_text=raw_text)
+            if final_line is not None:
+                yield _decode_json_line(final_line, decoder)
         except (PyreqwestRequestError, PyreqwestBuilderError) as error:
             raise _translate_transport_error(error) from error
 
@@ -6281,3 +6474,73 @@ class SyncHTTPClient:
             raw_response.version,
             elapsed,
         )
+
+    @overload
+    def options(
+        self,
+        path: str,
+        *,
+        params: Params | None = None,
+        headers: Headers | None = None,
+        timeout: float | None = None,
+        skip_auth: bool = False,
+        error_for_status: bool = True,
+        raises: type[HTTPResponseError[Any]] | None = None,
+    ) -> Response[None]: ...
+    @overload
+    def options[THeaders: TypedHeaders](
+        self,
+        path: str,
+        *,
+        params: Params | None = None,
+        headers: Headers | None = None,
+        timeout: float | None = None,
+        skip_auth: bool = False,
+        response_headers_type: type[THeaders],
+        error_for_status: bool = True,
+        raises: type[HTTPResponseError[Any]] | None = None,
+    ) -> Response[None, THeaders]: ...
+    def options(
+        self,
+        path: str,
+        *,
+        params: Params | None = None,
+        headers: Headers | None = None,
+        timeout: float | None = None,
+        skip_auth: bool = False,
+        response_headers_type: type[TypedHeaders] | None = None,
+        error_for_status: bool = True,
+        raises: type[HTTPResponseError[Any]] | None = None,
+    ) -> Response[None, Any]:
+        """OPTIONS `path` (e.g. a CORS preflight) — status and headers only, any body is discarded.
+        Pass `response_headers_type` to get the response headers parsed into `.typed_headers`.
+
+        `timeout` overrides the client's own for this call only; `skip_auth` omits the
+        `Authorization` header (and skips invoking `bearer_auth`) for this call; `raises` overrides
+        the client's own `raises` (the `HTTPResponseError` subclass a 4xx/5xx is raised as) for
+        this call.
+        """
+        _validate_raises(raises)
+        request_builder = self._prepare_request(
+            self._client.request("OPTIONS", path), params, headers, timeout, skip_auth=skip_auth
+        )
+        started = time.monotonic()
+        raw_response, request_info = _send_sync(request_builder)
+        elapsed = time.monotonic() - started
+        if error_for_status:
+            self._check_status(raw_response, raises, request_info)
+        response_headers = _LazyHeaders(raw_response.headers)
+        typed_headers = (
+            None
+            if response_headers_type is None
+            else _parse_typed_headers(response_headers, response_headers_type)
+        )
+        return Response(
+            None,
+            raw_response.status,
+            response_headers,
+            typed_headers,
+            request_info,
+            raw_response.version,
+            elapsed,
+        )

{lothc-0.2.0 → lothc-0.2.2}/pyproject.toml

@@ -17,6 +17,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Typing :: Typed",
 ]
 
@@ -48,35 +49,45 @@ lothc = "lothc.testing"
 
 [dependency-groups]
 dev = [
-    "aiohttp>=3.14.3",
-    "aiosonic>=1.0.5",
     "asv>=0.6.4",
     "basedpyright>=1.38.0",
     "coverage>=7.16.0",
     "deptry>=0.25.1",
-    "httpx>=0.28.1",
-    "httpx2>=2.12.0",
     "msgspec>=0.19.0",
     "mypy>=2.3.1",
-    "niquests>=3.21.0",
     "prek>=0.4.14",
     "pydantic>=2.12.5",
     "pylint>=4.0.7",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-codspeed>=5.0.3",
-    "requests>=2.34.2",
     "rich>=15.0.0",
     "ruff>=0.15.14",
     "trustme>=1.2.1",
     "ty>=0.0.74",
-    "types-requests>=2.33.0.20260712",
     "vulture>=2.16",
     "yeetr[uvloop]>=2026.8.14.post1",
     "zuban>=0.9.1",
 ]
+# The other HTTP clients perf.py races lothc against (plus requests' stubs, since `basedpyright .`
+# type-checks perf.py). Nothing in lothc/ or tests/ imports them, so the test-only free-threaded
+# CI jobs leave this group out: niquests pulls in qh3, which has no free-threaded 3.15 wheel.
+perf = [
+    "aiohttp>=3.14.3",
+    "aiosonic>=1.0.5",
+    "httpx>=0.28.1",
+    "httpx2>=2.12.0",
+    "niquests>=3.21.0",
+    "requests>=2.34.2",
+    "types-requests>=2.33.0.20260712",
+]
 docs = ["zensical>=0.0.56"]
 
+[tool.uv]
+# perf too, so a plain `uv run` (which syncs the default groups) keeps perf.py runnable and
+# type-checkable locally; jobs that must not install it pass --no-default-groups.
+default-groups = ["dev", "perf"]
+
 [build-system]
 requires = ["hatchling", "hatch-vcs"]
 build-backend = "hatchling.build"
@@ -193,6 +204,7 @@ known-first-party = ["lothc"]
     "S105",   # hardcoded-password false positives on deliberate literal test values, e.g.
     # test_oauth.py asserting a cache file holds `"access_token": "token-1"`
     "S106",   # hardcoded-password false positives on deliberate literal test values
+    "S107",   # the same, as a default: `_oauth_server.py`'s `client_secret="client-secret"`
     "S603",   # subprocess call with a fixed, non-attacker-controlled argument list
     "S607",   # partial executable path — deliberately PATH-resolved, matching Taskfile invocations
 ]
@@ -251,8 +263,8 @@ max-attributes = 15 # `OAuthProvider`/`SyncOAuthProvider` (lothc/_oauth.py) stor
 max-locals = 29 # one real case (the streaming line-buffering generator) legitimately needs a
 # couple more than pylint's default 15 — matches this project's own mccabe complexity ceiling
 # ([tool.ruff.lint.mccabe] max-complexity = 15) in spirit, just a different metric. Bumped again,
-# 20 -> 21, after `_sse_stream`/its sync mirror gained a 21st local (the new `error_type` param,
-# threaded through for typed error bodies), then 21 -> 27 after `build`/its sync mirror gained
+# 20 -> 21, after `_sse_stream`/its sync mirror gained a 21st local (the then-new `error_type`
+# param, since replaced by `raises`, threaded through for typed error bodies), then 21 -> 27 after `build`/its sync mirror gained
 # the TLS/connection-pool config params (`connect_timeout`, `root_certificates`, `identity_pem`,
 # `min_tls_version`, `max_tls_version`, `danger_accept_invalid_certs`, `https_only`,
 # `max_connections`, `pool_idle_timeout`, `pool_max_idle_per_host`, `pool_timeout`), then