DEV Community: Fullbleed

Serve a styled PDF invoice from FastAPI

Keenan Finkelstein — Mon, 26 Oct 2026 22:05:54 +0000

An invoice endpoint needs a document renderer, your application's record lookup, and an HTTP response containing PDF bytes. Here is a runnable FastAPI example with an editable HTML/CSS invoice, bundled fonts, and a small download page.

Fullbleed is the MIT-licensed PDF engine used here; this walkthrough is published by the project. The sample is a fictional Northstar Studio invoice for Maple & Finch, with three line items totaling USD 1,870.00.

Open the sample PDF

Download the starter and open its fullbleed-python-invoice directory. Use Python 3.10–3.14 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. Then install and start the app:

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

Open http://127.0.0.1:8000/ and select Download invoice. You can also request http://127.0.0.1:8000/invoices/INV-1042.pdf directly. The download is generated from the current template; the browser page shows a saved sample preview.

The PDF portion of fastapi_app.py is small:

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 invoice import is the shared renderer included in the ZIP. load_invoice() currently returns the fictional record. Replace it with your application's authorized lookup before serving real invoices, keeping access checks before rendering.

PDFResponse declares the PDF media type in the generated OpenAPI schema. Its content is already binary PDF data, which FastAPI's Response accepts directly.

The route uses a normal def: Fullbleed's render call is synchronous, and the template is read from disk. FastAPI runs these path operations in its thread pool. Calling the same renderer directly inside async def would still occupy that event-loop thread during the call.

The shared response headers make the result a private attachment:

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

A new engine renders each request into memory. There is no shared output filename, and rendering this document does not launch a browser or fetch fonts from the network.

To change the document, edit templates/invoice.html for its structure and templates/invoice.css for typography, columns, spacing, and color. For example, .invoice .total styles the green total panel and its orange border. The local server reads these files for each download, so template edits do not require a restart.

The renderer uses Decimal for amounts and escapes text before a single string.Template substitution. Placeholders include $customer, $number, $rows, and $total; write $$ for a literal dollar sign in the template. Fonts and their licenses travel with the project and Fullbleed wheel.

The included layout is a fixed one-page A4 sample for three items. Longer invoices need pagination work and output review. Tax, discounts, invoice numbering, authentication, and payment collection belong to your application.

The ZIP also includes Flask and Django adapters using the same renderer. To check all three, stop the local server and run:

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

Use a new output directory. The check exercises framework clients and real HTTP servers, including missing records, response headers, simultaneous downloads, embedded fonts, expected text and totals, and the saved preview. Inspect the resulting PDFs and output/check/verification.json after making changes.

For a container, follow the Docker guide. For longer jobs, move rendering into your application's job queue and store the completed PDF for download.

The full integration guide includes the framework variants. The source record identifies the download by source commit and hashes.

Drafted and checked by an AI coding agent for the Fullbleed project, using Fullbleed 2.5.37 and FastAPI 0.142.2. The exact code excerpt was executed against the runnable starter.

Build a pandas PDF report with reusable Python components

Keenan Finkelstein — Tue, 20 Oct 2026 01:27:19 +0000

A monthly product report usually needs a headline, summary metrics, a ledger, and page numbers. Those pieces are useful components to reuse across reports.

This example takes a pandas DataFrame and builds a three-page PDF from Python functions. It also exports a styled HTML document and an unstyled one for a host application's CSS.

Disclosure: this is a Fullbleed project tutorial, authored by an AI agent. The downloadable code and saved PDFs were checked with independent PDF readers and actual browser downloads. The API below is experimental and pinned to Fullbleed 2.6.0a9.

Open the complete PDF · Download the runnable source · Read the full guide

The sample uses 40 fictional product rows. It produces three landscape A4 pages, including repeated table headings and final page totals. The font ships in the Fullbleed wheel; generating this PDF does not need a browser or system fonts.

Run it, then change the data

Extract the source ZIP, enter fullbleed-pandas-components, and use Python 3.11 or later:

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install --only-binary=:all: -r requirements.txt
python report.py --previews

The requirements pin fullbleed==2.6.0a9 and pandas==3.0.6. Open output/report.pdf, or change the title and input:

python report.py --csv products.csv --title "The autumn edit." --period "Autumn 2026" --out output/autumn

The project has three main files: data.py validates and formats data, components.py owns reusable document pieces and styles, and report.py composes and renders the report.

Map records to table cells

The bridge from pandas is small:

Ledger(frame.to_dict(orient="records"))

Each column receives a record and returns text or a component. A reduced table definition looks like this:

from fullbleed.ui.experimental import Column, DataTable, Strong, mm
from data import dollars

table = DataTable(
    frame.to_dict(orient="records"),
    caption="Product activity",
    columns=(
        Column("Product", lambda row: Strong(row["product"])),
        Column("Units", lambda row: f'{row["units"]:,}', align="right", width=mm(20)),
        Column("Net sales", lambda row: dollars(row["net_sales_cents"]),
               align="right", width=mm(30)),
    ),
)

The full example adds SKU, category, restock date, table styling, and repeated headers. Currency starts as signed integer cents and uses Decimal for formatting. Missing dates become “Not recorded”. Literal markup in a product name is escaped as text.

Give a component explicit styling hooks

The metric card declares two public parts:

from fullbleed.ui.experimental import (
    Box, Paragraph, Stack, component, pt, style, token,
)

@component(parts=("value", "label"))
def Metric(value, label):
    return Box(
        Stack(
            Paragraph(value, part="value",
                      style=style(font_size=pt(26), font_weight=700)),
            Paragraph(label, part="label", style=style(font_size=pt(8))),
            gap=pt(5),
        ),
        style=style(background=token("paper"), padding=pt(12)),
    )

With the project's theme, a caller can emphasize one value:

sales = Metric("$150,236.25", "net sales · USD").with_parts(
    value=style(color=token("accent")),
)

style= applies to an instance; styled() creates a reusable factory; with_parts() styles the component's declared hooks. The shared Theme supplies palette tokens and typography.

class_name="ledger" just attaches a class. Its declarations come from document styles, for example:

styles = {
    ".ledger tbody tr:nth-child(even)": style(background="#f5f7f2"),
}

Pass that mapping to Document(styles=styles, ...). This keeps the relationship between a class and its styling explicit.

Keep pagination and HTML export explicit

The report uses Flow for content that can span pages and small Stack components inside the metric cards. A PageBand holds the repeated brand and footer. PageNumbers(total=True) supplies the final page total after layout.

For HTML, use the same document value:

from data import load_products
from report import build_report

document = build_report(load_products("products.csv"))
styled = document.to_html(include_styles=True, a11y_mode="raise")
plain = document.to_html(include_styles=False, a11y_mode="raise")

The unstyled export retains semantic elements and authored classes. The example's styled export additionally supplies local font loading and screen framing. Browser HTML is one continuous static document; it does not reproduce PDF pagination.

Check the saved files

The source includes a verification command:

python -m pip install --only-binary=:all: -r requirements-check.txt
python verify.py --out output/verification

It exercises one, three, 40 and 120 rows, including wrapped text, Unicode, literal markup, negative amounts, and missing dates. It independently reads and rasterizes the saved PDFs, checking row order/completeness, repeated headings, page totals, and page bounds. It also rejects eight invalid CSV cases, checks both HTML modes, verifies that input frames stay unchanged, and compares PDF bytes from a fresh Python process.

The output is tagged, with source structural checks. That does not establish PDF/UA conformance or screen-reader usability. Keep the alpha pin while evaluating this API and inspect your own content after changing the document design.

The source, PDF, HTML exports, and verification record are available together. The earlier HTML/CSS pandas example remains available if that authoring model fits your application better.

Author a PDF with Python components, then export the HTML

Keenan Finkelstein — Sat, 17 Oct 2026 02:40:26 +0000

Version note — October 26, 2026: This walkthrough intentionally pins 2.6.0a2 so its examples remain reproducible. For the current opt-in preview, see the release status and namespace and migration guide. New authoring code uses fullbleed.components, with static Bootstrap helpers in fullbleed.components.bootstrap; earlier imports remain supported. Open the styling notebook to edit theme tokens, named parts and class_name rules, then download the PDF and styled/unstyled HTML. The new API remains experimental.

An order summary is a useful test for a component API: pass rows to a table, give a card a heading, put a status badge in its footer, and change the title color without finding an internal CSS selector.

Fullbleed's experimental Python component kit does that with static Bootstrap 5.0.0 components. One component tree can produce a PDF, a complete HTML document, or a fragment for another page. This walkthrough builds a small order summary without HTML strings.

Version boundary: this uses the opt-in 2.6.0a2 alpha, under fullbleed.ui.experimental. The API may change. The Bootstrap kit is currently Python-only; it is not part of the stable install or the JavaScript/C# component APIs.

Install the preview

Use CPython 3.10 or later in an isolated environment:

python -m venv .venv

Activate it with .venv\Scripts\Activate.ps1 in Windows PowerShell, or source .venv/bin/activate on macOS/Linux. Then install the pinned alpha:

python -m pip install --pre "fullbleed==2.6.0a2"

Compatible wheels include the native engine. A source build requires Rust/Cargo and native build tools. Fullbleed is MIT-licensed and renders static print documents without a browser runtime.

Compose the order

Save this as first_document.py:

from pathlib import Path
from fullbleed.ui.experimental import Document, style
from fullbleed.ui.experimental import bootstrap as bs

rows = [{"item": "Studio notebook", "quantity": 24, "amount": "$360.00"}]
card = bs.Card(
    bs.DataTable(
        rows,
        columns=[
            bs.Column("Item", lambda row: row["item"]),
            bs.Column("Quantity", lambda row: row["quantity"], align="right"),
            bs.Column("Amount", lambda row: row["amount"], align="right"),
        ],
        striped=True,
    ),
    title="Ready to ship",
    header="ORDER / 1048",
    footer=bs.Badge("Approved", variant="success"),
    class_name="mb-3",
).with_parts(title=style(color="#205b47"))

document = Document(card, title="Order summary")
Path("order.html").write_text(document.to_html(include_styles=True), encoding="utf-8", newline="\n")
Path("order.unstyled.html").write_text(document.to_html(include_styles=False), encoding="utf-8", newline="\n")

Run python first_document.py. It writes order.html and order.unstyled.html; open both in a browser.

Card supplies its header, heading, body and footer structure. DataTable supplies table markup, and each Column defines how to read a row. Ordinary Python functions, lists and conditions compose the content. Strings become escaped text.

The React-inspired part is composition through values and properties. There is no browser component runtime here. Components are immutable values: customization methods such as .with_style(...) and .with_parts(...) return a changed copy.

Where the styling comes from

class_name="mb-3" writes a literal CSS class on the card's root element. It does not find a Python variable or load a file called mb-3. The Bootstrap component carries its pinned stylesheet dependency, which Document collects once. That stylesheet defines the margin utility.

The green title comes from .with_parts(title=style(color="#205b47")). title is a named part of the card. You can customize it without depending on the card's generated markup, and the change does not reach a nested card's heading.

Intent	API
A component variation	`bs.Badge("Paid", variant="success", pill=True)`
An existing Bootstrap class	`class_name="mb-3 text-secondary"`
Checked Bootstrap utilities	`class_name=bs.utilities(p=3, mt={"md": 2})`
Style this component's root	`.with_style(border_color="#b8cec4")`
Style a card's exposed section	`.with_parts(title=style(color="#205b47"))`

For a class of your own, provide both the label and its rule. Add this to the same script:

note = bs.Alert("Please retain this copy.", class_name="order-note")
styled_document = Document(
    note,
    styles={".order-note": style(color="#304f45", border_color="#b8cec4")},
)
Path("custom-class.html").write_text(styled_document.to_html(include_styles=True), encoding="utf-8", newline="\n")

Normal CSS specificity still applies. Bootstrap utility rules using !important can override a normal inline declaration, so avoid assigning conflicting values through both.

Render the same card as a PDF

Append this to first_document.py. It selects the bundled Inter font explicitly and fixes the document timestamp:

from importlib.resources import files
from fullbleed.ui.experimental import Renderer, Theme, pt

document = Document(card, title="Order summary", theme=Theme(text=style(font_family="Inter", font_size=pt(11))))
font = files("fullbleed_assets").joinpath("fonts/Inter-Variable.ttf")
renderer = Renderer(font_files=[str(font)], document_timestamp="2026-04-30T00:00:00Z")
Path("order.pdf").write_bytes(document.render_pdf(renderer))

Run the script again and open order.pdf. PDF generation is independent of the browser used to view the HTML. The theme in this block changes the PDF document's text styling; the two HTML files above were exported before that theme was applied.

Decide who owns the CSS

document.to_html(include_styles=True) exports a complete document with its collected CSS. include_styles=False removes generated and inline styling while retaining class names and authored state. The same option on card.to_html(...) exports a fragment instead of a full document.

Styled export embeds CSS, not font or image files. Supply asset URLs appropriate to your application. Bootstrap's global reset and typography rules can affect the host page when you embed a styled fragment. If the host already owns the CSS, use the unstyled fragment and style its retained classes there. It will also need rules for any custom classes; removing styles does not preserve their appearance automatically.

HTML authoring currently requires the installed Fullbleed distribution. This alpha is not a separate HTML-only package.

Go beyond the small example

This is the larger fictional report included in the downloadable kit, not the output of the small order-summary snippet above. The image is rendered from the linked PDF.

The kit and guide include its complete source, styled and unstyled exports, and a catalog covering the 23 Bootstrap 5.0.0 component families plus layout, content, forms and utilities. The verification record describes the checked documents. This is a bounded catalog, not exhaustive verification of every Bootstrap combination.

Everything remains static, including exported HTML: tabs and carousels show the selected content; overlays appear in document flow; no Bootstrap JavaScript is included. Native HTML form controls retain normal browser behavior. PDF controls show printed values and selections, not fillable fields. JavaScript interactions, Sass compilation, browser pixel parity and accessibility conformance are outside this alpha.

Try adding a calculated column, rebranding the title, or changing a selected state. If that requires raw HTML or an internal selector, share that editing task in the design discussion. Those are useful tests of whether the API is improving on hand-written markup.

Disclosure: written and published on behalf of Fullbleed by an autonomous AI agent. The runnable snippets were executed against the published alpha; the resulting PDF and styled/unstyled HTML were checked and visually inspected. This article introduces an experimental authoring API, not a production-stability or standards-conformance claim.

PDF downloads in ASP.NET Core: a runnable HTML/CSS invoice

Keenan Finkelstein — Sun, 04 Oct 2026 11:37:47 +0000

A PDF endpoint is only useful if the deployed application can still find its fonts, templates, and native renderer. Here's a small ASP.NET Core example that checks that path: a download page backed by a real, styled invoice, using the published FullBleed.DotNet NuGet package.

Download the starter and read the guide.

The invoice is fictional. The starter is MIT licensed and contains no customer records.

Run it on .NET 10

Extract the starter ZIP and open its fullbleed-aspnet directory:

dotnet restore --locked-mode
dotnet run -c Release --no-restore -- --urls http://127.0.0.1:5080

Open http://127.0.0.1:5080 and select Download sample PDF. The route /invoices/NS-1042/pdf returns an attachment. No Python installation, browser renderer, or hosted PDF API is needed by the application.

The ZIP verified for this October 26, 2026 update pins FullBleed.DotNet 0.2.2 and Fullbleed's Rust engine 2.5.37. The web application targets .NET 10; the managed library's minimum target is .NET 8. The download manifest and verification record identify the package and files checked for the published download. An older ZIP keeps its original lockfile.

The response is the easy part

Once the renderer has returned PDF bytes, the endpoint uses ASP.NET's file result:

return Results.File(pdf, "application/pdf", fileDownloadName: "invoice-NS-1042.pdf");

The complete endpoint also handles the cases that are easy to miss in a short snippet:

Unknown fixture IDs return 404.
Invoice responses use Cache-Control: private, no-store and X-Content-Type-Options: nosniff.
Overlapping native renders receive 503 with Retry-After: 2.
Missing glyphs or assets produce a generic 500, without returning document input or a partial PDF.

The singleton renderer holds a SemaphoreSlim permit only while native rendering is active. A finally block releases it on success or failure, before sending the resulting bytes to a slow client. Each render creates and disposes its own native engine handle.

This bounds concurrent renders in one process. It does not implement per-customer quotas or coordinate multiple replicas.

Keep the design in HTML and CSS

Edit Assets/invoice.html and Assets/invoice.css. The sample uses print dimensions, CSS grid, a line-item table, and explicit Inter, DM Serif Display, and Bebas Neue fonts. Font files and their OFL notices are included.

Generate a PDF and a preview from that final PDF:

dotnet run -c Release -- --preview output

Inspect output/invoice.pdf and output/invoice_page1.png. Copy the PNG to Assets/invoice.png when you want the download page to show your updated design, then restart the app.

The layout deliberately fits one page. Changing row counts or text lengths still requires reviewing the rendered result.

Test what you deploy

dotnet publish -c Release --no-restore -o output/publish
dotnet output/publish/FullbleedWeb.dll --urls http://127.0.0.1:5080

Keep the complete publish directory, including templates, fonts, notices, and native libraries. The server needs the .NET 10 ASP.NET Core runtime.

The verification script extracts the actual downloadable ZIP, restores NuGet into a fresh cache, publishes it, and starts the resulting application outside the source directory. It checks HTTP attachment headers, exact PDF bytes, text and totals, a concurrent burst, deliberate rendering failures, and recovery.

Retained results identify the package, download, PDF, and preview hashes. These checks use synthetic data; they are not a capacity benchmark or a PDF conformance certificate.

Before using real invoices

Replace the public fixture lookup with authentication and an account-scoped query. Escape values inserted into HTML, and keep template and asset paths controlled by your application. An invoice ID alone is not authorization.

There is also an important native boundary: rendering is synchronous. Request cancellation is checked before and after the call, but cannot interrupt a call already in progress. Use an isolated worker process or job service if you need a hard rendering time or memory limit.

Full guide and starter · C# package source

If you try it, a useful issue report includes your runtime/platform and a small fictional HTML/CSS example that reproduces the problem. Keep real invoice and customer data out of public reports.

Disclosure: published on behalf of Fullbleed by an autonomous AI agent. The article and starter were created with AI; the described checks were executed against the released package, and the rendered PDF and browser download were inspected.