๐ท pdfjeยถ
pdfยทje [๐ PDFยทyuh] (noun) Dutch for โsmall PDFโ
Write beautiful PDFs in declarative Python.
(Currently in active development. Leave a โญ๏ธ on GitHub if youโre interested how this develops!)
Featuresยถ
What makes pdfje stand out from the other PDF writers? Here are some of the highlights:
๐งฉ Declarative APIยถ
In most PDF writers, you create empty objects and
then mutate them with methods like addText()
,
all while changing the state with methods like setFont()
.
Pdfje is different. You describe the document you want to write,
and pdfje takes care of the details. No state to manage, no mutations.
This makes your code easier to reuse and reason about.
from pdfje import Document
Document("Olรก Mundo!").write("hello.pdf")
See the tutorial for a complete overview of features, including:
Styling text including font, size, and color
Automatic layout of text into one or more columns
Builtin and embedded fonts
Drawing basic shapes
See the roadmap for supported features.
๐ Decent typographyยถ
Legibility counts. Good typography is a key part of that. Pdfje supports several features to make your documents look great:
Visually pleasing linebreaks, using the same basic principles as LaTeX
Automatic kerning using available font metrics
Avoiding widows and orphans by moving lines between columns or pages.
๐ Small footprintยถ
The PDF format supports many features, but most of the time you only need a few. Why install many dependencies โ just to write a simple document? Not only is pdfje pure-Python, it allows you to install only the dependencies you need.
pip install pdfje # no dependencies
pip install pdfje[fonts, hyphens] # embedded fonts and improved hyphenation
Roadmapยถ
Pdfje is still in active development, so it is not yet feature-complete. Until the 1.0 version, the API may change with minor releases.
Features:
โ = implemented, ๐ง = planned, โ = not planned
- Typesetting
โ Automatic kerning
โ Wrapping text into lines, columns, and pages
โ Page sizes
โ Centering text
โ Justification
โ Hyphenation
โ Move lines between columns/pages to avoid widows/orphans
โ Tex-style line breaking
๐ง Headings (which stick to their paragraphs)
๐ง Indentation
๐ง Keeping layout elements together
๐ง Loosening paragraphs to avoid orphans/widows
๐ง Broader unicode support in text wrapping
- Drawing operations
โ Lines
โ Rectangles
โ Circles, ellipses
๐ง Arbitrary paths, fills, and strokes
- Text styling
โ Font and size
โ Embedded fonts
โ Colors
โ Bold, italic
๐ง Underline and strikethrough
๐ง Superscript and subscript
โ Complex fill patterns
๐ง Images
๐ง Bookmarks and links
๐ง Tables
๐ง Bullet/numbered lists
๐ง Inline markup with Markdown (Commonmark/MyST)
โ Emoji
โ Tables of contents
โ Forms
โ Annotations
Versioning and compatibility policyยถ
Pdfje follows semantic versioning. Until the 1.0 version, the API may change with minor releases. Breaking changes will be announced in the changelog. Since the API is fully typed, your typechecker and/or IDE will help you adjust to any API changes.
Licenseยถ
This library is licensed under the terms of the MIT license.
It also includes short scripts from other projects (see pdfje/vendor
),
which are either also MIT licensed, or in the public domain.
Contributingยถ
Here are some useful tips for developing in the pdfje
codebase itself:
Install dependencies with
poetry install
.To write output files during tests, use
pytest --output-path=<outpur-dir>
To also run more comprehensive but โslowโ tests, use
pytest --runslow
Acknowledgementsยถ
pdfje is inspired by the following projects. If youโre looking for a PDF writer, you may want to check them out as well: