multipart-response 0.5.0

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

multipart-response

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

Integrations

Use the adapter for your web framework:

• Django
• FastAPI
• FastHTML
• Starlette

Django

uv add "multipart-response[django]"

Stream parts from a Django view:

from multipart_response.django import MultipartResponse, Part


def generate_report(request):
    def parts():
        yield Part(
            "<p>Generating report...</p>",
            headers={"HX-Target": "#status"},
        )
        yield Part(
            '<li><a href="/reports/42">Quarterly report</a></li>',
            headers={
                "HX-Target": "#reports",
                "HX-Swap": "beforeend",
            },
        )

    return MultipartResponse(parts())

• Part(...)
  • Body: content, content_type, and charset. HTML is the default content type.
  • Headers: headers, has_header(), get(), and setdefault().
  • Cookies: set_cookie(), set_signed_cookie(), and delete_cookie().
• MultipartResponse(...)
  • Response: status, reason, charset, and headers.
  • Multipart: subtype and boundary.

Use an async part source under ASGI:

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

    return MultipartResponse(parts())

Django 4.2 or later is required.

MultipartResponse subclasses Django's native StreamingHttpResponse.

FastAPI

uv add "multipart-response[fastapi]"

Stream multiple content types from one path operation:

import json

from fastapi import FastAPI
from multipart_response.fastapi import MultipartResponse, Part

app = FastAPI()


@app.get("/updates", response_class=MultipartResponse)
async def updates():
    yield Part("<p>Ready</p>", media_type="text/html")
    yield Part(
        json.dumps({"status": "ready"}),
        media_type="application/json",
        headers={"HX-Target": "#status"},
    )
    yield Part(chunk_stream(), media_type="video/mp4")

• Part(...)
  • Body: content and media_type.
  • Headers: headers.
  • Cookies: set_cookie() and delete_cookie().
• MultipartResponse(...)
  • Response: status_code, headers, and background.
  • Multipart: subtype and boundary.
• Routing
  • Use response_class to wrap yielded parts.
  • Return MultipartResponse(...) directly to set outer response options.

Stream HTML or JSON values directly when every part has one content type:

from multipart_response.fastapi import HTMLMultipartResponse, JSONMultipartResponse


@app.get("/html-updates", response_class=HTMLMultipartResponse)
async def html_updates():
    yield "<p>Ready</p>"
    yield "<p>Done</p>", {"HX-Target": "#status"}


@app.get("/json-updates", response_class=JSONMultipartResponse)
async def json_updates():
    yield {"status": "ready"}, {"HX-Target": "#status"}
    yield "done"

HTMLMultipartResponse renders strings as HTML. JSONMultipartResponse uses FastAPI's jsonable_encoder() and sets each part to application/json. The final part above contains the JSON string "done", including its quotes.

MultipartResponse subclasses Starlette's native StreamingResponse, which FastAPI uses for streamed responses.

FastHTML

uv add "multipart-response[fasthtml]"

Stream FastHTML components from a route:

from fasthtml.common import Div, P, fast_app
from multipart_response.fasthtml import MultipartResponse, Part

app, rt = fast_app()


@rt("/updates")
def get():
    def parts():
        yield Part(P("Ready"))
        yield Part(Div("Done"), headers={"HX-Target": "#status"})

    return MultipartResponse(parts())

• Part(...)
  • Body: FastHTML FT components, content, and media_type. HTML is the default content type.
  • Headers: headers.
  • Cookies: set_cookie() and delete_cookie().
• MultipartResponse(...)
  • Response: status_code, headers, and background.
  • Multipart: subtype and boundary.
• Routing
  • Return the response directly so FastHTML does not buffer a sync part source.

Stream components directly when every part is HTML:

from multipart_response.fasthtml import HTMLMultipartResponse


def get():
    def parts():
        yield P("Ready")
        yield Div("Done"), {"HX-Target": "#status"}

    return HTMLMultipartResponse(parts())

MultipartResponse subclasses Starlette's native StreamingResponse, which FastHTML uses for streamed responses.

Starlette

uv add "multipart-response[starlette]"

Return a Starlette response from an endpoint:

from multipart_response.starlette import MultipartResponse, Part


async def updates(request):
    part = Part("Ready", media_type="text/plain", headers={"Content-ID": "status"})
    part.headers["HX-Target"] = "#status"
    part.set_cookie("seen", "yes")

    return MultipartResponse(
        [part],
        status_code=200,
        headers={"X-Stream": "updates"},
    )

• Part(...)
  • Body: content and media_type.
  • Headers: headers.
  • Cookies: set_cookie() and delete_cookie().
• MultipartResponse(...)
  • Response: status_code, headers, and background.
  • Multipart: subtype and boundary.

Use HTMLMultipartResponse to return HTML strings without wrapping each one in Part:

from multipart_response.starlette import HTMLMultipartResponse


async def html_updates(request):
    return HTMLMultipartResponse(["<p>Ready</p>", "<p>Done</p>"])

MultipartResponse subclasses Starlette's native StreamingResponse.

Nested parts

MultipartResponse accepts Part, MultipartPart, and nested Multipart values:

from multipart_response.fastapi import Multipart, Part

alternative = Multipart(
    [
        Part("Plain text", media_type="text/plain"),
        Part("<p>HTML</p>", media_type="text/html"),
    ],
    subtype="alternative",
)

A sequence is buffered. A sync or async iterable streams.

htmx

The hx-multipart extension lets one htmx request process a streaming multipart/mixed response. As each part arrives, its body and HX-* headers can swap HTML, fire events, or run other htmx response actions.

The extension vendors fetch-multipart, which adds Response.prototype.parts() and exposes each MIME part as a streaming Fetch-style BodyPart. multipart-response writes the parts on the server; hx-multipart parses and handles them in the browser.

Set HX-Target and HX-Swap on a part to control its swap.

FastHTML loads htmx 2 by default. Pass htmx=False to fast_app(), then load htmx 4 and hx-multipart as shown in the extension install guide.

Core

The dependency-free core exports Multipart, MultipartPart, and MultipartWriter.

• Boundaries and MIME headers are validated against RFC 2046 limits.
• Body chunks are checked for boundary collisions.
• Static, streamed, and nested multipart content is supported.

License

BSD-3-Clause