The Flask Response Object

The Response object in Flask, implemented in flask.wrappers.Response, is the standard container for data sent from the server to the client. It extends the base response class from Werkzeug but adds Flask-specific features like integrated JSON support and configuration-driven cookie management.

Default Behavior and Mimetype

By default, the Response class is configured to treat content as HTML. This is defined by the default_mimetype attribute:

class Response(ResponseBase):
    default_mimetype: str | None = "text/html"

While you can instantiate this class directly, Flask typically handles response creation through the make_response method in flask.app.Flask.

Automatic Response Conversion

Flask view functions are flexible in what they can return. The make_response method (found in src/flask/app.py) converts various return types into a proper Response instance:

• Strings and Bytes: Converted into a response with the default mimetype.
• Dictionaries and Lists: Automatically passed to the JSON provider to create a JSON response.
• Iterators/Generators: Used for streaming responses.
• Tuples: Allow specifying the body, status code, and headers simultaneously.

Returning Tuples

A common pattern in Flask is returning a tuple from a view. The make_response logic supports 2-tuples and 3-tuples:

# Example from tests/test_basic.py
@app.route("/full_tuple")
def from_full_tuple():
    return (
        "Meh",
        400,
        {"X-Foo": "Testing", "Content-Type": "text/plain; charset=utf-8"},
    )

If the first element of the tuple is already a Response object, Flask will update its status code and extend its headers with the remaining tuple elements.

JSON Support

Flask provides built-in support for JSON responses. When a view returns a dict or list, or when jsonify() is called, the DefaultJSONProvider (in src/flask/json/provider.py) handles the creation of the Response object.

The provider sets the mimetype to application/json and serializes the data:

# Logic from src/flask/json/provider.py
return self._app.response_class(
    f"{self.dumps(obj, **dump_args)}\n", mimetype=self.mimetype
)

The Response class also includes a json property (inherited and enhanced) that allows test clients to easily parse response data back into Python objects.

Streaming Responses

For large datasets or long-running responses, Flask supports streaming via generators. To ensure the request context is available during the generator's execution, the stream_with_context helper is used.

# Example from src/flask/helpers.py
@app.get("/stream")
def streamed_response():
    @stream_with_context
    def generate():
        yield "Hello "
        yield request.args["name"]
        yield "!"

    return Response(generate())

Warning: Modifying the session within a streamed generator is unsafe. Because headers (including the Set-Cookie header used for sessions) are sent to the client before the generator starts yielding data, any changes made to the session during generation will not be persisted to the client.

Response Configuration

The Response object integrates with the Flask application configuration. A notable example is the max_cookie_size property, which determines the maximum allowed size for cookies.

@property
def max_cookie_size(self) -> int:
    if current_app:
        return current_app.config["MAX_COOKIE_SIZE"]

    # return Werkzeug's default when not in an app context
    return super().max_cookie_size

This property is read-only on the response instance and reflects the MAX_COOKIE_SIZE value defined in the app's configuration (defaulting to 4093 bytes if not specified). If accessed outside of an active application context, it falls back to the default behavior defined in Werkzeug.