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

Uploaded CPython 3.9+Windows x86-64

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

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

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

Uploaded CPython 3.9+macOS 11.0+ ARM64

pyfulgur-0.20.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.20.0.tar.gz.

File metadata

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

File hashes

Hashes for pyfulgur-0.20.0.tar.gz
Algorithm Hash digest
SHA256 4cb774aabe7098d2990c0042562b051352a31b1aeef504595550b0c3ee83cbe7
MD5 9686ce442c1358c879a32be89dd98990
BLAKE2b-256 4e68786b00f16b9de7e7409d4be05037691465e882be415a39e41c560b316b50

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: pyfulgur-0.20.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.20.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 08dc8e75e969a59e16b30ff775723ddfdbae22b4732725f10e775857ef164ce8
MD5 8f57370c2d2eb78322e1b42285ec2fe1
BLAKE2b-256 3eb7d0954775157a1be176a50ec0df28265aed7749f5f421fccd5bb65b7f5bba

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.20.0-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4ba32fbf383cf1588fde36a9190d63bb5d47ae3166167769f4696e254237c498
MD5 47d82cf91ce354e6e3da5cbfe5a57c5c
BLAKE2b-256 3dcb6ab7834936d1cf77584b03a8a4d59af39b072cc4be6a82cb1b05e2bf6e07

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.20.0-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 c5799728f475fea6a068ab0ecc122cb82fd10d2417ecb81514289c9ebdc33e86
MD5 e6ff405ed60ca370fb765f7af07a014b
BLAKE2b-256 f48db46d20e282b6c244b7978c15fc464843b8cc7f936cfa17b84e96369038f4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.20.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6fb4cb3d7ba7c393b74eb1a1034e53400230c40f6c80f0243180775993ea38e7
MD5 db36391f486ca7d6918d67224a1c8daf
BLAKE2b-256 6313efe1e64c54c41eef36d364a26ea9c0d0e79cbe30af99b621c3da45a9a4a2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.20.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 1ed0a6b8dcf37d58ae7821cfb23327759c3662ad6781552104a591b1f127a3aa
MD5 f2a5e3adc533fa73dae65df5b58990b7
BLAKE2b-256 986131311343a0489bbf1622f631602d285fa7450a84d4fb89554b42d0bd5608

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.20.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 07deea337d06da4e3d8fb9685fd15a4c12afbce6bc424ffcce202e1cc5ccd664
MD5 826299de9dbbb90bf0670b38cf0ef076
BLAKE2b-256 0d1c64dfb8f88244efc59ae17a58dd6f8e5797a192c38867b3822fe853228530

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for pyfulgur-0.20.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 53f5d1a5e4ec2d95349ed53789313974a9eece1b3f63c5b0b8555026201da8b5
MD5 439f2f29f5a85f83e7dcab4d377af214
BLAKE2b-256 c15e357e83bd4a5ea770a4df6947945a635898e76f07b9b3055a84c45c3314e5

See more details on using hashes here.

Provenance

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