Metadata-Version: 2.1
Name: pypst
Version: 0.7.0
Summary: Declarative Typst in Python with Pandas data frame support.
Home-page: https://github.com/tilman151/pypst
Author: Tilman Krokotsch
Author-email: tilman@krokotsch.eu
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Provides-Extra: pandas
Requires-Dist: frozendict (>=2.4.4,<3.0.0)
Requires-Dist: frozenlist (>=1.4.1,<2.0.0)
Requires-Dist: pandas (>=2.2.2,<3.0.0) ; extra == "pandas"
Project-URL: Repository, https://github.com/tilman151/pypst
Description-Content-Type: text/markdown

# Pypst

Declarative Typst in Python with Pandas data frame support.

Pypst helps you dynamically generate [Typst](https://typst.app) 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](https://github.com/typst/typst/releases) to do so in the command line or install the [Typst Python package](https://pypi.org/project/typst/).

![Example script and output](docs/examples/example.png)

## Installation

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

```bash
pip install pypst
```

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

```bash
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.

```pycon
>>> 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.

```pycon
>>> 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.

```pycon
>>> 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](https://krokotsch.eu/pypst) contains more extensive tutorials on generating [documents](https://krokotsch.eu/pypst/usage) and generating [tables from Pandas data frames](https://krokotsch.eu/pypst/pandas).

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

- [x] 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
- [x] 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.

