Skip to content

Generate PDF responses with FastAPI, Flask, and Django

Fullbleed returns PDF bytes from Python data and HTML/CSS. Pass those bytes to your framework's response object to serve an invoice, report, or statement. The starter below sends a designed invoice as a download. It includes a browser page, editable HTML/CSS, and the same document renderer behind three small framework adapters. A short invoice fits on one page; a 24-line sample continues across three pages with repeated table headings and page numbers.

Download the Python starter Open the sample PDF Open the 24-line PDF

Northstar Studio invoice with large green typography, three line items, and an orange-accented total panel.

The source record and download hashes identify the exact source files, fonts, package version, and generated sample. This is a fictional integration example; connect your application's authorized record lookup before serving real invoices.

To try a layout before starting a server, open the browser playground, change the sample customer name, and select Render PDF. It runs on your device without an account or installation. The starter on this page adds Python data, calculated totals, and an HTTP download route.

Want a container? The same download includes a tested Docker path for the FastAPI app, using Debian slim or Alpine.

Set up the examples

Use Python 3.10–3.14. Extract the starter, open its fullbleed-python-invoice directory, and create a virtual environment:

python -m venv .venv

Activate it with source .venv/bin/activate on macOS/Linux or .venv\Scripts\Activate.ps1 in Windows PowerShell. A repository checkout also works: the source directory is examples/web_frameworks.

Choose one framework below. Each requirement file installs that framework; fullbleed remains a separate package. The examples are checked with Fullbleed 2.5.47, FastAPI 0.142.2, Flask 3.1.3, and Django 5.2.17.

Each app serves two fictional records:

http://127.0.0.1:8000/invoices/INV-1042.pdf
http://127.0.0.1:8000/invoices/INV-1043.pdf

Open http://127.0.0.1:8000/ after starting the app and select Download invoice. The browser downloads invoice.pdf, which contains three line items and a total of USD 1,870.00. The Download the 24-line invoice link renders INV-1043, with a total of USD 600.00 across three pages. An unknown invoice ID returns HTTP 404. Stop the server before trying another framework on the same port.

FastAPI

python -m pip install fullbleed==2.5.47 -r requirements-fastapi.txt
python -m uvicorn fastapi_app:app --host 127.0.0.1 --port 8000

The route in fastapi_app.py uses the shared invoice.py renderer:

from fastapi import FastAPI, HTTPException, Response
from invoice import PDF_HEADERS, load_invoice, render_invoice

class PDFResponse(Response):
    media_type = "application/pdf"

app = FastAPI(title="Fullbleed invoice example")

@app.get("/invoices/{invoice_id}.pdf", response_class=PDFResponse)
def invoice_pdf(invoice_id: str) -> PDFResponse:
    invoice = load_invoice(invoice_id)
    if invoice is None:
        raise HTTPException(status_code=404, detail="Invoice not found")
    return PDFResponse(render_invoice(invoice), headers=PDF_HEADERS)

The custom response class advertises application/pdf in OpenAPI. You can also try the route at http://127.0.0.1:8000/docs. See FastAPI's response documentation for how explicit response classes affect the generated API schema.

The route uses a normal def because rendering is synchronous. FastAPI runs these route functions in its thread pool. Calling a synchronous renderer directly inside async def would still occupy that event-loop thread until rendering finishes. See FastAPI's concurrency documentation.

Flask

python -m pip install fullbleed==2.5.47 -r requirements-flask.txt
python -m flask --app flask_app run --host 127.0.0.1 --port 8000

flask_app.py returns a regular Flask response:

from flask import Flask, Response, abort
from invoice import PDF_HEADERS, load_invoice, render_invoice

app = Flask(__name__)

@app.get("/invoices/<invoice_id>.pdf")
def invoice_pdf(invoice_id: str) -> Response:
    invoice = load_invoice(invoice_id)
    if invoice is None:
        abort(404)
    return Response(
        render_invoice(invoice), mimetype="application/pdf", headers=PDF_HEADERS
    )

See Flask's Response API for response bodies, media types, and headers.

Django

python -m pip install fullbleed==2.5.47 -r requirements-django.txt
python django_app.py runserver 127.0.0.1:8000 --noreload

The complete Django example includes minimal local settings. In an existing project, keep your project's settings and adapt this view and URL pattern:

from django.http import Http404, HttpResponse
from django.urls import path
from django.views.decorators.http import require_safe
from invoice import PDF_HEADERS, load_invoice, render_invoice

@require_safe
def invoice_pdf(request, invoice_id: str) -> HttpResponse:
    invoice = load_invoice(invoice_id)
    if invoice is None:
        raise Http404("Invoice not found")
    return HttpResponse(
        render_invoice(invoice), content_type="application/pdf", headers=PDF_HEADERS
    )

urlpatterns = [path("invoices/<str:invoice_id>.pdf", invoice_pdf)]

Adjust the invoice import to its location in your Django project. See Django's HttpResponse documentation for response construction and headers.

The shared document renderer

invoice.py contains the fictional record lookup and render_invoice(). It calculates line totals with Decimal, escapes text before inserting it into HTML, and registers the Inter font shipped with Fullbleed alongside the included DM Serif Display and Bebas Neue families. A new PdfEngine renders each request into memory. Font licenses and pinned source hashes are included in fonts/.

Edit the HTML and CSS

Change templates/invoice.html for document structure and templates/invoice.css for typography, spacing, columns, and color. The renderer reads those files for each request, so a new download uses your edits without restarting the server. Its Python string.Template placeholders include $customer, $number, $rows, and $total; write a literal dollar sign as $$. Text values are escaped before substitution and are not interpreted again as template markup.

The A4 layout uses automatic content height so longer tables continue across pages. Its .closing wrapper keeps totals and payment instructions together. The @page margins reserve footer space, and invoice.py supplies the engine's {page} / {pages} counters. Keep that automatic height when adapting the design; a fixed page-height container can put later rows outside the visible PDF page. Review your longest records after changing fonts, widths or spacing.

This starter leaves tax, discounts, invoice numbering, payment collection, and application authentication to your application. static/index.html is the local demo page; replace it with your application's interface when integrating.

Return a private PDF attachment

The response headers are shared too:

PDF_HEADERS = {
    "Content-Disposition": 'attachment; filename="invoice.pdf"',
    "Cache-Control": "private, no-store",
}

The download filename is fixed. To display the PDF in the browser instead, change attachment to inline. The response carries binary PDF bytes directly; it does not need JSON or base64 encoding, and requests do not share output files.

Replace load_invoice() with your application's authorized record lookup. It returns an invoice number, customer, date strings, and items with descriptions, integer quantities, unit-price strings, and an optional item detail. Keep access checks before rendering.

Verify and deploy your workflow

From the extracted starter's directory, with Fullbleed installed:

python -m pip install -r requirements-check.txt
python check_examples.py --out output/check

The check exercises each framework's test client and starts the documented local servers in turn. It verifies actual HTTP downloads, an independent PDF reader's text and totals, page count, embedded fonts, headers, 404/405 responses, and matching simultaneous downloads. It also checks font/license hashes, literal markup and placeholder-like customer text, and the saved preview. Servers stop when the checks finish. Layout fixtures cover 0, 3, 24 and 80 items, wrapped descriptions, and page-break boundaries at 4, 5, 16 and 17 items. They check row order, repeated headings, page counters, and that totals and payment text stay together on the final page. PDFium also checks every text character's position in the final PDFs: text extraction alone can find text outside the visible page. These inspection packages are development dependencies, separate from the invoice renderer.

Review output/check/verification.json, its PDFs, and the PNG preview after a layout change. To refresh the download page's saved preview, run:

python check_examples.py --out output/check --update-preview

The browser page shows a saved preview of the included invoice. Its Download invoice link always renders the current HTML/CSS. Verification covers these synthetic fixtures and local servers; it does not establish production capacity or PDF standards conformance.

For the FastAPI app, follow the Docker deployment guide. The Flask and Django commands above run local development servers; use your framework's deployment setup for a public app. For large jobs, render in your job queue and store the finished PDF for download. The variable-data guide covers compiled document families when many records share a template.

Invoice data examples · Python API · Ask a usage question in Q&A

For help with an integration, include your framework, Fullbleed version, the command or request you tried, and the expected response. Use a small fictional record and include the response status or error text.