capo-lambda 0.13.0__tar.gz → 0.15.0__tar.gz

{capo_lambda-0.13.0/src/capo_lambda.egg-info → capo_lambda-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: capo-lambda
-Version: 0.13.0
+Version: 0.15.0
 Summary: Python SDK for AWS Lambda.
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -19,6 +19,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: jmespath>=1.0
 Requires-Dist: zapros>=0.13.0
+Provides-Extra: anyio
+Requires-Dist: anyio>=3.0; extra == "anyio"
 Provides-Extra: sso
 Requires-Dist: capo-sso>=0.2.0; extra == "sso"
 Requires-Dist: capo-sso-oidc>=0.2.0; extra == "sso"
@@ -65,8 +67,10 @@ async def main():
 
 Some operations accept a streaming request body. Pass an async iterator of `bytes` chunks, or the whole body as `bytes`, for the streaming parameter.
 
+A plain iterator can be sent only once, so if a request fails after its body was transmitted the operation is not retried. To get retries for streamed uploads, pass a `Body` instead: it wraps a source that can be reopened, and every attempt streams a fresh copy. `Body.from_path` (sync client) and `Body.async_from_path` (async client, needs `anyio`) stream a file from disk; `Body(opener)` takes any context manager that yields a `(stream, length)` pair.
+
 ```python
-from capo_lambda import AsyncLambdaClient
+from capo_lambda import AsyncLambdaClient, Body
 
 
 async def main():
@@ -81,6 +85,11 @@ async def main():
         # Or pass the whole body as bytes
         response = await lambda_.invoke_async(invoke_args=b'Hello, World!')
         print(response)
+
+        # Or stream a file with Body: the file is reopened on every retry
+        # and Content-Length is taken from its size, so no content_length needed
+        response = await lambda_.invoke_async(invoke_args=Body.async_from_path("hello.txt"))
+        print(response)
 ```
 
 ## Waiters

{capo_lambda-0.13.0 → capo_lambda-0.15.0}/README.md

@@ -38,8 +38,10 @@ async def main():
 
 Some operations accept a streaming request body. Pass an async iterator of `bytes` chunks, or the whole body as `bytes`, for the streaming parameter.
 
+A plain iterator can be sent only once, so if a request fails after its body was transmitted the operation is not retried. To get retries for streamed uploads, pass a `Body` instead: it wraps a source that can be reopened, and every attempt streams a fresh copy. `Body.from_path` (sync client) and `Body.async_from_path` (async client, needs `anyio`) stream a file from disk; `Body(opener)` takes any context manager that yields a `(stream, length)` pair.
+
 ```python
-from capo_lambda import AsyncLambdaClient
+from capo_lambda import AsyncLambdaClient, Body
 
 
 async def main():
@@ -54,6 +56,11 @@ async def main():
         # Or pass the whole body as bytes
         response = await lambda_.invoke_async(invoke_args=b'Hello, World!')
         print(response)
+
+        # Or stream a file with Body: the file is reopened on every retry
+        # and Content-Length is taken from its size, so no content_length needed
+        response = await lambda_.invoke_async(invoke_args=Body.async_from_path("hello.txt"))
+        print(response)
 ```
 
 ## Waiters

{capo_lambda-0.13.0 → capo_lambda-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "capo-lambda"
-version = "0.13.0"
+version = "0.15.0"
 description = "Python SDK for AWS Lambda."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,8 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Async file request bodies via Body.async_from_path
+anyio = ["anyio>=3.0"]
 # IAM Identity Center (SSO), assume-role and web-identity credentials providers
 sso = [
     "capo-sso>=0.2.0",

{capo_lambda-0.13.0 → capo_lambda-0.15.0}/src/capo_lambda/__init__.py

@@ -48,6 +48,7 @@ from ._auth._providers import (
 )
 from ._auth._signers import Signer as Signer
 from ._auth._signers import SigV4Signer as SigV4Signer
+from ._body import Body as Body
 from ._services._lambda import LambdaClient as LambdaClient
 from ._services._pipeline import (
     AsyncOperationOptions as AsyncOperationOptions,

{capo_lambda-0.13.0 → capo_lambda-0.15.0}/src/capo_lambda/_auth/_signers.py

@@ -7,7 +7,7 @@ from zapros import Request
 
 from capo_lambda._auth._identity import Credentials, Identity
 from capo_lambda._auth._providers import IdentityProvider
-from capo_lambda._auth._sigv4 import SigV4AuthContext, sign_sigv4
+from capo_lambda._auth._sigv4 import S3_SIGNING_NAMES, SigV4AuthContext, sign_sigv4
 
 IdentityT = TypeVar("IdentityT", bound="Identity")
 
@@ -30,14 +30,25 @@ class SigV4Signer(Signer[Credentials]):
     The full auth scheme (``name`` variant, ``signingName``, ``signingRegion``,
     encoding/normalization flags) is provided by the caller — either from the
     endpoint rule-set's ``authSchemes`` property or built by the generated
-    ``get_signer`` from operation defaults.
+    ``get_signer`` from operation defaults. ``unsigned_payload`` mirrors the
+    operation's ``aws.auth#unsignedPayload`` trait: the body is sent but left
+    out of the signature. ``event_stream`` marks a request event stream: the
+    request is signed with the ``STREAMING-AWS4-HMAC-SHA256-EVENTS`` payload
+    marker and every event with a signature chained from it.
     """
 
     def __init__(
-        self, provider: IdentityProvider[Credentials], *, auth_scheme: dict[str, Any]
+        self,
+        provider: IdentityProvider[Credentials],
+        *,
+        auth_scheme: dict[str, Any],
+        unsigned_payload: bool = False,
+        event_stream: bool = False,
     ) -> None:
         super().__init__(provider)
         self._auth_scheme = auth_scheme
+        self._unsigned_payload = unsigned_payload
+        self._event_stream = event_stream
 
     async def asign(self, req: Request) -> Request:
         creds = await self.provider.aresolve_identity()
@@ -55,13 +66,24 @@ class SigV4Signer(Signer[Credentials]):
                 "disableNormalizePath", False
             ),
         }
-        if req.body is None:
-            body: bytes | None = b""
-        elif isinstance(req.body, bytes):
-            body = req.body
-        else:
-            body = None
-        return sign_sigv4(req, ctx, body)
+        unsigned_payload = self._unsigned_payload
+        if (
+            not unsigned_payload
+            and not self._event_stream
+            and req.body is not None
+            and not isinstance(req.body, bytes)
+        ):
+            if self._auth_scheme["signingName"] in S3_SIGNING_NAMES:
+                # S3 accepts UNSIGNED-PAYLOAD for any operation; streamed bodies rely on it.
+                unsigned_payload = True
+            else:
+                raise NotImplementedError(
+                    "Currently we don't support signed chunked payloads, so buffer the body and "
+                    "pass bytes as a workaround; chunked signed implementation coming soon"
+                )
+        return sign_sigv4(
+            req, ctx, unsigned_payload=unsigned_payload, event_stream=self._event_stream
+        )
 
     def sign(self, req: Request) -> Request:
         creds = self.provider.resolve_identity()
@@ -79,10 +101,21 @@ class SigV4Signer(Signer[Credentials]):
                 "disableNormalizePath", False
             ),
         }
-        if req.body is None:
-            body: bytes | None = b""
-        elif isinstance(req.body, bytes):
-            body = req.body
-        else:
-            body = None
-        return sign_sigv4(req, ctx, body)
+        unsigned_payload = self._unsigned_payload
+        if (
+            not unsigned_payload
+            and not self._event_stream
+            and req.body is not None
+            and not isinstance(req.body, bytes)
+        ):
+            if self._auth_scheme["signingName"] in S3_SIGNING_NAMES:
+                # S3 accepts UNSIGNED-PAYLOAD for any operation; streamed bodies rely on it.
+                unsigned_payload = True
+            else:
+                raise NotImplementedError(
+                    "Currently we don't support signed chunked payloads, so buffer the body and "
+                    "pass bytes as a workaround; chunked signed implementation coming soon"
+                )
+        return sign_sigv4(
+            req, ctx, unsigned_payload=unsigned_payload, event_stream=self._event_stream
+        )

{capo_lambda-0.13.0 → capo_lambda-0.15.0}/src/capo_lambda/_auth/_sigv4.py

@@ -1,4 +1,4 @@
-"""AWS Signature Version 4 — single-chunk signing.
+"""AWS Signature Version 4 — single-chunk and event-stream signing.
 
 Reference:
     https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
@@ -15,7 +15,8 @@ import functools
 import hashlib
 import hmac
 import re
-from typing import Any, Literal, TypedDict
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Literal, TypedDict, cast
 from urllib.parse import quote, unquote
 
 import zapros
@@ -23,6 +24,9 @@ from pywhatwgurl import URLSearchParams
 from zapros import Headers, Request
 from zapros._utils import get_host_header_value
 
+from .._iter import AnyIterator
+from .._protocol.eventstream import HeaderValue, Message, encode_headers
+
 
 def build_sigv4_auth_scheme(
     signing_name: str, region: str | None, endpoint_scheme: dict[str, Any] | None = None
@@ -65,6 +69,10 @@ class SigV4AuthContext(TypedDict):
 
 
 _SIGV4_ALGORITHM = "AWS4-HMAC-SHA256"
+# Per-event algorithm and request payload marker of a signed event stream.
+_EVENT_ALGORITHM = "AWS4-HMAC-SHA256-PAYLOAD"
+_EVENT_STREAM_PAYLOAD = "STREAMING-AWS4-HMAC-SHA256-EVENTS"
+_AMZ_DATE_FORMAT = "%Y%m%dT%H%M%SZ"
 _EMPTY_PAYLOAD_SHA256 = hashlib.sha256(b"").hexdigest()
 
 # Headers excluded from the signed-headers set. Mirrors botocore's denylist:
@@ -95,9 +103,11 @@ _UNSIGNED_HEADERS = frozenset(
 
 _MULTI_SPACE = re.compile(r" +")
 
-# Services that require the payload hash to travel in ``x-amz-content-sha256``.
-# Other services sign the hash into the canonical request without sending it.
-_S3_SIGNING_NAMES = frozenset({"s3", "s3express", "s3-outposts", "s3-object-lambda"})
+# Services that require the payload hash to travel in ``x-amz-content-sha256``
+# on every request, and that accept ``UNSIGNED-PAYLOAD`` for any operation.
+# Other services sign the hash into the canonical request without sending it,
+# and only see the header when the payload is left unsigned.
+S3_SIGNING_NAMES = frozenset({"s3", "s3express", "s3-outposts", "s3-object-lambda"})
 
 
 def _uri_encode(value: str) -> str:
@@ -231,12 +241,20 @@ def _canonical_query_from_pairs(pairs: list[tuple[str, str]]) -> str:
 def sign_sigv4(
     request: Request,
     ctx: SigV4AuthContext,
-    body: bytes | None,
+    *,
+    unsigned_payload: bool = False,
+    event_stream: bool = False,
 ) -> Request:
     """Return a new ``Request`` carrying SigV4 single-chunk auth headers.
 
-    Pass ``body=None`` to sign with ``UNSIGNED-PAYLOAD`` (streaming requests).
-    The original ``request.body`` is forwarded unchanged in that case.
+    The payload hash covers ``request.body``, which must be ``bytes`` or
+    ``None``. ``unsigned_payload`` signs ``UNSIGNED-PAYLOAD`` instead and
+    forwards any body unchanged (streaming S3 requests and operations carrying
+    ``aws.auth#unsignedPayload``). ``event_stream`` signs a request event
+    stream: the ``STREAMING-AWS4-HMAC-SHA256-EVENTS`` marker stands in for the
+    payload hash and the body — an iterator of encoded event messages — is
+    wrapped in an :class:`EventStreamIterator` that signs every event with a
+    signature chained from this request's.
     """
     service = ctx["signing_name"]
     region = ctx["signing_region"]
@@ -250,21 +268,31 @@ def sign_sigv4(
         date_stamp = amz_date[:8]
     else:
         now = _amz_now()
-        amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+        amz_date = now.strftime(_AMZ_DATE_FORMAT)
         date_stamp = now.strftime("%Y%m%d")
         headers["X-Amz-Date"] = amz_date
 
-    # Payload hash. For S3-family services, x-amz-content-sha256 is mandatory
-    # and must be set BEFORE computing the canonical request (it gets signed).
+    # Payload hash. For S3-family services, x-amz-content-sha256 is mandatory;
+    # for every service it is the only way to announce an unsigned payload or
+    # an event stream.
+    # Either way it must be set BEFORE computing the canonical request (it
+    # gets signed).
     payload_hash = headers.get("X-Amz-Content-SHA256")
     if payload_hash is None:
-        if body is None:
+        if event_stream:
+            payload_hash = _EVENT_STREAM_PAYLOAD
+        elif unsigned_payload:
             payload_hash = "UNSIGNED-PAYLOAD"
+        elif request.body is None:
+            payload_hash = _EMPTY_PAYLOAD_SHA256
+        elif isinstance(request.body, bytes):
+            payload_hash = hashlib.sha256(request.body).hexdigest()
         else:
-            payload_hash = (
-                hashlib.sha256(body).hexdigest() if body else _EMPTY_PAYLOAD_SHA256
+            raise TypeError(
+                "sign_sigv4 hashes a bytes body only; pass unsigned_payload=True "
+                "to send a streamed body without a payload hash"
             )
-    if service in _S3_SIGNING_NAMES:
+    if service in S3_SIGNING_NAMES or unsigned_payload or event_stream:
         headers["X-Amz-Content-SHA256"] = payload_hash
 
     # Session token (STS / assumed-role credentials).
@@ -308,18 +336,135 @@ def sign_sigv4(
         f"Signature={signature}"
     )
 
-    effective_body = body if body is not None else request.body
-    if effective_body is not None:
+    body = request.body
+    if event_stream:
+        if not isinstance(body, (Iterator, AsyncIterator)):
+            raise TypeError(
+                "event_stream requires an iterator of encoded events as the body"
+            )
+        body = EventStreamIterator(
+            cast("Iterator[bytes] | AsyncIterator[bytes]", body), ctx, signature
+        )
+    if body is not None:
         return Request(
             request.url,
             request.method,
             headers,
-            body=effective_body,
+            body=body,
             context=request.context,
         )
     return Request(request.url, request.method, headers, context=request.context)
 
 
+def _sign_event(
+    ctx: SigV4AuthContext, prior_signature: str, payload: bytes
+) -> tuple[bytes, str]:
+    """Wrap one encoded event in a signed outer message.
+
+    Returns ``(frame, signature)``; the hex signature seeds the next event.
+    The string to sign chains every frame to its predecessor — the first one
+    to the request's ``Authorization`` signature — so the service can verify
+    the stream incrementally::
+
+        AWS4-HMAC-SHA256-PAYLOAD
+        <date, YYYYMMDDTHHMMSSZ>
+        <credential scope>
+        <prior signature, hex>
+        <hex sha256 of the encoded ``:date`` header>
+        <hex sha256 of the payload>
+
+    The AWS SDKs (and the service) use the ``-PAYLOAD`` algorithm name; the
+    Transcribe developer guide's pseudocode omits the suffix.
+    """
+    service = ctx["signing_name"]
+    region = ctx["signing_region"]
+    now = _amz_now()
+    amz_date = now.strftime(_AMZ_DATE_FORMAT)
+    date_stamp = amz_date[:8]
+    credential_scope = f"{date_stamp}/{region}/{service}/aws4_request"
+    date_header: dict[str, HeaderValue] = {":date": now}
+    string_to_sign = "\n".join(
+        (
+            _EVENT_ALGORITHM,
+            amz_date,
+            credential_scope,
+            prior_signature,
+            hashlib.sha256(encode_headers(date_header)).hexdigest(),
+            hashlib.sha256(payload).hexdigest(),
+        )
+    )
+    signing_key = _derive_signing_key(
+        ctx["secret_access_key"], date_stamp, region, service
+    )
+    signature = hmac.new(
+        signing_key, string_to_sign.encode("utf-8"), hashlib.sha256
+    ).hexdigest()
+    frame = Message(
+        {**date_header, ":chunk-signature": bytes.fromhex(signature)}, payload
+    ).encode()
+    return frame, signature
+
+
+class EventStreamIterator(AnyIterator[bytes]):
+    """Sign a request event stream, one frame per event.
+
+    Wraps an iterator of encoded event messages (as produced by the generated
+    ``serialize_event_*`` functions). Each event becomes the payload of an
+    outer message carrying ``:date`` and ``:chunk-signature`` headers, the
+    signature chained from the previous frame's and seeded by the request's
+    ``Authorization`` signature. Once the events are exhausted, one empty
+    signed frame is yielded to mark the end of the stream.
+
+    Like :class:`~capo._body.Body`, it is both a sync and an async iterator:
+    iterate it the way the wrapped source is iterable (``next`` over a sync
+    source, ``async for`` over an async one).
+
+    Reference:
+        https://docs.aws.amazon.com/transcribe/latest/dg/streaming-setting-up.html
+    """
+
+    def __init__(
+        self,
+        events: Iterator[bytes] | AsyncIterator[bytes],
+        ctx: SigV4AuthContext,
+        seed_signature: str,
+    ) -> None:
+        self._events = events
+        self._ctx = ctx
+        self._prior_signature = seed_signature
+        self._ended = False
+
+    def _frame(self, payload: bytes) -> bytes:
+        frame, self._prior_signature = _sign_event(
+            self._ctx, self._prior_signature, payload
+        )
+        return frame
+
+    def __next__(self) -> bytes:
+        if self._ended:
+            raise StopIteration
+        if not isinstance(self._events, Iterator):
+            raise TypeError("this event stream wraps an async source; use `async for`")
+        try:
+            payload = next(cast(Iterator[bytes], self._events))
+        except StopIteration:
+            self._ended = True
+            payload = b""
+        return self._frame(payload)
+
+    async def __anext__(self) -> bytes:
+        if self._ended:
+            raise StopAsyncIteration
+        if not isinstance(self._events, AsyncIterator):
+            raise TypeError("this event stream wraps a sync source; use `for`")
+        try:
+            payload = await cast(AsyncIterator[bytes], self._events).__anext__()
+        except StopAsyncIteration:
+            self._ended = True
+            payload = b""
+        return self._frame(payload)
+
+
 def presign_sigv4(
     request: Request,
     ctx: SigV4AuthContext,
@@ -346,7 +491,7 @@ def presign_sigv4(
     service = ctx["signing_name"]
     region = ctx["signing_region"]
 
-    amz_date = sign_time.strftime("%Y%m%dT%H%M%SZ")
+    amz_date = sign_time.strftime(_AMZ_DATE_FORMAT)
     date_stamp = sign_time.strftime("%Y%m%d")
     credential_scope = f"{date_stamp}/{region}/{service}/aws4_request"
 

capo_lambda-0.15.0/src/capo_lambda/_body.py

@@ -0,0 +1,221 @@
+"""Request body abstraction for streaming operations.
+
+Hand-written, not regenerated.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Callable, Iterator
+from contextlib import (
+    AbstractAsyncContextManager,
+    AbstractContextManager,
+    asynccontextmanager,
+    contextmanager,
+)
+from typing import TYPE_CHECKING, Generic, TypeVar, Union, cast
+
+from ._iter import AnyIterator
+
+if TYPE_CHECKING:
+    import anyio
+else:
+    try:
+        import anyio
+    except ImportError:
+        anyio = None
+
+_CHUNK_SIZE = 64 * 1024
+
+TStream = TypeVar("TStream", Iterator[bytes], AsyncIterator[bytes])
+
+# The opener yields the fresh stream together with its length, or ``None`` when
+# no stream could be produced (an exhausted or non-rewindable source, or logic
+# that decides dynamically it cannot reopen). Pairing the length with each open
+# lets it change between rebuilds instead of being fixed for the whole body.
+_ContextManager = Union[
+    AbstractContextManager[Union[tuple[TStream, int], None]],
+    AbstractAsyncContextManager[Union[tuple[TStream, int], None]],
+]
+
+
+class Body(AnyIterator[bytes], Generic[TStream]):
+    """A replayable request body whose length travels with each open.
+
+    A plain ``Iterator[bytes]`` can be sent only once, so a failed request
+    cannot be retried. A ``Body`` instead holds an *opener* — a context manager
+    that opens a fresh stream over the same source — and rebuilds the stream
+    before every attempt, closing whatever was left of the previous one.
+
+    ``TStream`` is ``Iterator[bytes]`` for bodies built with :meth:`from_path`
+    and ``AsyncIterator[bytes]`` for :meth:`async_from_path`; the former use
+    ``rebuild()``/``close()``, the latter ``arebuild()``/``aclose()``.
+    ``build_request`` rebuilds before every attempt.
+
+    Each open produces ``(stream, length)`` together, so the length is not bound
+    to the whole body and may differ from one rebuild to the next. A rebuild is
+    also not guaranteed to succeed: the source may be exhausted or
+    non-rewindable, so the opener can yield ``None`` and :meth:`rebuild` then
+    returns ``None`` instead of a pair. Callers check the return value::
+
+        for attempt in range(max_attempts):
+            opened = body.rebuild()
+            if opened is None:
+                raise RuntimeError("body could not be rebuilt")
+            stream, length = opened
+            send(stream, length)
+
+    ``length`` also holds the current stream's length as an attribute (``None``
+    before the first rebuild). Iterating a ``Body`` reads its current stream.
+    """
+
+    def __init__(self, opener: Callable[[], _ContextManager[TStream]]) -> None:
+        self._opener = opener
+        self._cm: _ContextManager[TStream] | None = None
+        self._stream: TStream | None = None
+        self.length: int | None = None
+
+    @classmethod
+    def from_path(
+        cls, path: str | os.PathLike[str], chunk_size: int = _CHUNK_SIZE
+    ) -> Body[Iterator[bytes]]:
+        """A body that reads ``path`` in ``chunk_size`` chunks, reopening it (and re-measuring it) on every rebuild."""
+
+        @contextmanager
+        def open_() -> Iterator[tuple[Iterator[bytes], int]]:
+            with open(path, "rb") as file:
+                length = os.fstat(file.fileno()).st_size
+                yield iter(lambda: file.read(chunk_size), b""), length
+
+        return Body(open_)
+
+    @classmethod
+    def async_from_path(
+        cls, path: str | os.PathLike[str], chunk_size: int = _CHUNK_SIZE
+    ) -> Body[AsyncIterator[bytes]]:
+        """The async counterpart of :meth:`from_path`; needs ``anyio`` installed."""
+        if anyio is None:
+            dist = (__package__ or "capo").replace("_", "-")
+            raise RuntimeError(
+                "Body.async_from_path() requires the anyio package; "
+                f"reinstall with the anyio feature enabled: {dist}[anyio]"
+            )
+
+        @asynccontextmanager
+        async def open_() -> AsyncIterator[tuple[AsyncIterator[bytes], int]]:
+            async with await anyio.open_file(path, "rb") as file:
+                length = os.fstat(file.wrapped.fileno()).st_size
+
+                async def chunks() -> AsyncIterator[bytes]:
+                    while chunk := await file.read(chunk_size):
+                        yield chunk
+
+                yield chunks(), length
+
+        return Body(open_)
+
+    @property
+    def stream(self) -> TStream | None:
+        """The current open stream, or ``None`` if none is open (before the first
+        rebuild, or after a close).
+
+        ``build_request`` reuses a non-``None`` stream instead of rebuilding, so
+        the retry layer stays in control of when a fresh stream is created.
+        """
+        return self._stream
+
+    def rebuild(self: Body[Iterator[bytes]]) -> tuple[Iterator[bytes], int] | None:
+        """Reopen the stream, closing any previous one, and return ``(stream, length)``.
+
+        ``None`` if the source could not be reopened.
+        """
+        self.close()
+        cm = self._opener()
+        if not isinstance(cm, AbstractContextManager):
+            raise TypeError(
+                "this Body has an async opener; use it with the async client (arebuild/aclose)"
+            )
+        cm = cast(AbstractContextManager["tuple[Iterator[bytes], int] | None"], cm)
+        opened = cm.__enter__()
+        if opened is None:
+            cm.__exit__(None, None, None)
+            return None
+        stream, length = opened
+        self._stream, self.length, self._cm = stream, length, cm
+        return stream, length
+
+    async def arebuild(
+        self: Body[AsyncIterator[bytes]],
+    ) -> tuple[AsyncIterator[bytes], int] | None:
+        """Async :meth:`rebuild`, returning ``(stream, length)`` or ``None``."""
+        await self.aclose()
+        cm = self._opener()
+        if not isinstance(cm, AbstractAsyncContextManager):
+            raise TypeError(
+                "this Body has a sync opener; use it with the sync client (rebuild/close)"
+            )
+        cm = cast(
+            AbstractAsyncContextManager["tuple[AsyncIterator[bytes], int] | None"], cm
+        )
+        opened = await cm.__aenter__()
+        if opened is None:
+            await cm.__aexit__(None, None, None)
+            return None
+        stream, length = opened
+        self._stream, self.length, self._cm = stream, length, cm
+        return stream, length
+
+    def close(self: Body[Iterator[bytes]]) -> None:
+        cm, self._cm, self._stream, self.length = self._cm, None, None, None
+        if cm is not None:
+            cast(AbstractContextManager[object], cm).__exit__(None, None, None)
+
+    async def aclose(self: Body[AsyncIterator[bytes]]) -> None:
+        cm, self._cm, self._stream, self.length = self._cm, None, None, None
+        if cm is not None:
+            await cast(AbstractAsyncContextManager[object], cm).__aexit__(
+                None, None, None
+            )
+
+    def __next__(self) -> bytes:
+        if self._stream is None:
+            raise RuntimeError("body has no open stream; call rebuild() first")
+        return next(cast(Iterator[bytes], self._stream))
+
+    async def __anext__(self) -> bytes:
+        if self._stream is None:
+            raise RuntimeError("body has no open stream; call rebuild() first")
+        return await cast(AsyncIterator[bytes], self._stream).__anext__()
+
+
+@contextmanager
+def closing_bodies(inp: object) -> Iterator[None]:
+    """Close every :class:`Body` in a request input when the operation finishes.
+
+    The operation method wraps its whole run (request build across retries, plus
+    response handling) in this, so a ``Body``'s stream is released once — and only
+    once — the operation is done. Non-``Body`` values (bytes, plain iterators,
+    ``StaticAnyIterator``) are left untouched.
+    """
+    try:
+        yield
+    finally:
+        if isinstance(inp, dict):
+            for value in inp.values():
+                if isinstance(value, Body):
+                    cast("Body[Iterator[bytes]]", value).close()
+
+
+@asynccontextmanager
+async def aclosing_bodies(inp: object) -> AsyncIterator[None]:
+    """Async :func:`closing_bodies`, awaiting :meth:`Body.aclose`."""
+    try:
+        yield
+    finally:
+        if isinstance(inp, dict):
+            for value in inp.values():
+                if isinstance(value, Body):
+                    await cast("Body[AsyncIterator[bytes]]", value).aclose()
+
+
+__all__ = ["Body", "aclosing_bodies", "closing_bodies"]