Choose a Rendering Device in Python

Choose a rendering device by the required output format, not by the source format. Use PdfDevice for PDF, ImageDevice for raster images, DocDevice for DOCX, and XpsDevice for XPS. The source is supplied through document.render_to() or a matching source-specific renderer.

A rendering device implements the IDevice interface and receives drawing operations produced while a document is rendered. The device writes those operations to a particular output format.

Choose a Rendering Device

Source, renderer, device, and rendering options have separate roles:

Component	Select it by	Examples
Source	Input content	HTMLDocument, SVGDocument, MHTML stream, EPUB stream
Renderer	Source type and rendering workflow	HtmlRenderer, SvgRenderer, MhtmlRenderer, EpubRenderer
Device	Output format	PdfDevice, ImageDevice, DocDevice, XpsDevice
Rendering options	Layout and output-specific settings	PdfRenderingOptions, ImageRenderingOptions, DocRenderingOptions, XpsRenderingOptions

For one loaded HTML or SVG document, call document.render_to(device). When a source-specific renderer is required, pass the same device to renderer.render(). The device does not parse the source; it receives the rendered result and writes the output.

The two common paths are:

• document → rendering device → output;
• source → renderer → rendering device → output.

Output	Device and options	Choose it when	Most relevant controls
PDF	PdfDevice with PdfRenderingOptions	The result must be a paginated PDF document.	PDF metadata, JPEG compression quality, encryption, form-field behavior, and tagged-PDF output.
Raster image	ImageDevice with ImageRenderingOptions	The rendered pages are needed as PNG, JPEG, BMP, GIF, or TIFF images.	Raster format, TIFF compression, graphics antialiasing, text hinting, and output resolution.
DOCX	DocDevice with DocRenderingOptions	The result must be opened or edited as a Word DOCX document.	Font embedding, page layout, background, and CSS media settings.
XPS	XpsDevice with XpsRenderingOptions	The result must be a fixed-layout XPS document.	Common page setup, background, CSS media, and resolution settings.

Render HTML to PDF with PdfDevice

The following example loads document.html, creates a PdfDevice, and sends the document directly to the device. It demonstrates the same three-step workflow used with the other output devices.

To render a loaded document to a device:

1. Load or create the source document.
2. Create the device for the required output format and specify the destination.
3. Call render_to() and pass the device.

import os
import aspose.html as ah
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.pdf")

with ah.HTMLDocument(input_path) as document:
    with rp.PdfDevice(output_path) as device:
        document.render_to(device)

The result is document.pdf created with the default PDF rendering options. To customize a device, create its matching options object and pass the object and output destination to the device constructor. Common rendering settings include page setup, background color, CSS media, and resolution; the last column of the table highlights the controls most relevant to each output.

Do not pass save options such as PdfSaveOptions to PdfDevice. Save options belong to the high-level Converter workflow. Devices use rendering options such as PdfRenderingOptions. See Rendering Options for tested examples of page layout, PDF properties, TIFF output, and DOCX font embedding.

Common Device Selection Issues

Issue	Explanation and fix
The source type and device appear mismatched	The source and device are selected independently. Match the document or renderer to the input, then choose the device by output format.
A save-options object is rejected by a device	Use the corresponding rendering-options class, such as PdfRenderingOptions with PdfDevice.
DocDevice output is saved with a .doc extension	DocDevice produces DOCX. Use the .docx extension.
The image format is not the one expected	Select the required format in ImageRenderingOptions before creating ImageDevice.
Multiple sources must be written to one output	Use the appropriate source-specific renderer and pass the collection of sources to renderer.render().

Related Rendering Guides

• Fine-Tune HTML Rendering in Python – compare the high-level Converter API with the Rendering API.
• Renderers – choose a renderer by source type and use multi-source or timeout overloads.
• Rendering Options – configure general and output-specific rendering settings.

Other Platforms

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