# kozea/weasyprint architecture

> Architecture diagram of the GitHub repository kozea/weasyprint, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kozea/weasyprint
- Repository: https://github.com/kozea/weasyprint

## Overview

WeasyPrint is a Python HTML/CSS rendering engine that produces paginated PDF documents. The principal workflow is to accept HTML and stylesheets, build styled formatting boxes, lay them out across pages, draw their content, and export a PDF. Supporting branches handle external resources, images and SVG, text and fonts, and PDF metadata and accessibility features. The source index confirms several module dependencies; some orchestration details and unsampled PDF stages are shown only as documented or unverified relationships.

Main entry points: [`weasyprint/layout/block.py`](https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/block.py) (Block and page flow), [`weasyprint/html.py`](https://github.com/kozea/weasyprint/blob/main/weasyprint/html.py) (HTML handling), [`weasyprint/css/__init__.py`](https://github.com/kozea/weasyprint/blob/main/weasyprint/css/__init__.py) (Stylesheet cascade), [`weasyprint/draw/__init__.py`](https://github.com/kozea/weasyprint/blob/main/weasyprint/draw/__init__.py) (Page drawing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input and resources"]
  node_html["HTML handling<br/>[html.py]"]
  node_url["URL fetching<br/>[urls.py]"]
end

subgraph group_style["CSS processing"]
  node_css["Stylesheet cascade<br/>[__init__.py]"]
  node_tokens["CSS tokens<br/>[tokens.py]"]
  node_validation["Property validation<br/>[properties.py]"]
  node_computed["Computed values<br/>[computed_values.py]"]
end

subgraph group_layout["Formatting and layout"]
  node_boxes["Formatting boxes<br/>[boxes.py]"]
  node_boxbuild["Box construction<br/>[build.py]"]
  node_block["Block and page flow<br/>[block.py]"]
  node_grid["Grid layout<br/>[grid.py]"]
  node_table["Table layout<br/>[table.py]"]
  node_absolute["Positioned layout<br/>[absolute.py]"]
  node_page["Page layout<br/>[page.py]"]
end

subgraph group_render["Drawing and assets"]
  node_draw["Page drawing<br/>[__init__.py]"]
  node_images["Image decoding<br/>[images.py]"]
  node_svg["SVG rendering<br/>[__init__.py]"]
  node_fonts["Font handling<br/>[fonts.py]"]
end

subgraph group_pdf["PDF output"]
  node_document["Document rendering<br/>[document.py]"]
  node_pdf["PDF writing<br/>[__init__.py]"]
  node_pdfmeta["PDF metadata<br/>[metadata.py]"]
  node_pdfua["PDF accessibility<br/>[pdfua.py]"]
end

node_developer(("Web developer"))

node_developer -->|"provides HTML"| node_html
node_html -->|"resolves resources"| node_url
node_html -->|"finds stylesheets"| node_css
node_css -->|"tokenizes CSS"| node_tokens
node_css -->|"validates declarations"| node_validation
node_css -->|"computes styles"| node_computed
node_html -->|"handles elements"| node_boxes
node_boxbuild -->|"reads elements"| node_html
node_boxbuild -->|"builds boxes"| node_boxes
node_block -->|"lays out boxes"| node_boxes
node_block -->|"dispatches grid"| node_grid
node_block -->|"dispatches tables"| node_table
node_block -->|"lays out positioned boxes"| node_absolute
node_grid -->|"lays out children"| node_block
node_grid -->|"uses table layout"| node_table
node_page -.->|"paginates content"| node_block
node_draw -->|"draws boxes"| node_boxes
node_draw -->|"draws images"| node_images
node_images -->|"renders SVG"| node_svg
node_draw -.->|"draws text"| node_fonts
node_document -.->|"renders pages"| node_draw
node_document -.->|"exports PDF"| node_pdf
node_pdf -.->|"writes metadata"| node_pdfmeta
node_pdf -.->|"supports accessibility"| node_pdfua

click node_html "https://github.com/kozea/weasyprint/blob/main/weasyprint/html.py"
click node_url "https://github.com/kozea/weasyprint/blob/main/weasyprint/urls.py"
click node_css "https://github.com/kozea/weasyprint/blob/main/weasyprint/css/__init__.py"
click node_tokens "https://github.com/kozea/weasyprint/blob/main/weasyprint/css/tokens.py"
click node_validation "https://github.com/kozea/weasyprint/blob/main/weasyprint/css/validation/properties.py"
click node_computed "https://github.com/kozea/weasyprint/blob/main/weasyprint/css/computed_values.py"
click node_boxes "https://github.com/kozea/weasyprint/blob/main/weasyprint/formatting_structure/boxes.py"
click node_boxbuild "https://github.com/kozea/weasyprint/blob/main/weasyprint/formatting_structure/build.py"
click node_block "https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/block.py"
click node_grid "https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/grid.py"
click node_table "https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/table.py"
click node_absolute "https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/absolute.py"
click node_page "https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/page.py"
click node_document "https://github.com/kozea/weasyprint/blob/main/weasyprint/document.py"
click node_draw "https://github.com/kozea/weasyprint/blob/main/weasyprint/draw/__init__.py"
click node_images "https://github.com/kozea/weasyprint/blob/main/weasyprint/images.py"
click node_svg "https://github.com/kozea/weasyprint/blob/main/weasyprint/svg/__init__.py"
click node_fonts "https://github.com/kozea/weasyprint/blob/main/weasyprint/text/fonts.py"
click node_pdf "https://github.com/kozea/weasyprint/blob/main/weasyprint/pdf/__init__.py"
click node_pdfmeta "https://github.com/kozea/weasyprint/blob/main/weasyprint/pdf/metadata.py"
click node_pdfua "https://github.com/kozea/weasyprint/blob/main/weasyprint/pdf/pdfua.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_html,node_url toneBlue
class node_css,node_tokens,node_validation,node_computed toneAmber
class node_boxes,node_boxbuild,node_block,node_grid,node_table,node_absolute,node_page toneMint
class node_draw,node_images,node_svg,node_fonts toneRose
class node_document,node_pdf,node_pdfmeta,node_pdfua,node_developer toneIndigo
```

## Components

### Input and resources

- [HTML handling](https://github.com/kozea/weasyprint/blob/main/weasyprint/html.py): `weasyprint/html.py`
- [URL fetching](https://github.com/kozea/weasyprint/blob/main/weasyprint/urls.py): `weasyprint/urls.py`

### CSS processing

- [Stylesheet cascade](https://github.com/kozea/weasyprint/blob/main/weasyprint/css/__init__.py): `weasyprint/css/__init__.py`
- [CSS tokens](https://github.com/kozea/weasyprint/blob/main/weasyprint/css/tokens.py): `weasyprint/css/tokens.py`
- [Property validation](https://github.com/kozea/weasyprint/blob/main/weasyprint/css/validation/properties.py): `weasyprint/css/validation/properties.py`
- [Computed values](https://github.com/kozea/weasyprint/blob/main/weasyprint/css/computed_values.py): `weasyprint/css/computed_values.py`

### Formatting and layout

- [Formatting boxes](https://github.com/kozea/weasyprint/blob/main/weasyprint/formatting_structure/boxes.py): `weasyprint/formatting_structure/boxes.py`
- [Box construction](https://github.com/kozea/weasyprint/blob/main/weasyprint/formatting_structure/build.py): `weasyprint/formatting_structure/build.py`
- [Block and page flow](https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/block.py): `weasyprint/layout/block.py`
- [Grid layout](https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/grid.py): `weasyprint/layout/grid.py`
- [Table layout](https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/table.py): `weasyprint/layout/table.py`
- [Positioned layout](https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/absolute.py): `weasyprint/layout/absolute.py`
- [Page layout](https://github.com/kozea/weasyprint/blob/main/weasyprint/layout/page.py): `weasyprint/layout/page.py`

### Drawing and assets

- [Page drawing](https://github.com/kozea/weasyprint/blob/main/weasyprint/draw/__init__.py): `weasyprint/draw/__init__.py`
- [Image decoding](https://github.com/kozea/weasyprint/blob/main/weasyprint/images.py): `weasyprint/images.py`
- [SVG rendering](https://github.com/kozea/weasyprint/blob/main/weasyprint/svg/__init__.py): `weasyprint/svg/__init__.py`
- [Font handling](https://github.com/kozea/weasyprint/blob/main/weasyprint/text/fonts.py): `weasyprint/text/fonts.py`

### PDF output

- [Document rendering](https://github.com/kozea/weasyprint/blob/main/weasyprint/document.py): `weasyprint/document.py`
- [PDF writing](https://github.com/kozea/weasyprint/blob/main/weasyprint/pdf/__init__.py): `weasyprint/pdf/__init__.py`
- [PDF metadata](https://github.com/kozea/weasyprint/blob/main/weasyprint/pdf/metadata.py): `weasyprint/pdf/metadata.py`
- [PDF accessibility](https://github.com/kozea/weasyprint/blob/main/weasyprint/pdf/pdfua.py): `weasyprint/pdf/pdfua.py`

### Other components

- **Web developer**

## Connections

- Web developer → HTML handling: provides HTML
- HTML handling → URL fetching: resolves resources (evidence: `weasyprint/html.py`)
- HTML handling → Stylesheet cascade: finds stylesheets (evidence: `weasyprint/css/__init__.py`)
- Stylesheet cascade → CSS tokens: tokenizes CSS (evidence: `weasyprint/css/__init__.py`)
- Stylesheet cascade → Property validation: validates declarations (evidence: `weasyprint/css/__init__.py`)
- Stylesheet cascade → Computed values: computes styles (evidence: `weasyprint/css/__init__.py`)
- HTML handling → Formatting boxes: handles elements (evidence: `weasyprint/html.py`)
- Box construction → HTML handling: reads elements (evidence: `weasyprint/formatting_structure/build.py`)
- Box construction → Formatting boxes: builds boxes (evidence: `weasyprint/formatting_structure/build.py`)
- Block and page flow → Formatting boxes: lays out boxes (evidence: `weasyprint/layout/block.py`)
- Block and page flow → Grid layout: dispatches grid (evidence: `weasyprint/layout/block.py`)
- Block and page flow → Table layout: dispatches tables (evidence: `weasyprint/layout/block.py`)
- Block and page flow → Positioned layout: lays out positioned boxes (evidence: `weasyprint/layout/block.py`)
- Grid layout → Block and page flow: lays out children (evidence: `weasyprint/layout/grid.py`)
- Grid layout → Table layout: uses table layout (evidence: `weasyprint/layout/grid.py`)
- Page layout → Block and page flow: paginates content
- Page drawing → Formatting boxes: draws boxes (evidence: `weasyprint/draw/__init__.py`)
- Page drawing → Image decoding: draws images (evidence: `weasyprint/draw/__init__.py`)
- Image decoding → SVG rendering: renders SVG (evidence: `weasyprint/images.py`)
- Page drawing → Font handling: draws text
- Document rendering → Page drawing: renders pages
- Document rendering → PDF writing: exports PDF
- PDF writing → PDF metadata: writes metadata
- PDF writing → PDF accessibility: supports accessibility
