Skip to main content

Python bindings for fulgur — offline HTML/CSS to PDF conversion

Project description

pyfulgur

Python bindings for fulgur — an offline, deterministic HTML/CSS to PDF conversion library written in Rust.

Status

Alpha (v0.0.2). Core Engine / AssetBundle / PageSize / Margin / render_html API is available. Batch rendering, sandboxing, and template engine wiring are planned for later releases.

Install

Note: v0.0.2 is an early alpha. Pre-built wheels are not yet published to PyPI; install from source for now.

# From a checkout of the fulgur repository
pip install maturin
maturin develop --release -m crates/pyfulgur/Cargo.toml

Pre-built wheels for manylinux / macOS / Windows will be published in a later release.

Quick start

from pyfulgur import AssetBundle, Engine, PageSize

bundle = AssetBundle()
bundle.add_css("body { font-family: sans-serif; }")

engine = Engine(page_size=PageSize.A4, assets=bundle)
pdf_bytes = engine.render_html("<h1>Hello, world!</h1>")

with open("output.pdf", "wb") as f:
    f.write(pdf_bytes)

Builder style:

engine = (
    Engine.builder()
    .page_size(PageSize.A4)
    .landscape(False)
    .title("My doc")
    .assets(bundle)
    .build()
)
engine.render_html_to_file("<h1>Hi</h1>", "out.pdf")

API surface

  • Engine(**kwargs) / Engine.builder()EngineBuilder
  • Engine.render_html(html: str) -> bytes — render to PDF bytes (releases the GIL)
  • Engine.render_html_to_file(html: str, path: str | os.PathLike) -> None — render to a file
  • AssetBundle: add_css, add_css_file, add_font_file, add_image, add_image_file
  • PageSize: A4, LETTER, A3, custom(w_mm, h_mm), .landscape()
  • Margin: Margin(top, right, bottom, left), Margin.uniform(pt), Margin.symmetric(v, h), Margin.uniform_mm(mm)
  • Exceptions: FileNotFoundError, ValueError, pyfulgur.RenderError

Type stubs

pyfulgur ships PEP 561 type stubs (py.typed + __init__.pyi) so mypy, pyright, and IDEs can type-check call sites against the native API. Docstrings live in the Rust source and are exposed via __doc__ for help(), Jupyter ?, and griffe / mkdocstrings inspection.

Known limitation: blitz parse-error noise on stdout

The underlying blitz-dom parser writes non-fatal html5ever parse errors directly to the process's stdout via println!. These fire for browser-tolerated but technically invalid HTML — documents without a <!DOCTYPE>, missing <html>/<body> wrappers, or structural quirks that browsers silently auto-correct — and show up as ERROR: ... noise in Jupyter notebooks or any environment that captures stdout. The PDF bytes returned by render_html are not affected; only the caller's terminal is polluted.

pyfulgur intentionally does not redirect fd 1 from inside the binding: process-wide fd manipulation in a multi-threaded library context races with concurrent render_html calls from other threads (mixed suppress / non-suppress callers would silently lose stdout during a suppressed window). Correctness and parallelism take priority over cosmetic stdout cleanliness.

If you need clean stdout:

  • Redirect at the caller side with a Python contextlib.redirect_stdout for Python-level writes, or os.dup2 for fd-level writes. This keeps the fd manipulation scoped to your own call site where you can guarantee single-threaded use.
  • Run renders in a subprocess via multiprocessing (each worker has its own fd 1).
  • Use the fulgur CLI (which handles stdout isolation internally) invoked via subprocess.run when cold-start cost is acceptable.

A wrapper-style Python package that shells out to the fulgur CLI (clean stdout, parallel via process isolation, no native build required) is on the roadmap as a complement to this native binding.

Links

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

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

pyfulgur-0.24.0.tar.gz (902.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pyfulgur-0.24.0-cp39-abi3-win_amd64.whl (7.3 MB view details)

Uploaded CPython 3.9+Windows x86-64

pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_x86_64.whl (7.7 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ x86-64

pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_aarch64.whl (7.3 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.6 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (7.1 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

pyfulgur-0.24.0-cp39-abi3-macosx_11_0_arm64.whl (6.8 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

pyfulgur-0.24.0-cp39-abi3-macosx_10_12_x86_64.whl (7.1 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file pyfulgur-0.24.0.tar.gz.

File metadata

  • Download URL: pyfulgur-0.24.0.tar.gz
  • Upload date:
  • Size: 902.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for pyfulgur-0.24.0.tar.gz
Algorithm Hash digest
SHA256 17733c527c0f33a5349f54e76b90fb47a87f05358da9d0ce05f0a4d35a23c0e5
MD5 e678def0b72c288e2e7b51c274a6f11d
BLAKE2b-256 197fdc01c9d3f8b5af5532ca6a884a78045962dbda14a704a6995db112dfb370

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0.tar.gz:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: pyfulgur-0.24.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 7.3 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2426886fa85cd175f3ca489b6dfbb25ead1343f60a2a96038630e0846a3c5f15
MD5 02f94630d71a84069d917b7ac70f89db
BLAKE2b-256 76670791dc0bc6e7f361fed28dea5225381a84395a765e6c548afdc09c7d71e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-win_amd64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 40ae4dc0c1d1c9efd971aa44e7235a5d5931b60622a6bc7f698887c0aec26adb
MD5 b8654a48ac7c7cd758ad81149ab1c743
BLAKE2b-256 395e10402069fa096f7cbef42e9e78d34801f8fa55871dc99a5631d77d42986b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_x86_64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 5811ad3d8908ecc0e9708317be42b32055b27ff7ab69667cf18be90a85853a7a
MD5 4d913e4aa82652918694affb23b3ed66
BLAKE2b-256 6bee5082a0749ed21d74b07ef3a14e572b7c293612c47d2dc9fe12f45d23f131

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-musllinux_1_2_aarch64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2fdd668077818bef3e81d45f3f9efd83ef36780f1b131e61926b7af3d9786cc2
MD5 e2346b07b2fec738888e5c2b70ae145c
BLAKE2b-256 ef78b2eecb04db06470157460a3430a121b642de1449d52a697d314146fb4b9b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d3f241580594c60ce9a7644b69d38203d40209416d79647fe45dfbd6c4d958c9
MD5 4ebf0a5ff1488bfe2611a5e73f3dfb51
BLAKE2b-256 548bd34532e7a377b8303a010ab35e8f0f55b94111867a6f1553386751f99664

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 661226e4caafa43f004dbc957eaf631e65261f6381b097adb940cfc9d293e6a2
MD5 2c22d1c8226aa930e14320dc8eb62782
BLAKE2b-256 dbddae3ca2a0d443ff5011651c8ff7767eb28a79ac6352c9478272dd4fbae65b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyfulgur-0.24.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.24.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 cfe0d00cfbe721c9ad318c0b59a54f787dab66077dc540477584cab1302d9514
MD5 789b1715b4e7abb23830ce20cc8b1f44
BLAKE2b-256 760dc07978ad431f3088451f13ea23c583057c3355fd10f86785cfebc26d8a2e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.24.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release-python.yml on fulgur-rs/fulgur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

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