# mattjmorrison/reportlab architecture

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

- Interactive diagram: https://gitdiagram.com/mattjmorrison/reportlab
- Repository: https://github.com/mattjmorrison/reportlab

## Overview

1. This repository is the ReportLab PDF Toolkit: a Python library for generating PDFs, plus chart/graphics rendering utilities and a few ancillary tools and demos. The main runtime is the `reportlab` package under `src/`, with optional native extensions under `src/rl_addons/`.

2. The core architectural boundary is the public Python API in `src/reportlab`, which is split into four major subsystems: `pdfgen` for low-level PDF drawing, `platypus` for high-level document layout, `graphics` for charts/shapes/widgets, and `pdfbase` for fonts, encodings, PDF object modeling, and file-level utilities. Supporting modules in `lib` provide shared utilities, colors, units, geometry, validation, and configuration.

3. `pdfgen` is the low-level document emission layer. Its `canvas.py` is the primary entry point for creating PDF content page by page, while `pathobject.py`, `textobject.py`, `pdfimages.py`, and `pdfgeom.py` support vector paths, text, image embedding, and geometry. This layer ultimately serializes PDF content using structures from `pdfbase`.

4. `pdfbase` is the PDF infrastructure layer beneath both `pdfgen` and `platypus`. It contains the document/object model (`pdfdoc.py`), metrics and font handling (`pdfmetrics.py`, `ttfonts.py`, `cidfonts.py`), form and encryption support (`pdfform.py`, `pdfencrypt.py`), codec and width tables, and low-level PDF helpers. This is where text encoding, font embedding, and PDF object generation are centralized.

5. `platypus` is the document composition system for structured layouts. It provides flowables, frames, paragraph parsing/rendering, tables, templates, and document orchestration. The data flow here is: application creates flowables such as paragraphs, tables, images, or custom elements; `doctemplate.py` paginates them into frames; and the result is emitted through the PDF generation layer.

6. `graphics` is a separate scene-graph subsystem for charts and drawable shapes. `shapes.py`, `widgetbase.py`, and the `charts`, `widgets`, and `barcode` packages define reusable graphical primitives and higher-level visual components. These are rendered through backend-specific exporters in `renderPDF.py`, `renderPS.py`, `renderSVG.py`, and `renderPM.py`.

7. Rendering backends form an important boundary. The same graphics model can be exported to multiple outputs: PDF, PostScript, SVG, and bitmap/image output. `renderPM` is the bitmap path and depends on the optional compiled extension plus supporting C libraries; the other renderers are Python-level backends targeting vector formats.

8. Optional native acceleration lives in `src/rl_addons`. `_rl_accel` provides speedups for text handling, parsing, hyphenation, and other hot paths, while `renderPM` includes the compiled `_renderPM` extension and bundled C support code for rasterization. These extensions are performance and capability enhancers, not required for basic PDF generation.

9. The repository also contains packaging and distribution machinery. `setup.py`, `setup.cfg`, and `ez_setup.py` support installation; `src/reportlab/MANIFEST.in` and the package metadata files define what ships; and `rl_config.py` controls runtime configuration. The README indicates the library is designed to work even without the C extensions, but with reduced performance and bitmap capability.

10. `tests/` is the verification boundary for the library. It covers core PDF generation, font embedding, encryption, image handling, graphics rendering, Platypus layout, multibyte text, utilities, and the optional acceleration modules. This breadth reflects the repository’s major functional seams: document creation, rendering, fonts/text, and backend-specific behavior.

11. `docs/`, `demos/`, and `tools/` are supporting layers rather than runtime dependencies. `demos/` shows end-to-end use of the APIs, `docs/` builds the user guide and reference docs from code examples, and `tools/` contains ancillary generators and document-production helpers such as `pythonpoint` and doc generation scripts. These folders are useful for understanding intended usage, but they do not define the core library architecture.

12. A useful mental model for the architecture diagram is: application code enters through `canvas` or Platypus flowables, uses shared utilities and font/encoding services, produces PDF object structures, and then emits a PDF file or alternate graphics format through a selected renderer. Optional C extensions sit on the hot path where speed or bitmap rendering matters, while tests and docs validate and explain the full stack.

Main entry points: [`src/reportlab/pdfbase`](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/pdfbase) (pdfbase), [`src/reportlab/platypus`](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/platypus) (platypus), [`src/reportlab`](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab) (reportlab), [`src/reportlab/graphics`](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/graphics) (graphics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core library"]
  node_n_reportlab["reportlab<br/>Python package"]
  node_n_lib["lib<br/>Shared utilities"]
  node_n_pdfgen["pdfgen<br/>PDF emission"]
  node_n_pdfbase["pdfbase<br/>PDF infrastructure"]
  node_n_platypus["platypus<br/>Layout engine"]
  node_n_graphics["graphics<br/>Scene graph"]
  node_n_canvas["canvas<br/>[canvas.py]"]
  node_n_pdfdoc["pdfdoc<br/>PDF object model<br/>[pdfdoc.py]"]
  node_n_pdfmetrics["pdfmetrics<br/>Font metrics<br/>[pdfmetrics.py]"]
  node_n_ttfonts["ttfonts<br/>TrueType fonts<br/>[ttfonts.py]"]
  node_n_doctemplate["doctemplate<br/>Pagination<br/>[doctemplate.py]"]
  node_n_flowables["flowables<br/>Layout elements<br/>[flowables.py]"]
  node_n_shapes["shapes<br/>Vector primitives<br/>[shapes.py]"]
  node_n_renderers["renderers<br/>Export backends<br/>[renderPDF.py]"]
end

subgraph group_grp_addons["Native addons"]
  node_n_rl_accel{{"_rl_accel<br/>Python C accel<br/>[_rl_accel.c]"}}
  node_n_renderpm_ext{{"_renderPM<br/>Bitmap extension<br/>[_renderPM.c]"}}
end

subgraph group_grp_support["Support tooling"]
  node_n_tests["tests<br/>Verification suite"]
  node_n_docs_tools["docs/tools<br/>Docs and utilities"]
end

node_n_reportlab -->|"shared util"| node_n_lib
node_n_reportlab -->|"runtime"| node_n_pdfgen
node_n_reportlab -->|"runtime"| node_n_pdfbase
node_n_reportlab -->|"runtime"| node_n_platypus
node_n_reportlab -->|"runtime"| node_n_graphics
node_n_pdfgen -->|"entrypoint"| node_n_canvas
node_n_pdfgen -->|"serialize"| node_n_pdfbase
node_n_pdfbase -->|"model"| node_n_pdfdoc
node_n_pdfbase -->|"fonts"| node_n_pdfmetrics
node_n_pdfbase -->|"embed"| node_n_ttfonts
node_n_platypus -->|"paginate"| node_n_doctemplate
node_n_platypus -->|"compose"| node_n_flowables
node_n_platypus -->|"emit"| node_n_pdfgen
node_n_graphics -->|"model"| node_n_shapes
node_n_graphics -->|"export"| node_n_renderers
node_n_graphics -->|"text/fonts"| node_n_pdfbase
node_n_renderers -->|"pdf"| node_n_pdfgen
node_n_renderers -->|"bitmap path"| node_n_renderpm_ext
node_n_platypus -.->|"speedup"| node_n_rl_accel
node_n_pdfbase -.->|"speedup"| node_n_rl_accel
node_n_graphics -.->|"verified by"| node_n_tests
node_n_pdfbase -.->|"verified by"| node_n_tests
node_n_platypus -.->|"verified by"| node_n_tests
node_n_docs_tools -.->|"explains"| node_n_reportlab
node_n_docs_tools -.->|"examples"| node_n_graphics
node_n_docs_tools -.->|"examples"| node_n_platypus
node_n_tests -.->|"covers"| node_n_rl_accel

click node_n_reportlab "https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab"
click node_n_lib "https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/lib"
click node_n_pdfgen "https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/pdfgen"
click node_n_pdfbase "https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/pdfbase"
click node_n_platypus "https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/platypus"
click node_n_graphics "https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/graphics"
click node_n_canvas "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfgen/canvas.py"
click node_n_pdfdoc "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfbase/pdfdoc.py"
click node_n_pdfmetrics "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfbase/pdfmetrics.py"
click node_n_ttfonts "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfbase/ttfonts.py"
click node_n_doctemplate "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/platypus/doctemplate.py"
click node_n_flowables "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/platypus/flowables.py"
click node_n_shapes "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/graphics/shapes.py"
click node_n_renderers "https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/graphics/renderPDF.py"
click node_n_rl_accel "https://github.com/mattjmorrison/reportlab/blob/master/src/rl_addons/rl_accel/_rl_accel.c"
click node_n_renderpm_ext "https://github.com/mattjmorrison/reportlab/blob/master/src/rl_addons/renderPM/_renderPM.c"
click node_n_tests "https://github.com/mattjmorrison/reportlab/tree/master/tests"
click node_n_docs_tools "https://github.com/mattjmorrison/reportlab/tree/master/docs"

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_n_reportlab,node_n_lib,node_n_pdfgen,node_n_pdfbase,node_n_platypus,node_n_graphics,node_n_canvas,node_n_pdfdoc,node_n_pdfmetrics,node_n_ttfonts,node_n_doctemplate,node_n_flowables,node_n_shapes,node_n_renderers toneBlue
class node_n_rl_accel,node_n_renderpm_ext toneAmber
class node_n_tests,node_n_docs_tools toneMint
```

## Components

### Core library

Primary runtime package and shared utilities under src/reportlab.

- [reportlab](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab): Python package · Top-level runtime package for PDF generation and graphics. · `src/reportlab`
- [lib](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/lib): Shared utilities · Common helpers for colors, units, geometry, validation, styles, and configuration. · `src/reportlab/lib`
- [pdfgen](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/pdfgen): PDF emission · Low-level canvas and drawing layer that writes page content to PDF. · `src/reportlab/pdfgen`
- [pdfbase](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/pdfbase): PDF infrastructure · Fonts, encodings, document objects, metrics, and PDF file helpers. · `src/reportlab/pdfbase`
- [platypus](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/platypus): Layout engine · High-level document composition with flowables, frames, templates, and pagination. · `src/reportlab/platypus`
- [graphics](https://github.com/mattjmorrison/reportlab/tree/master/src/reportlab/graphics): Scene graph · Chart and shape model with reusable drawing primitives and widgets. · `src/reportlab/graphics`
- [canvas](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfgen/canvas.py): PDF canvas · Primary entry point for page-by-page PDF drawing. · `src/reportlab/pdfgen/canvas.py`
- [pdfdoc](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfbase/pdfdoc.py): PDF object model · Document and object serialization layer used to build PDF files. · `src/reportlab/pdfbase/pdfdoc.py`
- [pdfmetrics](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfbase/pdfmetrics.py): Font metrics · Font registration, measurement, and text metric services. · `src/reportlab/pdfbase/pdfmetrics.py`
- [ttfonts](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/pdfbase/ttfonts.py): TrueType fonts · TrueType font embedding and font-file handling. · `src/reportlab/pdfbase/ttfonts.py`
- [doctemplate](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/platypus/doctemplate.py): Pagination · Orchestrates flowables into frames and pages. · `src/reportlab/platypus/doctemplate.py`
- [flowables](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/platypus/flowables.py): Layout elements · Building blocks such as paragraphs, tables, images, and custom elements. · `src/reportlab/platypus/flowables.py`
- [shapes](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/graphics/shapes.py): Vector primitives · Core drawing primitives and scene-graph objects. · `src/reportlab/graphics/shapes.py`
- [renderers](https://github.com/mattjmorrison/reportlab/blob/master/src/reportlab/graphics/renderPDF.py): Export backends · PDF, PostScript, SVG, and bitmap exporters for graphics. · `src/reportlab/graphics/renderPDF.py`

### Native addons

Optional compiled acceleration and bitmap rendering extensions.

- [_rl_accel](https://github.com/mattjmorrison/reportlab/blob/master/src/rl_addons/rl_accel/_rl_accel.c): Python C accel · Optional speedups for hot paths such as parsing, text handling, and hyphenation. · `src/rl_addons/rl_accel/_rl_accel.c`
- [_renderPM](https://github.com/mattjmorrison/reportlab/blob/master/src/rl_addons/renderPM/_renderPM.c): Bitmap extension · Optional compiled rasterization backend for renderPM. · `src/rl_addons/renderPM/_renderPM.c`

### Support tooling

Tests, docs, demos, and ancillary tools around the core library.

- [tests](https://github.com/mattjmorrison/reportlab/tree/master/tests): Verification suite · Repository-wide tests spanning PDF generation, fonts, graphics, Platypus, and addons. · `tests`
- [docs/tools](https://github.com/mattjmorrison/reportlab/tree/master/docs): Docs and utilities · User guide, reference docs, demos, and ancillary generation tools. · `docs`

## Connections

- reportlab → lib: shared util · Core package depends on common utilities and configuration.
- reportlab → pdfgen: runtime · Public API exposes low-level PDF generation.
- reportlab → pdfbase: runtime · Public API exposes PDF infrastructure services.
- reportlab → platypus: runtime · Public API exposes structured document composition.
- reportlab → graphics: runtime · Public API exposes graphics and charting.
- pdfgen → canvas: entrypoint · Canvas is the main page emission interface.
- pdfgen → pdfbase: serialize · Canvas and drawing objects serialize through PDF base structures.
- pdfbase → pdfdoc: model · Document object model anchors PDF serialization.
- pdfbase → pdfmetrics: fonts · Metrics layer handles font lookup and measurement.
- pdfbase → ttfonts: embed · TrueType font support feeds the metrics and embedding path.
- platypus → doctemplate: paginate · Document template breaks flowables into pages and frames.
- platypus → flowables: compose · Flowables define the composable layout elements.
- platypus → pdfgen: emit · Paginated layouts are written through the PDF generation layer.
- graphics → shapes: model · Scene graph is built from drawing primitives and shapes.
- graphics → renderers: export · Graphics are exported through multiple backends.
- graphics → pdfbase: text/fonts · Charts and widgets rely on shared PDF font and encoding services.
- renderers → pdfgen: pdf · PDF renderer targets the core emission layer.
- renderers → _renderPM: bitmap path · Bitmap backend can use the optional compiled renderer.
- platypus → _rl_accel: speedup · Layout and parsing hot paths can use native acceleration.
- pdfbase → _rl_accel: speedup · Text parsing and font-related hot paths can use native acceleration.
- graphics → tests: verified by · Graphics behavior is exercised by the test suite.
- pdfbase → tests: verified by · Font, encoding, and PDF object behavior is covered by tests.
- platypus → tests: verified by · Layout and paragraph behavior is covered by tests.
- docs/tools → reportlab: explains · Docs and demos demonstrate the public package architecture and usage.
- docs/tools → graphics: examples · User guide and demos showcase graphics and chart APIs.
- docs/tools → platypus: examples · User guide and demos showcase Platypus layout APIs.
- tests → _rl_accel: covers · Test suite includes the optional acceleration modules.
