Python API

The main function of xhtml2pdf is CreatePDF().

xhtml2pdf.pisa.CreatePDF(src, dest=None, dest_bytes=False, path='', link_callback=None, debug=0, default_css=None, xhtml=False, encoding=None, xml_output=None, raise_exception=True, capacity=100 * 1024, context_meta=None, encrypt=None, signature=None, show_error_as_pdf=False, resource_policy=None)

Create PDF.

Parameters:

• src (str|io.BufferedIOBase) – The source to be parsed.

• dest (io.BufferedIOBase) – The destination for the resulting PDF. This has to be a file object which will not be closed afterwards.

• dest_bytes (bool) – If true, will return the data written to the file.

• path (str) – The original file path or URL. This is needed to calculate the relative paths of images and stylesheets.

• link_callback (Callable[str|pathlib.Path|None, str|None]) – Handler for special file paths (see below).

• debug (int) –

  deprecated:

  does nothing; set the level of the xhtml2pdf logger instead. Any other unknown argument is now named in a DeprecationWarning rather than being ignored.

• default_css (str) – The default CSS definition. If None, the predefined CSS of xhtml2pdf is used.

• xhtml (bool) –

  Force parsing the source as HTML. If omitted, the parser will try to guess this.

  deprecated:

  XHTML parsing will be removed in v0.2.8

• encoding (str) – The source encoding. If omitted, this will be guessed by the HTML5 parser. This is helpful if the HTML file does not have <meta charset>.

• xml_output (io.BufferedIOBase) – If given, the XML output of the document tree (not the document itself!) will be written to this file/buffer.

• raise_exception (bool) – Whether a failed conversion raises. If false, the exception is logged and the context is returned with err set.

• capacity (int) – The capacity of the internal buffer, in bytes. If the document is bigger than the buffer, it will be managed in a temporary file rather than in-memory

• context_meta (dict[str, str | tuple[float, float]]) – Metadata for the PDF document. May include fields: author, title, subject, keywords, and pagesize.

• encrypt (str|reportlab.lib.pdfencrypt.StandardEncryption) – Either a password to protect the PDF with or a pre-built instance of encryption parameters.

• signature (dict[str, Any]) – Signature parameters. Should contain at least engine with the values of "pkcs12", "pkcs11", or "simple". Cannot be combined with encrypt.

• show_error_as_pdf (bool) – If true, a failed conversion produces a PDF listing the errors and the warnings instead of raising.

• resource_policy (xhtml2pdf.config.resources.ResourceAccessPolicy) – What this document may fetch. Falls back to a policy set around the call with use_policy, then to a default that refuses internal network addresses and confines local reads to the document’s own directory. See Security.

Returns:

Return type:

xhtml2pdf.document.pisaStory|bytes

Link callback

Images, backgrounds, and stylesheets are loaded from the HTML document. Normally, xhtml2pdf expects these files to be found on the local drive. They may also be referenced relative to the original document. You might, however, want to reference these objects from somewhere else, like a Web page or a database. Therefore, you may define a link_callback that handles these requests.

The link callback accepts two parameters:

1. uri — the URI that needs to be transformed

2. (optionally) basepath — the path of the resource where the URI originates from (useful for relative path calculations)

Note

A link_callback rewrites a URI; it does not authorise one. Its result goes through the resource policy, so a callback that resolves paths outside the document’s own directory needs those directories named in the policy. See Security.