pd4ml — PD4ML for Python

HTML and CSS to PDF, PDF/A, PDF/UA, ZUGFeRD/Factur-X, DOCX, RTF and page images, with the full public PD4ML API (Java package com.pd4ml) available to Python applications.

PD4ML runs in a Java virtual machine inside the Python process, through JPype. Every public Java class, method, constant and enum can be used directly, and the module adds Python I/O (paths, bytes, file objects) on top. New converters use PD4ML's v42 layout engine by default.

pip install pd4ml

import pd4ml

pd = pd4ml.PD4ML()                                   # v42 layout engine
pd.setPageSize(pd4ml.PageSize.A4)
pd.setPageMargins(pd4ml.PageMargins(15, 15, 15, 15, pd4ml.Units.MM))
pd.readHTML("invoice.html")                          # a path, URL, bytes or file object
pd.writePDF("invoice.pdf", pd4ml.PdfSpec.PDFA_3B)    # a path or file object; no target: bytes

The first use downloads the most recent PD4ML build (see Installation below).

Requirements

• Python 3.9 or later.
• Java 8 or later: a JDK or JRE of the same bitness as Python; 17 or 21 is recommended. JPype finds it through JAVA_HOME or the system's default Java. To use a specific JVM library (jvm.dll, libjvm.so), set PD4ML_JVM.

Installation

pip install pd4ml

The package contains the Python module only. The PD4ML library itself comes from the PD4ML Maven repository (https://pd4ml.com/maven2):

• Automatically. If no PD4ML build is installed or configured, the first use of PD4ML downloads the most recent 4.x release. Bouncy Castle (for encryption and signing) comes along from Maven Central. Every file is verified against its published SHA-1 checksum and stored in a per-user cache directory: %LOCALAPPDATA%\pd4ml-python on Windows, ~/.cache/pd4ml-python elsewhere, or PD4ML_HOME. A notice on standard error reports the download.

• Ahead of time, which is better for servers and container images:

  pd4ml install                       # the most recent 4.x release (also: python -m pd4ml install)
  

  Run it again to update to a newer release. From Python, call pd4ml.install().

PD4ML_AUTO_INSTALL=0 turns the automatic download off; the module then raises pd4ml.ClasspathError until a build is installed or configured.

Other PD4ML builds. The module takes PD4ML from the first of these that is set:

1. pd4ml.start(classpath=[...]), called before first use;
2. PD4ML_CLASSPATH: jars and class directories separated by ; on Windows and : elsewhere, with dir/* for all jars of a directory;
3. PD4ML_CLASSPATH_FILE: a file with one entry per line;
4. the build pd4ml install downloaded.

The v42 layout engine is new in PD4ML 4.2. With an earlier build, such as the published 4.1.x, a converter uses that build's own engine and warns once. pd4ml.has_layout_engines() tells which kind of build is loaded.

API

The Java API

All public classes of com.pd4ml are module attributes under their own names:

Methods keep their Java names and take Python values:

• str, int, float, bool;
• bytes for byte[];
• None for null.

Java null results become None, and Java strings become str. Any other Java class is available through pd4ml.java_class("java.util.HashMap").

Java exceptions are Python exceptions; catch them by their class:

try:
    pd.readHTML("missing.html")
    pd.writePDF("out.pdf")
except pd4ml.java_class("java.io.IOException") as e:
    print("conversion failed:", e)

pd4ml.PD4ML

PD4ML(*args, engine="v42", html_width=None) creates a com.pd4ml.PD4ML, passing *args to the Java constructor: nothing, a license key, or an HTML width. It then selects the layout engine: engine="v40" for the previous engine, engine=None for the Java default.

Every Java method is available. These also accept Python I/O:

Static members of the Java class are on the wrapper class: pd4ml.PD4ML.getVersion(), pd4ml.PD4ML.disableBatik = True. The underlying Java object is pd.java.

Helpers

• pd4ml.html_to_pdf(source, target=None, *, base_url, page_size, page_margins, spec, engine, html_width)
• pd4ml.open_pdf(source, password=None): a PdfDocument from a path, URL, bytes or file
• pd4ml.write_pdf(document, target=None, password=None, permissions=None)
• pd4ml.merge_pdfs(first, second, target=None)
• pd4ml.pdf_spec(keyword): the PdfSpec for a keyword; unknown keywords raise ValueError
• pd4ml.progress_listener(callback): a Java ProgressListener for a callable
• pd4ml.version(), pd4ml.start(...), pd4ml.is_started(), pd4ml.java_class(name)
• pd4ml.install(...), pd4ml.installed_jar(), pd4ml.installed_version(), pd4ml.has_layout_engines()

The JVM starts on the first use of PD4ML. To pass JVM options, call pd4ml.start(jvm_options=["-Xmx2g"]) first, or set PD4ML_JVM_OPTIONS. The JVM runs headless, and it can be started only once per process.

Limitations

• ResourceProvider and CustomTag are Java classes to extend. Write those in Java and register them by class name (addCustomResourceProvider) or instance. Python can implement only Java interfaces, such as ProgressListener.
• As of PD4ML 4.2.0, the v42 layout engine reports only DOC_WRITE_BEGIN to a ProgressListener; v40 reports every stage.

Documentation

• User guide: docs/guide.md in the source distribution (pip download --no-binary :all: pd4ml). It covers prerequisites, installation, use cases with code, tips and troubleshooting.
• The PD4ML manual: https://pd4ml.com/docs/.
• Usage examples: https://pd4ml.com/docs/usage-examples.html.
• Licensing: without a license, PD4ML runs in evaluation mode and watermarks its output. See https://pd4ml.com/docs/#3.-licensing.

Development

These steps need the source distribution or repository.

pip install -e ".[test]"
python tools/pd4ml_classpath.py <pd4ml maven project>    # writes ./pd4ml.classpath (optional)
python -m pytest

• Tests use ./pd4ml.classpath (or PD4ML_CLASSPATH/PD4ML_CLASSPATH_FILE), and are skipped without one. PD4ML_NETWORK_TESTS=1 adds tests that download the latest release, both explicitly and through the automatic first-use download.
• Type stubs: src/pd4ml/__init__.pyi declares the whole API for IDEs and type checkers. After an API change, regenerate it with python tools/gen_stubs.py.
• Releases to PyPI are described in docs/releasing.md.
• Example: python examples/convert.py page.html page.pdf --pdfa pdf/a-2b.