Pypst

Declarative Typst in Python with Pandas data frame support.

Pypst helps you dynamically generate Typst code directly in Python. No manual string manipulation required. It has two major use cases:

• Generating full Typst documents to be rendered as PDFs
• Generating and styling Typst tables from Pandas data frames to be included in another Typst document

Pypst produces human-readable Typst code that you can modify and extend. It will not compile Typst code for you, but you can either use the Typst compiler to do so in the command line or install the Typst Python package.

Installation

Pypst is available on PyPI and can be installed via pip.

pip install pypst

To use the table functionality, pandas is needed. Install Pypsts like this instead:

pip install pypst[pandas]

Usage

Pypst contains classes that represent Typst elements. You can create a Typst document by instantiating these classes and nesting them as needed.

>>> import pypst
>>> heading = pypst.Heading("My Heading", level=1)
>>> itemize = pypst.Itemize(["First item", "Second item", "Third item"])

Each of these classes has a render method that returns the Typst code as a string.

>>> print(heading.render())
= My Heading
>>> print(itemize.render())
- First item
- Second item
- Third item

If you want to combine multiple elements into a single document, you can use the Document class. You can even add imports for other Typst files or packages.

>>> document = pypst.Document([heading, itemize])
>>> document.add_import("utils.typ")
>>> print(document.render())
#import "utils.typ"
<BLANKLINE>
= My Heading
<BLANKLINE>
- First item
- Second item
- Third item

The output of the render method can be written to a .typ file for compilation. The documentation contains more extensive tutorials on generating documents and generating tables from Pandas data frames.

Limitations

Pypst is not a Typst compiler. It doesn't check for syntax errors or compile Typst code into PDFs. Pypst interprets any string as a Typst literal, so stroke = "1pt" will be rendered as stroke: 1pt. If you want to pass a string literal, you need to wrap it in quotes, for example, caption = '"My Caption"'. When Pypst encounters a string wrapped in quotes without need, it will automatically remove them. For a content block, you can wrap the string in brackets instead, for example, caption = "[My content]".

Roadmap

If there is time and people are interested, I would like to add the following features:

• Complete table attributes (for example, fill is missing)
• Support automatic formating for common workflows, like automatically merging multi-level columns with mean and standard deviation
• Add more Typst elements (like headings or lists) to make building more complex documents easier

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.