[python] What TypeSpec type maps to IO[bytes] for a streaming binary body?

[l0lawrence]

Question

What TypeSpec type is supposed to map to IO[bytes] in the Python emitter?

Today there does not seem to be a way to author a spec whose generated client method takes a streaming binary body as IO[bytes]:

• A bytes body maps to Python bytes (read fully into memory), e.g.:

  @post
  op upload(
    @header contentType: "application/octet-stream",
    @body body: bytes,
  ): void;

  generates:

  def upload(self, body: bytes, **kwargs: Any) -> None: ...

• A JSON model body is the only thing that produces an IO[bytes] form, and only as the auto-generated binary overload alongside the model (Union[Model, IO[bytes]]) — never on its own.

IO[bytes] itself (BinaryType) is only ever injected by the generator (pygen/preprocess/__init__.py add_body_param_type), gated on model/dict/list bodies with a JSON (or multipart) content type:

if (
    body_parameter
    and body_parameter["type"]["type"] in ("model", "dict", "list")
    and (
        has_json_content_type(body_parameter)
        or (self.is_tsp and has_multi_part_content_type(body_parameter))
    )
    ...
):
    ...
    body_parameter["type"]["types"].append(KNOWN_TYPES["binary"])

A bytes body has type == "bytes", so it never goes down this path.

So:

1. Is there an existing TypeSpec type/pattern that is intended to emit IO[bytes] (streaming binary body) for the Python client, and we're just missing it?
2. If not, should a bytes body grow an IO[bytes] overload (e.g. Union[bytes, IO[bytes]] or a true @overload) so callers can pass a file/stream without materializing the whole payload in memory?

The common motivation is binary upload operations where reading the entire body into bytes is undesirable.

Notes

• The current JSON-only gating is long-standing (introduced with the original emitter migration, Migrate python emitter #4182), not a recent regression.

[github-actions]

🎯 Issue Triage

The Python emitter does not generate IO[bytes] overloads for operations whose body type is bytes, limiting callers to in-memory payloads and preventing streaming uploads. This is a feature request to extend the existing overload-injection logic in pygen/preprocess/__init__.py to cover bytes bodies in addition to model/dict/list bodies.

Category: Feature Request
Area: emitter:client:python

🔁 Possible related issue: #5941 — "[Python] typing for bytes in typespec" covers an overlapping concern about the bytes vs. IO type inconsistency between OpenAPI binary format and TypeSpec bytes; the two issues may be worth addressing together.

🔍 Analysis

• Affected component: packages/http-client-python/generator/pygen/preprocess/__init__.py, specifically add_body_param_type.
• Root cause: The guard condition checks body_parameter["type"]["type"] in ("model", "dict", "list"), explicitly excluding "bytes", so the KNOWN_TYPES["binary"] entry is never appended for raw binary bodies.
• Proposed fix area: Add a parallel branch (or widen the condition) to inject IO[bytes] when body_parameter["type"]["type"] == "bytes".
• Open design questions (per the issue):
  • Whether to restrict the overload to application/octet-stream content types only, or apply universally to all bytes bodies.
  • Whether true @overloads are preferred over a single Union[bytes, IO[bytes]] signature (no content-type disambiguation between the two variants).
  • Whether the serialization path (_content = body) already handles stream inputs correctly.
  • Snapshot-test and existing SDK impact.
• Related PR that introduced JSON-only gating: Migrate python emitter #4182.

📝 Suggested next steps

• Resolve the design questions (overload vs. union; scope to octet-stream or all bytes bodies) before implementation.
• Update add_body_param_type in pygen/preprocess/__init__.py to inject KNOWN_TYPES["binary"] for bytes bodies.
• Verify that the request-builder serialization path correctly handles IO[bytes] inputs.
• Add/update snapshot tests to capture the new generated signatures.
• Consider whether [Python] typing for bytes in typespec #5941 should be closed as a duplicate or tracked separately.

Generated by Agentic Triage