multipart-response 0.3.0

Stream one HTTP response as multiple parts. For Django, FastAPI, and Starlette.

multipart-response

Stream one HTTP response as multiple parts. For Django, FastAPI, and Starlette.

FastAPI

Install the FastAPI adapter:

uv add "multipart-response[fastapi]"

Yield parts from an endpoint:

from fastapi import FastAPI
from multipart_response.fastapi import HTMLMultipartResponse

app = FastAPI()

@app.get("/updates", response_class=HTMLMultipartResponse)
async def updates():
    yield "<p>Ready</p>"
    yield "<p>Done</p>"

Each part is sent when it is yielded:

Content-Type: multipart/mixed; boundary=multipart-...

--multipart-...
content-length: 12
content-type: text/html; charset=utf-8

<p>Ready</p>
--multipart-...
content-length: 11
content-type: text/html; charset=utf-8

<p>Done</p>
--multipart-...--

The same API is available from multipart_response.starlette.

Django

Install the Django adapter:

uv add "multipart-response[django]"

Return explicit parts from a view:

from multipart_response.django import MultipartResponse, Part


def updates(request):
    def parts():
        yield Part("<p>Ready</p>")
        yield Part("<p>Done</p>")

    return MultipartResponse(parts())

Part uses Django's content, content_type, charset, and headers conventions. HTML is the default content type, as it is for Django's HttpResponse.

Set headers on one part through its constructor or headers:

part = Part(
    "<p>Ready</p>",
    headers={"HX-Target": "#status"},
)
part.headers["HX-Swap"] = "innerHTML"

Use an async part source when Django runs under ASGI:

async def updates(request):
    async def parts():
        yield Part("<p>Ready</p>")
        yield Part("<p>Done</p>")

    return MultipartResponse(parts())

MultipartResponse subclasses Django's StreamingHttpResponse, so Django handles it like any other streaming response.

Django 4.2 or later is required. Sync iterators suit WSGI. Async iterators suit ASGI.

htmx

With the hx-multipart extension, each part is one swap. Part headers pick the target:

@app.get("/dashboard", response_class=HTMLMultipartResponse)
async def dashboard():
    yield ("<p>Ready</p>", {"HX-Target": "#status"})
    yield ("<li>New</li>", {"HX-Target": "#reports", "HX-Swap": "beforeend"})

Other part types

Use explicit parts when one response mixes content types:

from multipart_response.fastapi import JSONPart, Multipart, MultipartResponse, Part, TextPart

@app.get("/report", response_class=MultipartResponse)
async def report():
    yield TextPart("Preparing")
    yield JSONPart({"status": "ready"})
    yield Part(chunk_stream(), media_type="video/mp4")
    yield Multipart([...], subtype="alternative")

Django's Part uses content_type instead of media_type. Use JSONPart for Django's JsonResponse serialization rules.

Notes

• Return MultipartResponse([...], status_code=..., headers=...) with FastAPI or Starlette.
• Return MultipartResponse([...], status=..., reason=..., headers=...) with Django.
• The dependency-free core exports Multipart, MultipartPart, and MultipartWriter.
• Boundaries and headers are validated against RFC 2046 limits.
• Body chunks are checked for boundary collisions.

License

BSD-3-Clause