typst-py

typst-py is a PyO3-based Python binding to Typst, the Rust-built markup typesetting system, letting Python code compile .typ source directly into PDF, SVG, PNG, or HTML without shelling out to the Typst CLI. It exposes both simple free functions (typst.compile, typst.query, typst.eval) for one-off use and a reusable Compiler class that keeps fonts and package caches warm across repeated compiles.

Beyond basic file-to-file compilation, it supports in-memory multi-file projects (a dict of filenames to bytes/paths), structured sys_inputs for passing data into documents, reproducible output via fixed creation timestamps, PDF/A and PDF/UA standard export, and structured TypstError/TypstWarning exceptions carrying hints and trace information instead of opaque compiler output. Wheels are published for a wide range of platforms and architectures, including free-threaded Python builds.

What You Get

• A typst.compile() free function that turns a .typ file path or in-memory bytes into PDF, SVG, PNG, or HTML output in one call.
• A Compiler class that reuses fonts, package caches, and world state across multiple compilations for better performance in long-running processes.
• Support for compiling multi-file Typst projects from a dictionary of filenames to content, useful when Typst sources are bundled as Python package resources.
• Structured TypstError and TypstWarning exceptions exposing message, hints, trace, and diagnostic attributes instead of raw stderr text.
• query() and eval() entry points for extracting structured data (JSON/YAML) out of compiled Typst documents.
• Reproducible-build support via fixed creation timestamps, and PDF/A and PDF/UA standards export.

Common Use Cases

• Generating invoices, reports, or certificates as PDFs from a Python backend without shelling out to LaTeX or a headless browser.
• Rendering Typst templates to SVG/PNG for previews in a web application or documentation pipeline.
• Extracting structured metadata (e.g. custom <note> markers) from compiled documents via typst.query.
• Batch-compiling multi-page or multi-file Typst projects packaged inside a Python library’s resources.

Under The Hood

Architecture The crate binds Rust’s typst compiler ecosystem into Python via PyO3, centered on SystemWorld (src/world.rs), which implements typst’s World trait (source, file, font, today) backed by a mutex-guarded hash map of lazily-loaded FileSlots for source files and packages. Compiler (src/lib.rs) wires user input — a path, raw bytes, or a multi-file dict — into that World before invoking the typst-pdf/typst-svg/typst-render/typst-html backends, and translates typst’s SourceDiagnostics into structured TypstError/TypstWarning PyO3 exceptions carrying hints and trace context. The free functions (compile, query, eval) are thin wrappers that construct a fresh Compiler per call, while the class form lets callers reuse font/package state across repeated compilations.

Tech Stack Built with Rust and PyO3 0.29 (abi3-py38, gil_used = false for free-threaded Python builds), packaged via the maturin build backend into a _typst native extension imported by a thin, fully-typed Python shim (python/typst/__init__.py plus a .pyi stub). It depends directly on the typst 0.15.1 workspace crates (typst, typst-kit, typst-pdf, typst-svg, typst-render, typst-eval, typst-html, typst-layout) alongside chrono, rayon, serde/serde_json/serde_yaml, ecow, and comemo. CI (maturin-generated GitHub Actions) builds manylinux, musllinux, Windows, and macOS wheels across a wide set of architectures, including free-threaded interpreter builds.

Code Quality pytest-based tests cover PDF/PNG/SVG/HTML compilation, reproducible-timestamp behavior, multi-file project compilation, query/eval extraction, and font enumeration. Error handling on the Rust side favors typed, structured exceptions over swallowed diagnostics — TypstError/TypstWarning carry hints and trace data rather than a flat error string. There is no separate lint/clippy gate visible beyond the build-and-test CI workflow, and inline comment density in the Rust source is moderate rather than extensive.

API Design The public surface stays low-friction for the common case — typst.compile(path) — while layering on advanced control for demanding callers: a reusable Compiler to avoid re-initializing fonts and packages, an in-memory multi-file input format, a tri-state sys_inputs parameter (keep/clear/set) across repeated compiles, reproducible timestamps, and PDF/A/UA standard selection. Full typed stubs (__init__.pyi, py.typed) give editors and type checkers complete signatures with no runtime dependencies of their own.