Render HTML, SVG, MHTML, and EPUB in Python

Use document.render_to() to send one loaded document directly to an output device. Use HtmlRenderer, SvgRenderer, MhtmlRenderer, or EpubRenderer when the application needs a source-specific renderer, several sources rendered to one output device, or a rendering timeout.

Renderers process source documents and send drawing operations to an IDevice implementation. The renderer must match the source type, while the device determines whether the result is written as PDF, XPS, DOCX, or a raster image.

Choose a Renderer for the Source Type

Source	Renderer	Expected input
HTML	HtmlRenderer	One or more HTMLDocument objects
SVG	SvgRenderer	One or more SVGDocument objects
MHTML	MhtmlRenderer	One or more binary streams
EPUB	EpubRenderer	One or more binary streams

Choose the device separately according to the required output:

Output	Device
PDF	PdfDevice
Raster image	ImageDevice
DOCX	DocDevice
XPS	XpsDevice

A renderer and a device therefore answer different questions: the renderer identifies what is being processed, while the device identifies the output format.

Renderer vs. document.render_to()

API	Use it when
document.render_to(device)	One HTML or SVG document is already loaded and should be sent directly to a device.
renderer.render(device, source)	The application should explicitly select the renderer for an HTML, SVG, MHTML, or EPUB source.
renderer.render(device, sources)	Several sources of the same supported type should be rendered to one output device.
renderer.render(device, source, timeout)	The rendering operation needs a maximum waiting time.

For common one-file conversions, the high-level Converter API is usually shorter. Renderers are most useful when their multi-source or timeout overloads are required.

Render Multiple HTML Documents to One PDF

HtmlRenderer accepts a list of HTMLDocument objects. The following example loads document.html and paragraphs.html, then sends both documents to one PdfDevice.

To render several HTML documents to one output:

1. Load each HTML source as an HTMLDocument.
2. Create the device for the required output format.
3. Create an HtmlRenderer instance.
4. Pass the device and the list of documents to renderer.render().

import os
import aspose.html as ah
import aspose.html.rendering as rn
import aspose.html.rendering.pdf as rp

data_dir = "data"
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)

first_path = os.path.join(data_dir, "document.html")
second_path = os.path.join(data_dir, "paragraphs.html")
output_path = os.path.join(output_dir, "combined.pdf")

with ah.HTMLDocument(first_path) as first_document, \
        ah.HTMLDocument(second_path) as second_document:
    with rp.PdfDevice(output_path) as device:
        with rn.HtmlRenderer() as renderer:
            renderer.render(device, [first_document, second_document])

The result is one PDF containing the rendered output of both HTML documents. This operation does not combine their DOM trees and does not create a new HTML document.

Set a Rendering Timeout

The integer timeout overload limits how long the renderer waits for document lifecycle tasks during rendering. The value is measured in milliseconds; -1 means an indefinite wait. A timeout is useful when a document depends on remote resources, scripts, timers, or other work that may delay completion.

The following example gives HtmlRenderer up to 5,000 milliseconds to render an HTML document to PDF:

import os
import aspose.html as ah
import aspose.html.rendering as rn
import aspose.html.rendering.pdf as rp

data_dir = "data"
output_dir = "output"
os.makedirs(output_dir, exist_ok=True)

input_path = os.path.join(data_dir, "document.html")
output_path = os.path.join(output_dir, "document-timeout.pdf")
timeout = 5000

with ah.HTMLDocument(input_path) as document:
    with rp.PdfDevice(output_path) as device:
        with rn.HtmlRenderer() as renderer:
            renderer.render(device, document, timeout)

If the rendering lifecycle does not finish within the specified interval, the resulting output may be incomplete. Choose a limit that allows expected resources and scripts to finish, and validate the generated file.

Source-Specific Renderer Workflows

The same output device can be paired with different renderers. Match the renderer to the source and keep stream-based inputs open until render() completes:

• use HtmlRenderer with HTMLDocument objects;
• use SvgRenderer with SVGDocument objects;
• use MhtmlRenderer with MHTML streams opened in binary mode;
• use EpubRenderer with EPUB streams opened in binary mode.

For page size, margins, background color, image settings, PDF security, and DOCX font embedding, configure the corresponding device with the settings described in Rendering Options.

Common Renderer Issues

Issue	Explanation and fix
A renderer rejects the source	Match HtmlRenderer to HTML documents, SvgRenderer to SVG documents, and the MHTML or EPUB renderer to binary streams of the corresponding format.
The output format is wrong	Choose the device by output format. For example, use PdfDevice for PDF and ImageDevice for raster images.
Several files do not become one HTML document	Multi-source rendering combines rendered output in the target device; it does not merge DOM trees or save a new HTML source file.
Output is incomplete when a timeout is used	Increase the timeout and check remote resources, scripts, timers, and other operations that delay completion.
An MHTML or EPUB stream cannot be read	Open the file in binary mode and keep the stream open until renderer.render() returns.

Related Rendering Guides

• Fine-Tune HTML Rendering in Python – compare the Converter and Rendering APIs.
• Rendering Devices – choose a PDF, image, DOCX, or XPS output device.
• Rendering Options – configure page layout and format-specific output settings.
• HTML Converter – use the high-level API for common HTML conversion workflows.

Other Platforms

• Renderers in C#
• Fine-Tune Rendering in Java