microsoft / microsoft/typespec
[python] What TypeSpec type maps to IO[bytes] for a streaming binary body?
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
## 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.:
```tsp
@post
op upload(
@header contentType: "application/octet-stream",
@body body: bytes,
): void;
```
generates:
```python
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:
```python
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, #4182), not a recent regression.
Contributor guide
Research direction
Start in pygen/preprocess/__init__.py at add_body_param_type and trace how bytes, model, dict, and list body types are emitted for the Python client. Compare the existing JSON and multipart binary handling, then determine the supported TypeSpec representation and expected generated signature for a streaming binary body; done means the behavior and its coverage are agreed and documented or implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100