Skip to main content

Write beautiful PDFs in declarative Python

Project description

https://img.shields.io/pypi/v/pdfje.svg?style=flat-square&color=blue https://img.shields.io/pypi/pyversions/pdfje.svg?style=flat-square https://img.shields.io/pypi/l/pdfje.svg?style=flat-square&color=blue https://img.shields.io/badge/mypy-strict-forestgreen?style=flat-square https://img.shields.io/badge/coverage-99%25-forestgreen?style=flat-square https://img.shields.io/github/actions/workflow/status/ariebovenberg/pdfje/tests.yml?branch=main&style=flat-square https://img.shields.io/readthedocs/pdfje.svg?style=flat-square

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:

Sample document with two columns of text

🎈 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:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pdfje-0.6.1.tar.gz (111.5 kB view hashes)

Uploaded source

Built Distribution

pdfje-0.6.1-py3-none-any.whl (124.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page