Responses & JSON

from flask import Flask

app = Flask(__name__)

BOOKS = {
    1: {"id": 1, "title": "Dune", "author": "Frank Herbert", "year": 1965},
    2: {"id": 2, "title": "Solaris", "author": "Stanislaw Lem", "year": 1961},
}


@app.get("/")
def home():
    return "<h1>Bookshelf</h1>"                       # str -> text/html


@app.get("/books")
def list_books():
    return list(BOOKS.values())                       # list -> application/json


@app.get("/books/<int:book_id>")
def get_book(book_id):
    book = BOOKS.get(book_id)
    if book is None:
        return {"error": "book not found"}, 404       # (dict, status)
    return book                                       # dict -> application/json


@app.get("/health")
def health():
    return "", 204                                    # (str, status): no content


@app.get("/forgotten")
def forgotten():
    BOOKS.get(1)                                      # no return: a bug


client = app.test_client()
assert client.get("/").content_type.startswith("text/html")
assert client.get("/books").json[0]["title"] == "Dune"
assert client.get("/books/2").json["author"] == "Stanislaw Lem"
assert client.get("/books/99").status_code == 404
assert client.get("/health").status_code == 204
app.logger.disabled = True                            # keep the expected traceback quiet
assert client.get("/forgotten").status_code == 500

from flask import Flask

app = Flask(__name__)                                 # a fresh application, same Bookshelf data
BOOKS = {1: {"id": 1, "title": "Dune"}, 2: {"id": 2, "title": "Solaris"}}


@app.post("/books")
def create_book():
    book = {"id": max(BOOKS) + 1, "title": "Neuromancer", "author": "William Gibson", "year": 1984}
    BOOKS[book["id"]] = book
    # (body, status, headers): 201 Created plus a Location header for the new resource
    return book, 201, {"Location": f"/books/{book['id']}"}


@app.get("/legacy-tuple")
def legacy_tuple():
    # (body, headers): the second item is a dict, so it is read as headers
    return "ok", {"X-Bookshelf-Edition": "2026"}


client = app.test_client()
created = client.post("/books")
assert created.status_code == 201
assert created.headers["Location"] == "/books/3"
assert client.get("/legacy-tuple").headers["X-Bookshelf-Edition"] == "2026"

from flask import Flask, Response, make_response, request

app = Flask(__name__)


class XmlResponse(Response):
    default_mimetype = "application/xml"      # views that return a str now send XML


@app.get("/export.xml")
def export_xml():
    # an explicit Response: the body, the status and a mimetype
    return Response("<books><book id='1'>Dune</book></books>", status=200, mimetype="application/xml")


@app.get("/version")
def version():
    response = make_response({"api": "bookshelf", "version": 3})   # dict -> JSON response object
    response.headers["X-Api-Version"] = "3"                        # replace
    response.headers.add("Link", '</books>; rel="collection"')     # append
    response.status_code = 200
    return response


xml_app = Flask(__name__)
xml_app.response_class = XmlResponse


@xml_app.get("/catalogue")
def catalogue():
    return "<books/>"                         # a str, but sent as application/xml


assert app.test_client().get("/export.xml").mimetype == "application/xml"
reply = app.test_client().get("/version")
assert reply.json["version"] == 3 and reply.headers["X-Api-Version"] == "3"
assert xml_app.test_client().get("/catalogue").mimetype == "application/xml"

from datetime import timedelta
from flask import Flask, make_response, request

app = Flask(__name__)


@app.post("/preferences/theme/<name>")
def set_theme(name):
    if name not in {"light", "dark"}:
        return {"error": "unknown theme"}, 400
    response = make_response({"theme": name})
    response.set_cookie(
        "theme",
        name,
        max_age=timedelta(days=365),     # seconds or a timedelta; None = until the browser closes
        secure=True,                     # only over HTTPS
        httponly=True,                   # not readable from JavaScript
        samesite="Lax",                  # not sent on cross-site sub-requests
        path="/",
    )
    return response


@app.get("/preferences/theme")
def get_theme():
    return {"theme": request.cookies.get("theme", "light")}


@app.delete("/preferences/theme")
def reset_theme():
    response = make_response("", 204)
    response.delete_cookie("theme", path="/", secure=True, httponly=True, samesite="Lax")
    return response


client = app.test_client()
client.post("/preferences/theme/dark", base_url="https://localhost")    # HTTPS, so the cookie is sent back
cookie = client.get_cookie("theme")
assert cookie.value == "dark" and cookie.http_only and cookie.secure and cookie.same_site == "Lax"
assert client.get("/preferences/theme", base_url="https://localhost").json == {"theme": "dark"}
client.delete("/preferences/theme", base_url="https://localhost")
assert client.get_cookie("theme") is None

from urllib.parse import urlsplit
from flask import Flask, redirect, request, url_for

app = Flask(__name__)
BOOKS = {1: {"id": 1, "title": "Dune"}}


@app.get("/books/<int:book_id>")
def get_book(book_id):
    return BOOKS[book_id]


@app.get("/books/<int:book_id>/edit")
def edit_book(book_id):
    return f"edit form for {book_id}"


@app.post("/books/<int:book_id>/edit")
def save_book(book_id):
    BOOKS[book_id]["title"] = request.form["title"]
    # Post/Redirect/Get: 303 forces the browser to follow with a GET
    return redirect(url_for("get_book", book_id=book_id), code=303)


@app.get("/old-catalogue")
def old_catalogue():
    return redirect(url_for("get_book", book_id=1), code=308)    # permanent, method preserved


def is_safe_target(target: str | None) -> bool:
    """Accept only same-site paths: no scheme, no host, no protocol-relative URL."""
    if not target or "\\" in target or not target.startswith("/") or target.startswith("//"):
        return False
    parts = urlsplit(target)
    return not parts.scheme and not parts.netloc


@app.post("/login")
def login():
    # ... authenticate first, then:
    target = request.args.get("next")
    return redirect(target if is_safe_target(target) else url_for("get_book", book_id=1), code=303)


client = app.test_client()
saved = client.post("/books/1/edit", data={"title": "Dune Messiah"})
assert saved.status_code == 303 and saved.headers["Location"] == "/books/1"
assert BOOKS[1]["title"] == "Dune Messiah"
assert client.get("/old-catalogue").status_code == 308
assert client.post("/login?next=/books/1/edit").headers["Location"] == "/books/1/edit"
assert client.post("/login?next=https://evil.example/").headers["Location"] == "/books/1"
assert client.post("/login?next=//evil.example/").headers["Location"] == "/books/1"
followed = client.post("/books/1/edit", data={"title": "Dune"}, follow_redirects=True)
assert followed.json["title"] == "Dune" and followed.history[0].status_code == 303

from flask import Flask, abort, jsonify, make_response, request

app = Flask(__name__)
BOOKS = {1: {"id": 1, "title": "Dune", "author": "Frank Herbert"}}


@app.get("/books/<int:book_id>")
def get_book(book_id):
    book = BOOKS.get(book_id)
    if book is None:
        abort(404, description=f"No book with id {book_id}")    # stops here
    return book


@app.post("/books")
def add_book():
    data = request.get_json()
    if any(b["title"] == data.get("title") for b in BOOKS.values()):
        abort(409, description="A book with this title already exists")
    BOOKS[len(BOOKS) + 1] = {"id": len(BOOKS) + 1, **data}
    return data, 201


@app.get("/secret-shelf")
def secret_shelf():
    # abort() also accepts a ready-made response, which is used as it is
    abort(make_response(jsonify({"error": "authentication required"}), 401))


@app.errorhandler(404)
@app.errorhandler(409)
def json_error(error):
    # a JSON body instead of the default HTML page (error handlers: see the Error Handling page of this section)
    return {"error": error.name, "message": error.description}, error.code


client = app.test_client()
missing = client.get("/books/7")
assert missing.status_code == 404 and missing.json["message"] == "No book with id 7"
assert client.post("/books", json={"title": "Dune"}).status_code == 409
assert client.get("/secret-shelf").status_code == 401

from flask import Flask, jsonify

app = Flask(__name__)


@app.get("/a")
def a():
    return {"title": "Dune", "year": 1965}              # dict: implicit jsonify


@app.get("/b")
def b():
    return jsonify(title="Dune", year=1965)             # keyword arguments: an object


@app.get("/c")
def c():
    return jsonify("Dune", "Solaris")                   # several positional values: an array


@app.get("/d")
def d():
    response = jsonify({"title": "Dune"})
    response.status_code = 201                          # a Response object, so it can be shaped
    response.headers["Location"] = "/books/1"
    return response


client = app.test_client()
assert client.get("/a").json == client.get("/b").json == {"title": "Dune", "year": 1965}
assert client.get("/c").json == ["Dune", "Solaris"]
assert client.get("/d").status_code == 201
assert client.get("/a").content_type == "application/json"

from datetime import date
from decimal import Decimal
from uuid import UUID
from flask import Flask

app = Flask(__name__)


@app.get("/offer")
def offer():
    return {"title": "Zażółć", "price": Decimal("9.90"), "published": date(2026, 10, 7), "sku": UUID(int=1)}


client = app.test_client()
body = client.get("/offer").get_data(as_text=True)
print(body)
app.json.sort_keys = False                  # keep insertion order
app.json.ensure_ascii = False               # UTF-8 instead of escapes
app.json.compact = False                    # indent even outside debug mode
print(client.get("/offer").get_data(as_text=True))

from datetime import datetime, date
from flask import Flask
from flask.json.provider import DefaultJSONProvider


class Book:
    def __init__(self, title, tags):
        self.title, self.tags = title, set(tags)


def bookshelf_default(o):
    if isinstance(o, (datetime, date)):
        return o.isoformat()                 # ISO 8601 instead of RFC 822
    if isinstance(o, set):
        return sorted(o)
    if isinstance(o, Book):
        return {"title": o.title, "tags": o.tags}      # the set inside is handled by the same function
    return DefaultJSONProvider.default(o)    # Decimal, UUID, dataclasses, __html__ and the TypeError


class BookshelfJSONProvider(DefaultJSONProvider):
    default = staticmethod(bookshelf_default)
    sort_keys = False
    ensure_ascii = False


app = Flask(__name__)
app.json = BookshelfJSONProvider(app)        # the instance form; see json_provider_class below


@app.get("/book")
def book():
    return {"book": Book("Dune", {"sf", "classic"}), "added": datetime(2026, 10, 7, 9, 30)}


payload = app.test_client().get("/book").json
assert payload["added"] == "2026-10-07T09:30:00"
assert payload["book"]["tags"] == ["classic", "sf"]

from flask import Flask


class BookshelfApp(Flask):
    json_provider_class = BookshelfJSONProvider      # instantiated for every application of this class


app = BookshelfApp(__name__)
assert isinstance(app.json, BookshelfJSONProvider)

from flask import Flask
from flask_orjson import OrjsonProvider

app = Flask(__name__)
app.json = OrjsonProvider(app)               # after this, jsonify, get_json and the session use orjson


@app.get("/fast")
def fast():
    return {"title": "Dune", "year": 1965}   # keys are not sorted by orjson: insertion order is kept


assert app.test_client().get("/fast").get_data() == b'{"title":"Dune","year":1965}'

import csv
import io
from flask import Flask, Response, request, stream_with_context

app = Flask(__name__)
BOOKS = [{"id": i, "title": f"Book {i}", "year": 1900 + i} for i in range(1, 6)]


@app.get("/books.csv")
def export_csv():
    min_year = request.args.get("min_year", 0, type=int)

    @stream_with_context
    def generate():
        buffer = io.StringIO()
        writer = csv.writer(buffer)
        writer.writerow(["id", "title", "year"])
        yield buffer.getvalue()
        for book in BOOKS:
            if book["year"] < min_year:
                continue
            buffer.seek(0)
            buffer.truncate()
            writer.writerow([book["id"], book["title"], book["year"]])
            yield buffer.getvalue()

    headers = {"Content-Disposition": 'attachment; filename="books.csv"'}
    return Response(generate(), mimetype="text/csv", headers=headers)


reply = app.test_client().get("/books.csv?min_year=1903")
assert reply.headers["Content-Disposition"].startswith("attachment")
assert reply.get_data(as_text=True).splitlines()[1:] == ["3,Book 3,1903", "4,Book 4,1904", "5,Book 5,1905"]
assert "Content-Length" not in reply.headers

import json
import time
from flask import Flask, Response, stream_with_context

app = Flask(__name__)


@app.get("/imports/<int:job_id>/events")
def import_events(job_id):
    def events():
        for done in range(0, 101, 50):
            yield f"event: progress\ndata: {json.dumps({'job': job_id, 'percent': done})}\n\n"
            time.sleep(0.01)                  # a real view would wait for the worker here
        yield "event: done\ndata: {}\n\n"

    response = Response(stream_with_context(events()), mimetype="text/event-stream")
    response.headers["Cache-Control"] = "no-cache"     # an event stream must never be cached
    return response


text = app.test_client().get("/imports/7/events").get_data(as_text=True)
assert text.count("event: progress") == 3 and text.endswith("event: done\ndata: {}\n\n")

from flask import Flask, make_response, request

app = Flask(__name__)
BOOKS = {1: {"id": 1, "title": "Dune", "author": "Frank Herbert"}}


@app.get("/books/<int:book_id>")
def get_book(book_id):
    response = make_response(BOOKS[book_id])
    response.cache_control.public = True
    response.cache_control.max_age = 60            # clients may reuse it for a minute
    response.add_etag()                            # strong ETag computed from the body
    return response.make_conditional(request)      # 304 if the client already has this version


client = app.test_client()
first = client.get("/books/1")
assert first.status_code == 200 and "max-age=60" in first.headers["Cache-Control"]
again = client.get("/books/1", headers={"If-None-Match": first.headers["ETag"]})
assert again.status_code == 304 and again.get_data() == b""
BOOKS[1]["title"] = "Dune (revised)"
assert client.get("/books/1", headers={"If-None-Match": first.headers["ETag"]}).status_code == 200

from flask import Flask, request

app = Flask(__name__)
BOOK = {"id": 1, "title": "Dune"}


@app.get("/books/1")
def book():
    best = request.accept_mimetypes.best_match(["application/json", "text/html"], default="application/json")
    if best == "text/html":
        return f"<h1>{BOOK['title']}</h1>"
    return BOOK


client = app.test_client()
assert client.get("/books/1", headers={"Accept": "text/html"}).mimetype == "text/html"
assert client.get("/books/1", headers={"Accept": "application/json"}).json["id"] == 1
assert client.get("/books/1", headers={"Accept": "*/*"}).mimetype == "application/json"

import secrets
from flask import Flask

app = Flask(__name__)


@app.after_request
def add_default_headers(response):
    response.headers.setdefault("X-Content-Type-Options", "nosniff")     # no MIME sniffing
    response.headers.setdefault("Referrer-Policy", "same-origin")
    response.headers.setdefault("X-Request-Id", secrets.token_hex(8))
    return response


@app.get("/")
def home():
    return {"status": "ok"}


headers = app.test_client().get("/").headers
assert headers["X-Content-Type-Options"] == "nosniff" and len(headers["X-Request-Id"]) == 16

import io
import tempfile
from pathlib import Path
from flask import Flask, send_file, send_from_directory

app = Flask(__name__)
EXPORTS = Path(tempfile.mkdtemp())           # a configured absolute directory in a real application
(EXPORTS / "catalogue.txt").write_text("Dune\nSolaris\n")
app.config["EXPORT_DIR"] = EXPORTS


@app.get("/exports/<path:name>")
def download_export(name):
    # name comes from the client: send_from_directory refuses ../ tricks and answers 404
    return send_from_directory(app.config["EXPORT_DIR"], name, as_attachment=True, max_age=3600)


@app.get("/report.csv")
def report():
    csv_bytes = b"id,title\n1,Dune\n2,Solaris\n"
    return send_file(io.BytesIO(csv_bytes), mimetype="text/csv", as_attachment=True, download_name="report.csv")


@app.get("/cover.txt")
def cover():
    return send_file(app.config["EXPORT_DIR"] / "catalogue.txt")      # trusted path built by the server


client = app.test_client()
reply = client.get("/exports/catalogue.txt")
assert reply.status_code == 200 and "attachment" in reply.headers["Content-Disposition"]
assert "max-age=3600" in reply.headers["Cache-Control"]
assert client.get("/exports/../app.py").status_code == 404
assert client.get("/exports/missing.txt").status_code == 404
assert client.get("/report.csv").headers["Content-Disposition"] == "attachment; filename=report.csv"

# conditional request: the ETag from the first response avoids sending the file again
tag = reply.headers["ETag"]
assert client.get("/exports/catalogue.txt", headers={"If-None-Match": tag}).status_code == 304
# range request: only the first four bytes (Content-Range tells where they fit)
partial = client.get("/cover.txt", headers={"Range": "bytes=0-3"})
assert partial.status_code == 206 and partial.data == b"Dune"
assert partial.headers["Content-Range"] == "bytes 0-3/13"
assert client.get("/cover.txt").headers["Cache-Control"] == "no-cache"     # no max_age: revalidate every time

from pathlib import Path
import tempfile
from flask import Flask, send_file

app = Flask(__name__)
app.config["USE_X_SENDFILE"] = True           # in production: only behind a server that handles the header
path = Path(tempfile.mkdtemp()) / "cover.txt"
path.write_text("Dune\n")


@app.get("/cover")
def cover():
    return send_file(path)


reply = app.test_client().get("/cover")
assert reply.headers["X-Sendfile"] == str(path) and reply.data == b""

import pytest
from flask import Flask


def create_app():
    app = Flask(__name__)

    @app.get("/books/<int:book_id>")
    def get_book(book_id):
        if book_id != 1:
            return {"error": "not found"}, 404
        return {"id": 1, "title": "Dune"}

    return app


@pytest.fixture
def client():
    return create_app().test_client()


@pytest.mark.parametrize("book_id, status", [(1, 200), (2, 404)])
def test_get_book(client, book_id, status):
    response = client.get(f"/books/{book_id}")
    assert response.status_code == status
    assert response.mimetype == "application/json"


# the same checks run here without pytest
c = create_app().test_client()
assert c.get("/books/1").json == {"id": 1, "title": "Dune"}
assert c.get("/books/2").json == {"error": "not found"}