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

Uploaded CPython 3.9+Windows x86-64

pyfulgur-0.26.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.26.0-cp39-abi3-musllinux_1_2_aarch64.whl (7.3 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

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

Uploaded CPython 3.9+macOS 11.0+ ARM64

pyfulgur-0.26.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.26.0.tar.gz.

File metadata

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

File hashes

Hashes for pyfulgur-0.26.0.tar.gz
Algorithm Hash digest
SHA256 f0564851ca5643afe5c39ca2da5ff53878064c3c7d4b337971535808bb1bce54
MD5 6100fb26745a18d2a3bad4c0b324afad
BLAKE2b-256 4b89c29b0b3de88ae963741d65abfd6ae1942c1933fba0857254e0dcb105321f

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: pyfulgur-0.26.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.26.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 fb534f550a9da74e31f00ef272a6842e65b16e23b981e67958fc2905bdd54a67
MD5 e63dc9bcaef39c58e53a8f008c63b355
BLAKE2b-256 47f0aec01a2d9a449a4af734d61a195eee9b66466a5f2e3cf5ae8ed11d06ea3c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.26.0-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 ab801483944e8019ce19738ffb998ff5d13c25ee9e10e97f080c6bfe639916f6
MD5 4ec0c492ce5803b851fac7b5ac688113
BLAKE2b-256 95d72bb24c0cfb34c0fcd7f755db323897ae08cce311e6335a6348cd52e90e21

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.26.0-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 7e062ccb98839282a65c1367c46012ff64d3c594bc3947723c5936855f08d2b5
MD5 07381db475e23761083ef78eee1a6f08
BLAKE2b-256 82b4f7203dff0fda0e528f03987f7d1735b04141ac8c6341a875695bdbacc341

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.26.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 dde92852153428987287c5a130ed849042811ad248ee695235906e03124fef41
MD5 a27a91ea729d505d479bea0c40939cda
BLAKE2b-256 81a8e85ac17ee2d273baedbb62e39bda629c8209c1aac3d0b6003f89815c9254

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.26.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8b8213147742e1643167bad472dc9d7348737fdb9e0c2b0205f9cfb7457c7a93
MD5 46f41219e95a3ec13e542a5aadd14826
BLAKE2b-256 3a68bf5d56aac1b76d763d7159dea04606215e10e7f24d5adff0c0b200df726b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.26.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0b7ded5b5845a79ab71fe4d811934c52c342ce44632fbe7b7b74525fe006f8d9
MD5 c90fb60f602248dc5e3a7b8db0998807
BLAKE2b-256 1831d3f5e624aacbf6c74c2fb8696cf5360fc57cda3259f861817360477bb5e1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.26.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 850abefa13fbb8249883e0820f2f81b1bad1b99fe42969a3f7f00a81c4cc4c8a
MD5 87fa2511d7e40c406b5a2072300bee9d
BLAKE2b-256 cb407baec6abe5888e02fa9c0daa5c1e27d827288ff5638fb6fb306aed342fbf

See more details on using hashes here.

Provenance

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