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.35.0.tar.gz (944.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.35.0-cp39-abi3-win_amd64.whl (7.3 MB view details)

Uploaded CPython 3.9+Windows x86-64

pyfulgur-0.35.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.35.0-cp39-abi3-musllinux_1_2_aarch64.whl (7.2 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

pyfulgur-0.35.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.5 MB view details)

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

pyfulgur-0.35.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.35.0-cp39-abi3-macosx_11_0_arm64.whl (6.8 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

pyfulgur-0.35.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.35.0.tar.gz.

File metadata

  • Download URL: pyfulgur-0.35.0.tar.gz
  • Upload date:
  • Size: 944.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.35.0.tar.gz
Algorithm Hash digest
SHA256 1460de56d7df4d7d986aabb4a424b57ca9b1f7584577f693791f0e9adc516abf
MD5 81774ed070a84e1595ca1f58c9908447
BLAKE2b-256 174a06950745e77b40070f7393029857c077b372f3f7823c77c424a28d63ae99

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: pyfulgur-0.35.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.35.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0751608566fcd127323fa6e0bb977a2db5a9c4bb4cee52f2b9827fb137f90925
MD5 d2743fe3a81c08d6927951b7089d766f
BLAKE2b-256 76a62fea811b40a4d1160a38044561cad73e360c8dd451bc7426b69eeadb9c45

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.35.0-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 9e6534d9b0a930663005b435902755e15564b17a6df784793ce4d1f9b78f7515
MD5 3eddc411708e2eb684ac8ca4fba9e8a0
BLAKE2b-256 1e946423705a03e43c7cea71c0b08e389ebdb2c38d9f0b5e95a348d065ac7d8b

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.35.0-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 cf79f09d90de3415d163e664c6a36ba80154f8f1455b8d73a45368842a7b3bca
MD5 84ad23db5d670bf295f26b6901aaaf4f
BLAKE2b-256 c77c667eac8dc5d5ce73e1eaa5672bc6c2c13487b41fb374e62066753895053c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.35.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b8e29d83bd82b47052dbcbb4d9df17f76aa313f01b7f581255ed5f2beddc9d50
MD5 6ab0a6095c41758d3a37b8518813603a
BLAKE2b-256 665e366599b62e3403e9afe776b9422ad3220c6a8c3a57fb5f593a3e31596ddc

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.35.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 a67132033633959b8d27440bc3a5f8962904dc634abe4b3fba3d4c5df84aa6a7
MD5 77b7c2799aae301905c90ca3616d9345
BLAKE2b-256 de3209506bda733fd0fafba6586cab42307e4669299334d6caa7d77e9015fc5e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.35.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 85b29d76f078a9190374dca1b6bb4cc94396f87f3700b1ef8c57c5eb868d2f6e
MD5 714efbfb7789e2ad8e38550d797ffb32
BLAKE2b-256 6a7dc76efca3f31ac4f9e14e4c7cc926974cca847d43544f0c504a1ac296dc27

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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.35.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pyfulgur-0.35.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ecfb848c3a990f313d3d98c5df19b3c25c8e3364b1417764363385d87f812d61
MD5 25c1a042361e3a35ca0e2d5b83f9ad16
BLAKE2b-256 e6a3750a207d84a6db2920c70eda213d5c6163dd9257e871aefade5ba5eb0059

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyfulgur-0.35.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