cliV1 0.1.1__py3-none-any.whl

swagger_petstore_open_api_3_0/core/decoding.py

@@ -0,0 +1,263 @@
+"""Turning wire bytes into typed values: response decoding and error-body mapping.
+
+One verb per act, and they are not interchangeable. ``decode`` turns a 2xx body into its typed
+payload: it is the method a :class:`ResponseDecoder` carries, built by the ``*_decoder``
+factories for an endpoint that has not sent its request yet, and run in one step by the
+``decode_*`` helpers for a response already in hand -- ``decode_json[t](response)`` is
+``json_decoder[t].decode(response)``.
+
+``map`` is the error path's act, because there the work is **selection**: an :class:`ErrorMapper`
+picks the documented schema for a response's status, and each generated error module's ``match``
+on ``response.status_code`` is that mapping written out.
+
+The decoders below resolve their adapter through :func:`adapter_for`, the single cache the request
+path (``json_body``, ``param``) draws from too.
+
+Every factory here takes its target type in its subscript, as a ``TypeForm[T]`` (PEP 747) rather
+than a ``type[T]``. That is what keeps ``T`` precise for the type expressions no class can stand in
+for -- a union alias, an ``Annotated`` wire-format alias, a ``list[...]``/``dict[...]`` wrapper --
+and so what lets a type checker compare an endpoint's *declared* payload type against the type it
+actually parses. A ``type[T]``-plus-``object`` overload pair cannot: given a declared type the
+precise overload does not fit, inference falls through to the ``object`` one, yields ``Any``, and
+the disagreement has nowhere left to surface.
+
+Not every decoder is subscripted: :data:`empty_response` is a shared singleton for an operation
+with no 2xx body, mirroring :data:`raw_error_response` on the error side, and :data:`file_decoder`
+is one for an operation whose body is a file. None of the three has a type to name. Between them,
+every argument ``execute`` and ``stream`` need is always written out, so a payload type is never
+left to be inferred from the surrounding declaration.
+
+There are two decoder families, told apart by what they receive. A :class:`ResponseDecoder` takes a
+buffered :class:`HttpResponse` whose ``content`` is already in memory; a :class:`StreamDecoder`
+takes the still-open :class:`StreamedResponse` and hands the connection to the value it builds. So a
+streamed payload cannot be produced by the buffered protocol at all, which is why ``stream`` names
+its decoder from the second family."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, Generic, Protocol, TypeVar
+
+from pydantic import TypeAdapter
+from typing_extensions import TypeForm
+
+from .adapters import adapter_for
+from .file_responses import AsyncFileResponse, FileResponse
+from .results import RawError
+from .transport import AsyncStreamedResponse, HttpResponse, StreamedResponse
+
+T = TypeVar("T")
+T_co = TypeVar("T_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+
+
+class ResponseDecoder(Protocol[T_co]):
+    """Decodes a 2xx response into the operation's typed success payload."""
+
+    def decode(self, response: HttpResponse) -> T_co: ...
+
+
+class ErrorMapper(Protocol[E_co]):
+    """Maps a non-2xx response to the operation's typed error body -- a union of the
+    documented error schemas, or ``RawError`` for an unmapped status."""
+
+    def map(self, response: HttpResponse) -> E_co: ...
+
+
+class StreamDecoder(Protocol[T_co]):
+    """Builds a 2xx payload from a body that has not been read.
+
+    The lazy counterpart of :class:`ResponseDecoder`, and a sibling rather than a subtype: that one
+    receives a buffered :class:`HttpResponse` whose ``content`` is already in memory, this one
+    receives the open :class:`StreamedResponse` and hands the connection to the value it returns.
+
+    ``decode`` is synchronous in both flavours -- building the payload never touches the wire, and
+    the awaiting happens when a caller consumes it."""
+
+    def decode(self, streamed: StreamedResponse, url: str) -> T_co: ...
+
+
+class AsyncStreamDecoder(Protocol[T_co]):
+    """Builds a 2xx payload from an unread async body; the twin of :class:`StreamDecoder`.
+
+    A twin rather than one protocol over both streamed types, because the two are what make the
+    flavours non-interchangeable: an argument position is contravariant, so a decoder over an
+    :class:`AsyncStreamedResponse` cannot satisfy :class:`StreamDecoder`, and the sync seam can
+    never be handed the async decoder."""
+
+    def decode(self, streamed: AsyncStreamedResponse, url: str) -> T_co: ...
+
+
+@dataclass(frozen=True, slots=True)
+class JsonDecoder(Generic[T]):
+    """Decodes a JSON body (object, array or scalar) through ``adapter``."""
+
+    adapter: TypeAdapter[T]
+
+    def decode(self, response: HttpResponse) -> T:
+        return self.adapter.validate_python(response.json())
+
+
+@dataclass(frozen=True, slots=True)
+class TextDecoder(Generic[T]):
+    """Decodes a plain-text body through ``adapter``."""
+
+    adapter: TypeAdapter[T]
+
+    def decode(self, response: HttpResponse) -> T:
+        return self.adapter.validate_python(response.text(errors="strict"))
+
+
+class _JsonDecoderFactory:
+    """``json_decoder[T]`` -- build a decoder that reads a JSON body as the subscripted type.
+
+    The subscript is a ``TypeForm``, so a runtime union alias (``Person``, which is
+    ``Employee | Boss``) is as acceptable as a concrete class and ``T`` is precise for either.
+    That precision is what makes an endpoint's declared payload type checkable against what it
+    decodes. And because the factory declares no ``__call__``, the type cannot be omitted
+    (``[operator]``); its runtime ``__call__`` is checker-invisible and only guides."""
+
+    def __getitem__(self, declared: TypeForm[T]) -> ResponseDecoder[T]:
+        return JsonDecoder(adapter_for(declared))
+
+    if not TYPE_CHECKING:
+
+        def __call__(self, *args, **kwargs):
+            raise TypeError(
+                "json_decoder is not called -- subscript it with the payload type: "
+                "decoder=json_decoder[T], e.g. json_decoder[Person]"
+            )
+
+
+class _TextDecoderFactory:
+    """``text_decoder[T]`` -- build a decoder reading a plain-text body; see ``json_decoder``."""
+
+    def __getitem__(self, declared: TypeForm[T]) -> ResponseDecoder[T]:
+        return TextDecoder(adapter_for(declared))
+
+    if not TYPE_CHECKING:
+
+        def __call__(self, *args, **kwargs):
+            raise TypeError(
+                "text_decoder is not called -- subscript it with the payload type: "
+                "decoder=text_decoder[T], e.g. text_decoder[int]"
+            )
+
+
+class _DecodeJsonFactory:
+    """``decode_json[T](response)`` -- decode a JSON body as the subscripted type, now.
+
+    The result is typed as the subscripted type whatever shape it takes -- a concrete class, a
+    union such as ``Accountant | Manager``, an ``Annotated`` alias -- so a generated error mapper
+    returns its documented body union directly, with no ``cast`` standing in for what the type
+    system now carries itself."""
+
+    def __getitem__(self, declared: TypeForm[T]) -> Callable[[HttpResponse], T]:
+        return JsonDecoder(adapter_for(declared)).decode
+
+    if not TYPE_CHECKING:
+
+        def __call__(self, *args, **kwargs):
+            raise TypeError(
+                "decode_json is not called directly -- name the body type in its subscript: decode_json[T](response)"
+            )
+
+
+class _DecodeTextFactory:
+    """``decode_text[T](response)`` -- decode a plain-text body, now; see ``decode_json``.
+
+    Also callable bare -- ``decode_text(response)`` -- which is the ``str`` default the retired
+    two-member overload existed to carry: the default lives on ``__call__`` and a named type can
+    only take the subscript path, so a mismatch has nowhere to fall through to."""
+
+    def __getitem__(self, declared: TypeForm[T]) -> Callable[[HttpResponse], T]:
+        return TextDecoder(adapter_for(declared)).decode
+
+    def __call__(self, response: HttpResponse) -> str:
+        return self[str](response)
+
+
+json_decoder: Final = _JsonDecoderFactory()
+text_decoder: Final = _TextDecoderFactory()
+decode_json: Final = _DecodeJsonFactory()
+decode_text: Final = _DecodeTextFactory()
+
+
+@dataclass(frozen=True, slots=True)
+class EmptyResponse:
+    """Response decoder for an operation whose 2xx body is empty.
+
+    The success-side counterpart of :class:`RawErrorResponse`, and the reason ``decoder`` is a
+    required argument rather than an optional one: an operation that returns no content says so by
+    naming this, instead of by leaving the argument out. Presence is auditable where absence is
+    not -- a missing ``decoder=`` could be a no-content operation or a generator that dropped the
+    line, and only one of those should compile.
+
+    Naming it is also what keeps the payload type honest. ``T`` is solved from this argument, so the
+    operation can declare ``ApiResult[None, E]`` and nothing else. Were the argument omitted
+    instead, ``T`` would be solved from the declared type, and an operation that parses nothing
+    could claim any payload it liked and hand back ``None`` at runtime -- the last place a declared
+    type could go unstated, now that each factory makes its own subscript mandatory.
+
+    Not subscripted, and not a factory: there is no type to name. ``json_decoder[None]`` would still
+    parse the body and raise on an empty one, which is the opposite of what this does.
+
+    Carries nothing SDK-specific, so it lives here rather than in the generated error layer, and is
+    shared by every such operation."""
+
+    def decode(self, response: HttpResponse) -> None:
+        return None
+
+
+empty_response: Final[ResponseDecoder[None]] = EmptyResponse()
+
+
+@dataclass(frozen=True, slots=True)
+class RawErrorResponse:
+    """Error mapper for an operation that declares no error schemas.
+
+    Deliberately has **no** ``match`` on the status code: the absence is the
+    signal. Where an operation's spec documents error responses, its own mapper
+    in the generated error layer selects a schema per status; where it documents
+    none there is nothing to select, so every non-2xx response maps to the same
+    :class:`RawError` -- status plus the undecoded body, decoded on demand.
+
+    Carries nothing SDK-specific, so it lives here rather than in the generated
+    error layer, and is shared by every such operation."""
+
+    def map(self, response: HttpResponse) -> RawError:
+        return RawError(response)
+
+
+raw_error_response: Final[ErrorMapper[RawError]] = RawErrorResponse()
+
+
+@dataclass(frozen=True, slots=True)
+class FileDecoder:
+    """Stream decoder for an operation whose 2xx body is a file.
+
+    Not subscripted, and not a factory: a file bypasses the model layer, so there is no adapter to
+    name -- the same absence that leaves ``file_part`` unsubscripted on the request side.
+
+    Naming it is what keeps the payload solved from an *argument* rather than from the seam's own
+    return type, which is what lets a second streamed payload shape join ``stream`` instead of
+    forking it. ``url`` is carried in because a :class:`StreamedResponse` does not know it and the
+    payload reports it when abandoned."""
+
+    def decode(self, streamed: StreamedResponse, url: str) -> FileResponse:
+        return FileResponse(streamed, url)
+
+
+file_decoder: Final[StreamDecoder[FileResponse]] = FileDecoder()
+
+
+@dataclass(frozen=True, slots=True)
+class AsyncFileDecoder:
+    """Stream decoder for an operation whose 2xx body is a file; the twin of :class:`FileDecoder`."""
+
+    def decode(self, streamed: AsyncStreamedResponse, url: str) -> AsyncFileResponse:
+        return AsyncFileResponse(streamed, url)
+
+
+async_file_decoder: Final[AsyncStreamDecoder[AsyncFileResponse]] = AsyncFileDecoder()

swagger_petstore_open_api_3_0/core/exceptions.py

@@ -0,0 +1,41 @@
+"""The SDK's single exception type."""
+
+from __future__ import annotations
+
+from typing import Any, Generic
+
+from typing_extensions import TypeVar
+
+from .transport import HttpResponse
+
+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, response: HttpResponse) -> 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 {response.status_code}: {type(error).__name__}")
+        self.error: E = error
+        self.response: HttpResponse = response
+
+    @property
+    def status_code(self) -> int:
+        return self.response.status_code
+
+    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, HttpResponse], dict[str, Any]]:
+        # ``BaseException``'s default reduce replays ``args`` through ``__init__``, which takes
+        # two 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.response), self.__dict__)

swagger_petstore_open_api_3_0/core/file_responses.py

@@ -0,0 +1,324 @@
+"""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 .transport import AsyncStreamedResponse, StreamedResponse
+
+_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", "_stream", "_url", "content_length", "filename", "headers", "media_type")
+
+    def __init__(self, stream: StreamedResponse, url: str) -> 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._stream = stream
+        self._closed = False
+        self._url = url
+        self.headers: Mapping[str, str] = stream.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._stream.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._stream.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._stream.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", "_stream", "_url", "content_length", "filename", "headers", "media_type")
+
+    def __init__(self, stream: AsyncStreamedResponse, url: str) -> None:
+        # Total by design, exactly as the sync twin's: a raise here would leak the connection.
+        self._stream = stream
+        self._closed = False
+        self._url = url
+        self.headers: Mapping[str, str] = stream.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._stream.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._stream.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._stream.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"
+            )