Skip to content

Python SDK design for Http.File when it appears in non-multipart request body and response body (DO NOT MERGE) #3351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
msyyc wants to merge 9 commits into
base: main
Choose a base branch
from
Draft

Python SDK design for Http.File when it appears in non-multipart request body and response body (DO NOT MERGE) #3351

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fd45d36
docs: clarify Http.File request body compatibility
msyyc Feb 25, 2026
25971fd
docs: fix design doc wording, IO type, union syntax, and add overloads
msyyc Feb 25, 2026
e19f144
docs: improve design doc structure and wording
msyyc Feb 25, 2026
272eb64
docs: add concrete examples to backward compatibility section
msyyc Feb 25, 2026
ec80958
docs: add Http.File response body section
msyyc Feb 25, 2026
d1535cc
docs: update Http.File request body compatibility and overview
msyyc Feb 25, 2026
13a9ce4
revert: undo changes to docs/developer/readme.md
msyyc Feb 25, 2026
17877e8
docs: add references to TypeSpec Http.File docs and Spector tests
msyyc Feb 25, 2026
7e03176
docs: clean up title and simplify TypeSpec examples
msyyc Feb 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions docs/developer/http_file_body_compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Python SDK design for `Http.File` when it appears in non-multipart request body and response body

## Overview

TypeSpec `Http.File` is emitted differently depending on whether it appears as a non-multipart request body or a response body:

- **Request body**: emits `IO | bytes` (new pattern; Swagger `type: file` was never used in non-multipart request bodies)
- **Response body**: emits `bytes` (identical to legacy Swagger `type: file` signature)

Since `type: file` was not used in non-multipart request bodies, the request body change is purely additive. The response body remains fully backward compatible.

## Request Body

### TypeSpec Definition

```typespec
@post
op upload(@body body: Http.File): void;
```

### Generated Python SDK

```python
from typing import IO, overload

@overload
def upload(self, body: IO, **kwargs) -> None:
...

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

def upload(self, body: IO | bytes, **kwargs) -> None:
...
```

## Response Body

### TypeSpec Definition

```typespec
@get
op download(): Http.File;
```

### Generated Python SDK

```python
def download(self, **kwargs) -> bytes:
Copy link
Member

@johanste johanste Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This loses both content type and suggested file name. And it is a very dangerous operation for large amounts of data.

Copy link
Member Author

@msyyc msyyc Feb 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For

  @route("/base64")
  @scenario
  @scenarioDoc("""
    Test base64 encode for bytes body.
    Expected body:
    "dGVzdA==" (base64 encode of test, in JSON string)
    """)
  op base64(): {
    @header
    contentType: "application/json";

    @body
    @encode(BytesKnownEncoding.base64)
    value: bytes;
  };

Python SDK API will decode it with base64 like

autorest.python/packages/typespec-python/test/azure/generated/encode-bytes/encode/bytes/responsebody/aio/operations/_operations.py

Line 279 in 0c3981b

deserialized = _deserialize(bytes, response.json(), format="base64")
. But what if "content-type" is "application/json" but the response body is not encoded with base64 like this case: https://github.com/microsoft/typespec/blob/4d4afdabef3fed9b2d5f017a61e34286970bbff2/packages/http-specs/specs/type/file/main.tsp#L39-L47. Then typespec type bytes can't work and only Http.File could reprensent this scenario.

That's my understanding why we need Http.File as response body.

...
```

### Backward Compatibility

Swagger `type: file` (e.g. [`operationId: "WebApps_GetWebSiteContainerLogs"`](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/web/resource-manager/Microsoft.Web/AppService/stable/2024-11-01/WebApps.json#L2675)) responses also generated `bytes` (e.g. [`WebAppsOperations.get_web_site_container_logs(...)`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/appservice/azure-mgmt-web/azure/mgmt/web/operations/_web_apps_operations.py#L22070)). The TypeSpec `Http.File` response emits the same `bytes` return type, so existing callers are **completely unaffected**.

## References

- [TypeSpec `Http.File` documentation](https://typespec.io/docs/libraries/http/files/#using-httpfile-in-operations) — explains how `Http.File` works in operations (uploading, downloading, multipart payloads, custom file models, and when a model is effectively a `File`).
- [Spector test cases for `Http.File`](https://github.com/microsoft/typespec/blob/main/packages/http-specs/specs/type/file/main.tsp) — conformance tests covering file upload/download with specific, JSON, multiple, and default content types.

Loading