cliV1 0.0.7__py3-none-any.whl

swagger_petstore_open_api_3_1_0/core/event_streams.py

@@ -0,0 +1,225 @@
+"""The event stream's payload: a ``text/event-stream`` body not yet read, owning its connection.
+
+``EventStream`` and ``AsyncEventStream`` join ``FileResponse`` and its twin as the runtime's non-frozen
+classes, for the same reason: they own a resource with a lifecycle. Iterating one yields the typed payload
+of each event as the server dispatches it. Every path that ends the iteration releases the connection --
+exhaustion, the operation's sentinel, an exception, a ``with`` block, ``close`` -- and abandoning a partial
+iteration is the one leak, reported by ``__del__`` (a ``ResourceWarning`` naming the URL) and reaped by the
+client's own close, exactly as a file's is. A stream that is never iterated at all is reported the same way.
+
+The parser is ``_internal/sse_parser.py``; this module decides what happens to what it yields. An event
+whose ``data`` equals the sentinel ends the stream and is never surfaced. An event the declared type
+rejects raises pydantic's ``ValidationError`` -- a ``ValueError``, exactly what a buffered body's decoder
+raises -- after the close; raised, not skipped, because a silently dropped event in a token stream is data
+loss the caller cannot see. The bytes are taken as the transport delivers them, ``iter_bytes(None)``, never
+re-chunked: a fixed chunk size would hold a twenty-byte event back until enough followed it.
+
+A finalizer here only ever *reports*, never acts (ADR-0007): nothing is closed at GC time, and the
+consuming generator re-raises ``GeneratorExit`` without closing for the same reason."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import AsyncIterator, Callable, Iterator
+from typing import Generic, TypeVar
+
+from typing_extensions import Self
+
+from ._internal.redaction import redact_url
+from ._internal.sse_parser import SseParser
+from .transport import AsyncHttpResponse, HttpResponse
+
+T = TypeVar("T")
+
+
+class EventStream(Generic[T]):
+    """An event stream whose body has not been read yet; iterate it to receive the events.
+
+    ``for chunk in stream`` yields each event's decoded ``data`` and closes the connection when the server
+    ends the stream or the operation's sentinel arrives, so a loop run to the end leaks nothing::
+
+        with client.streaming.create_chat_completion(request) as chunks:
+            for chunk in chunks:
+                ...
+
+    Only a *partially* consumed iteration outside a ``with`` can leak; that case emits a ``ResourceWarning``
+    at finalization, the same way an unclosed file does, and the client's own ``close()`` is the backstop.
+    A ``break`` inside a ``with`` is the idiomatic early stop. Single-use: once closed, iterating again
+    raises rather than yielding nothing. The per-call ``timeout`` applies to each read of the body, so it
+    bounds the wait *between* events and a stalled server raises rather than hangs. Each open stream holds
+    one connection from the transport's pool until it is closed, so many left open will make later
+    requests wait on the pool."""
+
+    __slots__ = ("_closed", "_decode_data", "_parser", "_response", "_sentinel", "_url")
+
+    def __init__(self, response: HttpResponse, decode_data: Callable[[str], T], sentinel: str | None) -> None:
+        # Total by design: this runs between the head arriving and the raw client returning, so a
+        # raise here would leak the connection.
+        self._response = response
+        self._closed = False
+        # Captured here rather than read off the response inside the finalizer, which can run at
+        # interpreter shutdown; its query values masked, so an api key placed there cannot reach a warning.
+        self._url = redact_url(response.url)
+        self._decode_data = decode_data
+        self._sentinel = sentinel
+        self._parser = SseParser()
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterate the events, closing when the stream ends.
+
+        Ends -- and closes -- when the server closes the connection, or when an event's ``data`` equals
+        the operation's sentinel, which is consumed and never yielded. An exception mid-iteration closes
+        before propagating; only abandoning the iteration part-way leaves the connection held, which
+        ``__del__`` reports.
+
+        Returns:
+            Each event's decoded ``data``, in order.
+
+        Raises:
+            ValueError: If the stream is already closed; if an event's ``data`` is rejected by the
+                declared type (pydantic's ``ValidationError``); or if the wire breaks the event-stream
+                grammar."""
+        # Checked here, not in the generator: a closed stream must raise at the call, the way a closed
+        # file does -- not at the first next().
+        self._ensure_open()
+        return self._consume()
+
+    def _consume(self) -> Iterator[T]:
+        try:
+            for data in self._events():
+                if data == self._sentinel:
+                    break
+                yield self._decode_data(data)
+        except GeneratorExit:
+            # Abandoned mid-iteration: deliberately left open. Closing here would run at GC time, and a
+            # finalizer may report, never act (ADR-0007) -- __del__ warns, client.close() reaps.
+            raise
+        except BaseException:
+            self.close()
+            raise
+        self.close()
+
+    def _events(self) -> Iterator[str]:
+        # None, not a size: the transport's own delivery units, so an event is parsed the moment its
+        # bytes arrive.
+        for chunk in self._response.iter_bytes(None):
+            yield from self._parser.parse_chunk(chunk)
+
+    def close(self) -> None:
+        """Release the connection. Idempotent, and every path that ends an iteration calls it."""
+        if self._closed:
+            return
+        self._closed = True
+        self._response.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # getattr guard: __init__ may not have completed. Report only -- never act (ADR-0007).
+        if not getattr(self, "_closed", True):
+            warnings.warn(
+                f"unclosed {type(self).__name__} for {self._url} -- use `with`, iterate to the end, or call close()",
+                ResourceWarning,
+                stacklevel=2,
+                source=self,
+            )
+
+    def __repr__(self) -> str:
+        # Identify by state only -- never an event, which is the caller's data and not read yet anyway.
+        return f"{type(self).__name__}(closed={self._closed})"
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ValueError(
+                f"this {type(self).__name__} is closed -- it is single-use: the end of the stream, its "
+                "sentinel, an error and close() each close it"
+            )
+
+
+class AsyncEventStream(Generic[T]):
+    """The awaited twin of :class:`EventStream` -- same lifecycle, ``a``-prefixed verbs.
+
+    ``async with`` is the spelling to reach for: an abandoned instance defers finalization to
+    ``loop.shutdown_asyncgens()``, where the ``ResourceWarning`` still fires but later and less usefully,
+    and ``aclose`` must run on the loop that created the stream."""
+
+    __slots__ = ("_closed", "_decode_data", "_parser", "_response", "_sentinel", "_url")
+
+    def __init__(self, response: AsyncHttpResponse, decode_data: Callable[[str], T], sentinel: str | None) -> None:
+        # Total by design, and the URL captured and masked, as in the sync twin.
+        self._response = response
+        self._closed = False
+        self._url = redact_url(response.url)
+        self._decode_data = decode_data
+        self._sentinel = sentinel
+        self._parser = SseParser()
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        """Iterate the events, closing when the stream ends; the twin of :meth:`EventStream.__iter__`.
+
+        Returns:
+            Each event's decoded ``data``, in order.
+
+        Raises:
+            ValueError: If the stream is already closed; if an event's ``data`` is rejected by the
+                declared type (pydantic's ``ValidationError``); or if the wire breaks the event-stream
+                grammar."""
+        self._ensure_open()
+        return self._consume()
+
+    async def _consume(self) -> AsyncIterator[T]:
+        try:
+            async for data in self._events():
+                if data == self._sentinel:
+                    break
+                yield self._decode_data(data)
+        except GeneratorExit:
+            # Abandoned mid-iteration: deliberately left open, as in the sync twin.
+            raise
+        except BaseException:
+            await self.aclose()
+            raise
+        await self.aclose()
+
+    async def _events(self) -> AsyncIterator[str]:
+        async for chunk in self._response.aiter_bytes(None):
+            for data in self._parser.parse_chunk(chunk):
+                yield data
+
+    async def aclose(self) -> None:
+        """Release the connection. Idempotent, and every path that ends an iteration awaits it."""
+        if self._closed:
+            return
+        self._closed = True
+        await self._response.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    def __del__(self) -> None:
+        # getattr guard: __init__ may not have completed. Report only -- never act (ADR-0007).
+        if not getattr(self, "_closed", True):
+            warnings.warn(
+                f"unclosed {type(self).__name__} for {self._url} -- use `async with`, iterate to the end, or "
+                "call aclose()",
+                ResourceWarning,
+                stacklevel=2,
+                source=self,
+            )
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(closed={self._closed})"
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ValueError(
+                f"this {type(self).__name__} is closed -- it is single-use: the end of the stream, its "
+                "sentinel, an error and aclose() each close it"
+            )

swagger_petstore_open_api_3_1_0/core/exceptions.py

@@ -0,0 +1,78 @@
+"""The SDK's own exception types: a failed call, and a call that never happened.
+
+The two are disjoint by construction. :class:`ApiError` means the server answered and the answer was
+an error, so it carries a decoded body. :class:`TransportError` means no answer arrived at all, so
+there is nothing to decode -- only what went wrong on the way."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+E = TypeVar("E", default=object)
+
+
+class ApiError(Exception, Generic[E]):
+    """A failed API call, raised by the parsed response mode.
+
+    ``error`` is the decoded response body -- a typed union of the operation's documented
+    error schemas, or :class:`RawError` for a status the operation does not document. That
+    payload *is* the information, so neither string form embeds it: ``str`` and ``repr``
+    identify the failure by status and error type only, which keeps response bodies out of logs
+    and tracebacks. Read ``.error`` to inspect it."""
+
+    def __init__(self, error: E, status_code: int, headers: Mapping[str, str]) -> None:
+        # Composed once: ``Exception.__str__`` returns a single argument verbatim, so
+        # ``args[0]`` and ``str(self)`` are the same string by construction.
+        super().__init__(f"HTTP {status_code}: {type(error).__name__}")
+        self.error: E = error
+        self.status_code = status_code
+        self.headers: Mapping[str, str] = headers
+        """Header names lowercased, per the transports' obligation -- look keys up in lowercase."""
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status_code={self.status_code}, error={type(self.error).__name__})"
+
+    def __reduce__(self) -> tuple[type[ApiError[E]], tuple[E, int, Mapping[str, str]], dict[str, Any]]:
+        # ``BaseException``'s default reduce replays ``args`` through ``__init__``, which takes
+        # three arguments -- so pickling and copying both fail without this. The state mapping is
+        # what carries ``__notes__`` and any subclass attribute across the round trip.
+        return (type(self), (self.error, self.status_code, self.headers), self.__dict__)
+
+
+class TransportError(Exception):
+    """A request never produced a response -- the connection failed, timed out, or was dropped.
+
+    Raised by a transport, never by the pipeline. It is the one failure shape the retry loop can act
+    on without knowing which HTTP library moved the bytes, which is what keeps that library named in
+    a single module: a loop that caught the library's own connection error would have to import that
+    library to say so.
+
+    A transport author's vocabulary, not a caller's. It is exported from ``core`` beside
+    :class:`~.transport.HttpClient`, because custom transport has to raise it for the retry loop to
+    act on a failed send -- whatever else that transport raises reaches the caller on the first
+    attempt. A caller does not catch it: when the last attempt fails, ``execute`` raises
+    :attr:`inner_exception` in this wrapper's place, ``from`` the cause that exception already
+    carried -- which restates what it held rather than clearing it, and suppresses this wrapper from
+    the chain it is printed with. So
+    it adds nothing to what it wraps. Transport passes the original exception itself rather
+    than a string of it, both as ``__cause__`` and as the single argument: ``Exception.__str__``
+    renders a lone argument through ``str``, so the message reads identically, and nothing is
+    flattened on the way through.
+    A distinction worth narrowing on, a timeout against a refused connection among them, belongs to
+    the exception the caller actually sees; the loop itself draws none, waiting the same curve for
+    both.
+
+    A response that arrived and said 4xx or 5xx is not this -- that is an :class:`ApiError`, or a
+    :class:`~.results.Failure` in the raw response mode. This type means there was no response."""
+
+    def __init__(self, inner_exception: Exception) -> None:
+        super().__init__(inner_exception)
+        self.inner_exception = inner_exception
+        """What the transport itself raised, and the only thing this type carries.
+
+        Required, so a wrapper that cannot say what failed is a build failure rather than a runtime
+        discovery. ``args`` is the same one value, which is what lets ``BaseException``'s default
+        ``__reduce__`` replay it unaided."""

swagger_petstore_open_api_3_1_0/core/file_responses.py

@@ -0,0 +1,337 @@
+"""The streamed download's payload: a response body not yet read, owning its connection.
+
+``FileResponse`` and ``AsyncFileResponse`` are the only non-frozen classes in the runtime, and
+deliberately so: everything else is an inert value, these own a resource with a lifecycle. Every
+consuming path -- ``read``, ``save_to``, a drained ``iter_bytes``, a ``with`` block, ``close`` --
+releases the connection; abandoning a partial manual iteration is the one leak, reported by
+``__del__`` (a ``ResourceWarning``, the io/socket idiom) and reaped by the client's own close.
+
+A finalizer here only ever *reports*, never acts (ADR-0007): nothing is closed at GC time, which
+is also why the consuming generator re-raises ``GeneratorExit`` without closing -- closing there
+would run at collection time and silently suppress the warning that names the mistake."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import warnings
+from collections.abc import AsyncIterator, Iterator, Mapping
+from pathlib import Path
+
+from typing_extensions import Self
+
+from ._internal.content_disposition import content_disposition_filename, safe_filename
+from ._internal.redaction import redact_url
+from .transport import AsyncHttpResponse, HttpResponse
+
+_CHUNK_SIZE = 65_536
+"""The library's own multipart chunk size, matched so a download iterates as an upload reads."""
+
+
+class FileResponse:
+    """A response body that has not been read yet.
+
+    Three ways to consume it, and all three close the connection::
+
+        client.files.download(id).save_to("out.bin")      # streams to disk
+        data = client.files.download(id).read()           # buffers, for a small file
+        with client.files.download(id) as f:              # anything else
+            for chunk in f.iter_bytes():
+                ...
+
+    Reading is what closes it, so only a *partially* consumed manual iteration outside a ``with``
+    can leak. That case emits a ``ResourceWarning`` at finalization, the same way an unclosed file
+    object does -- the mistake is made loud rather than quietly cleaned up (ADR-0007, amended).
+    The client's own ``close()`` is the backstop: it disposes the pool, and any connection still
+    held with it. Single-use: once closed, reading again raises rather than yielding nothing. One
+    consumer per response: ``read()`` after a partially-driven ``iter_bytes()`` raises the
+    underlying single-pass error. The per-call ``timeout`` applies to each read of a streamed
+    body, so a stalled download raises rather than hanging.
+
+    ``headers`` is the full response head -- ``ETag``, ``Last-Modified`` and friends cost nothing
+    to expose since the head has already arrived; ``media_type``, ``content_length`` and
+    ``filename`` are the three curated conveniences over it. ``filename`` is the server's own
+    suggestion from ``Content-Disposition`` and is sanitised before it can name a path -- see
+    :meth:`save_to`."""
+
+    __slots__ = ("_closed", "_response", "_url", "content_length", "filename", "headers", "media_type")
+
+    def __init__(self, response: HttpResponse) -> None:
+        # Total by design: this runs between the head arriving and the raw client returning, so a
+        # raise here would leak the connection. Malformed headers degrade to None, never raise.
+        self._response = response
+        self._closed = False
+        # Captured here rather than read off the response in __del__, which can run at interpreter
+        # shutdown where a property call into the transport may find its objects already torn down --
+        # and a finalizer that raises reports nothing. Rendered through ``redact_url`` with its
+        # defaults, unknown query values ``REDACTED``, because this string's only reader is the
+        # abandonment warning, and a query-placed api key would otherwise reach stderr and the logs
+        # with it.
+        self._url = redact_url(response.url)
+        self.headers: Mapping[str, str] = response.headers
+        self.media_type = self.headers.get("content-type")
+        length = self.headers.get("content-length")
+        self.content_length = int(length) if length is not None and length.isascii() and length.isdigit() else None
+        self.filename = content_disposition_filename(self.headers.get("content-disposition"))
+
+    def iter_bytes(self, chunk_size: int = _CHUNK_SIZE) -> Iterator[bytes]:
+        """Iterate the body in chunks, closing when it is exhausted.
+
+        The default is the underlying library's own 64 KiB: a 2 GiB download is 32 768 iterations
+        at this size. An exception mid-iteration closes before propagating; only abandoning the
+        iteration part-way leaves the connection held, which ``__del__`` reports.
+
+        Args:
+            chunk_size: How many bytes each chunk carries at most.
+
+        Returns:
+            The body's chunks, in order.
+
+        Raises:
+            ValueError: If ``chunk_size`` is not positive."""
+        # Checked here, not in the generator: a closed response must raise at the call, the way a
+        # closed file does -- not at the first next().
+        self._ensure_open()
+        if chunk_size <= 0:
+            raise ValueError(f"chunk_size must be a positive number of bytes -- got {chunk_size}")
+        return self._consume(chunk_size)
+
+    def _consume(self, chunk_size: int) -> Iterator[bytes]:
+        try:
+            yield from self._response.iter_bytes(chunk_size)
+        except GeneratorExit:
+            # Abandoned mid-iteration: deliberately left open. Closing here would run at GC time,
+            # and a finalizer may report, never act (ADR-0007) -- __del__ warns, client.close()
+            # reaps. The warning is the remedy's pointer, not the remedy.
+            raise
+        except BaseException:
+            self.close()
+            raise
+        self.close()
+
+    def read(self) -> bytes:
+        """Buffer the whole body and close. For a payload that fits in memory.
+
+        Returns:
+            The complete body."""
+        self._ensure_open()
+        try:
+            return self._response.read()
+        finally:
+            self.close()
+
+    def save_to(self, destination: str | Path) -> Path:
+        """Stream the body to ``destination``, closing when done.
+
+        A directory is a legal destination: the file is named by ``filename`` when the server sent
+        one -- reduced to a safe basename first, since a ``Content-Disposition`` is
+        attacker-controlled -- and ``ValueError`` is raised when it did not. Written to
+        ``<name>.part`` and moved into place with ``os.replace``, which is atomic on both
+        platforms, so an interrupted download never appears under the final name; the partial is
+        unlinked on failure. A failure to open the partial -- a missing parent directory, or
+        permissions -- propagates with the response still consumable, exactly as the no-filename
+        precondition does.
+
+        Args:
+            destination: The file path to write, or a directory to write into under the
+                server-suggested name.
+
+        Returns:
+            The path written.
+
+        Raises:
+            ValueError: If ``destination`` is a directory and the server sent no usable filename."""
+        # First: a second save_to must raise before it can touch the filesystem -- without this, a
+        # doomed call would create, truncate and unlink the .part before iter_bytes refuses.
+        self._ensure_open()
+        target = Path(destination)
+        if target.is_dir():
+            if self.filename is None:
+                raise ValueError(
+                    "the server sent no filename to save under -- pass a full file path instead of a directory"
+                )
+            target = target / safe_filename(self.filename)
+        partial = target.with_name(target.name + ".part")
+        out = partial.open("wb")  # an open failure, like the precondition above, leaves the response consumable
+        try:
+            with out:
+                for chunk in self.iter_bytes():
+                    out.write(chunk)
+            os.replace(partial, target)  # inside the try: a failed replace must also clean up
+        except BaseException:
+            self.close()  # idempotent -- iter_bytes' own error path may have closed already
+            partial.unlink(missing_ok=True)
+            raise
+        return target
+
+    def close(self) -> None:
+        """Release the connection. Idempotent, and every consuming path above calls it."""
+        if self._closed:
+            return
+        self._closed = True
+        self._response.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # getattr guard: __init__ may not have completed. Report only -- never act (ADR-0007).
+        if not getattr(self, "_closed", True):
+            warnings.warn(
+                f"unclosed {type(self).__name__} for {self._url} -- use `with`, or call read() / save_to() / close()",
+                ResourceWarning,
+                stacklevel=2,
+                source=self,
+            )
+
+    def __repr__(self) -> str:
+        # Identify by media type and length only -- never the bytes, which may be enormous and
+        # are not read yet anyway. Same rule as RawError and ApiError.
+        return f"{type(self).__name__}(media_type={self.media_type!r}, content_length={self.content_length})"
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ValueError(
+                f"this {type(self).__name__} is closed -- it is single-use: read(), save_to() and "
+                "a drained iter_bytes() each consume and close it"
+            )
+
+
+class AsyncFileResponse:
+    """The awaited twin of :class:`FileResponse` -- same lifecycle, ``a``-prefixed verbs.
+
+    ``async with`` is the spelling to reach for: an abandoned instance defers finalization to
+    ``loop.shutdown_asyncgens()``, where the ``ResourceWarning`` still fires but later and less
+    usefully, and ``aclose`` must run on the loop that created the response."""
+
+    __slots__ = ("_closed", "_response", "_url", "content_length", "filename", "headers", "media_type")
+
+    def __init__(self, response: AsyncHttpResponse) -> None:
+        # Total by design, exactly as the sync twin's: a raise here would leak the connection.
+        self._response = response
+        self._closed = False
+        # Captured here rather than read off the response in __del__, which can run at interpreter
+        # shutdown where a property call into the transport may find its objects already torn down --
+        # and a finalizer that raises reports nothing. Rendered through ``redact_url`` with its
+        # defaults, unknown query values ``REDACTED``, because this string's only reader is the
+        # abandonment warning, and a query-placed api key would otherwise reach stderr and the logs
+        # with it.
+        self._url = redact_url(response.url)
+        self.headers: Mapping[str, str] = response.headers
+        self.media_type = self.headers.get("content-type")
+        length = self.headers.get("content-length")
+        self.content_length = int(length) if length is not None and length.isascii() and length.isdigit() else None
+        self.filename = content_disposition_filename(self.headers.get("content-disposition"))
+
+    def aiter_bytes(self, chunk_size: int = _CHUNK_SIZE) -> AsyncIterator[bytes]:
+        """Iterate the body in chunks, closing when it is exhausted; see the sync twin.
+
+        Args:
+            chunk_size: How many bytes each chunk carries at most.
+
+        Returns:
+            The body's chunks, in order.
+
+        Raises:
+            ValueError: If ``chunk_size`` is not positive."""
+        self._ensure_open()
+        if chunk_size <= 0:
+            raise ValueError(f"chunk_size must be a positive number of bytes -- got {chunk_size}")
+        return self._consume(chunk_size)
+
+    async def _consume(self, chunk_size: int) -> AsyncIterator[bytes]:
+        try:
+            async for chunk in self._response.aiter_bytes(chunk_size):
+                yield chunk
+        except GeneratorExit:
+            # Abandoned mid-iteration: deliberately left open, as in the sync twin.
+            raise
+        except BaseException:
+            await self.aclose()
+            raise
+        await self.aclose()
+
+    async def aread(self) -> bytes:
+        """Buffer the whole body and close. For a payload that fits in memory.
+
+        Returns:
+            The complete body."""
+        self._ensure_open()
+        try:
+            return await self._response.aread()
+        finally:
+            await self.aclose()
+
+    async def save_to(self, destination: str | Path) -> Path:
+        """Stream the body to ``destination``, closing when done; see the sync twin.
+
+        Every filesystem touch runs in a worker thread, so a slow disk does not park the loop.
+
+        Args:
+            destination: The file path to write, or a directory to write into under the
+                server-suggested name.
+
+        Returns:
+            The path written.
+
+        Raises:
+            ValueError: If ``destination`` is a directory and the server sent no usable filename."""
+        self._ensure_open()  # first, as in the sync twin: raise before touching the filesystem
+        target = Path(destination)
+        if await asyncio.to_thread(target.is_dir):
+            if self.filename is None:
+                raise ValueError(
+                    "the server sent no filename to save under -- pass a full file path instead of a directory"
+                )
+            target = target / safe_filename(self.filename)
+        partial = target.with_name(target.name + ".part")
+        out = await asyncio.to_thread(partial.open, "wb")  # an open failure leaves the response consumable
+        try:
+            try:
+                async for chunk in self.aiter_bytes():
+                    await asyncio.to_thread(out.write, chunk)
+            finally:
+                await asyncio.to_thread(out.close)
+            await asyncio.to_thread(os.replace, partial, target)
+        except BaseException:
+            await self.aclose()  # idempotent -- aiter_bytes' own error path may have closed already
+            await asyncio.to_thread(partial.unlink, True)
+            raise
+        return target
+
+    async def aclose(self) -> None:
+        """Release the connection. Idempotent, and every consuming path above awaits it."""
+        if self._closed:
+            return
+        self._closed = True
+        await self._response.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    def __del__(self) -> None:
+        # getattr guard: __init__ may not have completed. Report only -- never act (ADR-0007).
+        if not getattr(self, "_closed", True):
+            warnings.warn(
+                f"unclosed {type(self).__name__} for {self._url} -- use `async with`, or call "
+                "aread() / save_to() / aclose()",
+                ResourceWarning,
+                stacklevel=2,
+                source=self,
+            )
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(media_type={self.media_type!r}, content_length={self.content_length})"
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ValueError(
+                f"this {type(self).__name__} is closed -- it is single-use: aread(), save_to() and "
+                "a drained aiter_bytes() each consume and close it"
+            )