How mattjmorrison/reportlab works
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: pdfbase pdfbase · platypus platypus · reportlab reportlab · graphics graphics
Components 18
Core library
Primary runtime package and shared utilities under src/reportlab.
- reportlab · Top-level runtime package for PDF generation and graphics.
src/reportlab - lib · Common helpers for colors, units, geometry, validation, styles, and configuration.
src/reportlab/lib - pdfgen · Low-level canvas and drawing layer that writes page content to PDF.
src/reportlab/pdfgen - pdfbase · Fonts, encodings, document objects, metrics, and PDF file helpers.
src/reportlab/pdfbase - platypus · High-level document composition with flowables, frames, templates, and pagination.
src/reportlab/platypus - graphics · Chart and shape model with reusable drawing primitives and widgets.
src/reportlab/graphics - canvas · Primary entry point for page-by-page PDF drawing.
src/reportlab/pdfgen/canvas.py - pdfdoc · Document and object serialization layer used to build PDF files.
src/reportlab/pdfbase/pdfdoc.py - pdfmetrics · Font registration, measurement, and text metric services.
src/reportlab/pdfbase/pdfmetrics.py - ttfonts · TrueType font embedding and font-file handling.
src/reportlab/pdfbase/ttfonts.py - doctemplate · Orchestrates flowables into frames and pages.
src/reportlab/platypus/doctemplate.py - flowables · Building blocks such as paragraphs, tables, images, and custom elements.
src/reportlab/platypus/flowables.py - shapes · Core drawing primitives and scene-graph objects.
src/reportlab/graphics/shapes.py - renderers · PDF, PostScript, SVG, and bitmap exporters for graphics.
src/reportlab/graphics/renderPDF.py
Native addons
Optional compiled acceleration and bitmap rendering extensions.
Support tooling
Tests, docs, demos, and ancillary tools around the core library.
- tests · Repository-wide tests spanning PDF generation, fonts, graphics, Platypus, and addons.
tests - docs/tools · User guide, reference docs, demos, and ancillary generation tools.
docs
Connections 27
- 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.