Introduction

document.py, the module that defines Aspose.PDF FOSS for Python’s Document class, describes it as a class that “wraps the native PDF engine.” Concretely, that engine is aspose_pdf.engine.simple_pdf.SimplePdf: Document.load_from() builds a SimplePdf instance, and every document-level operation — saving, optimizing, repairing, encrypting — delegates to it. The same is true of rendering: Page.render() and Document.render_page() both call into aspose_pdf.engine.rasterizer.

Most application code never needs to look past Document and Page. But aspose_pdf.engine is an ordinary, importable Python package, and several of the pieces underneath the facade are useful on their own: the rasterizer that turns a page into pixels, the stream-filter codecs that compress and decompress PDF content streams, and the encryption utilities that implement the AES-CBC and RC4 algorithms PDF security handlers rely on. Unlike the main package, aspose_pdf.engine submodules are not re-exported from top-level aspose_pdf — the one exception is RasterizedPage, bridged through aspose_pdf.visualization — so everything below is imported by its full dotted path, for example from aspose_pdf.engine.filters import StreamDecoder.

Aspose.PDF FOSS for Python is a Python package, aspose-pdf-foss-for-python, released under the MIT license, requiring Python 3.11 or later. Its top-level module name is aspose_pdf, installed with pip install aspose-pdf-foss-for-python. The core package depends only on cryptography and asn1crypto; optional extras add Pillow-based image decoding, Brotli-based WOFF2 font support, and HarfBuzz-based complex text layout.

Key Features

Rendering Pages with the Rasterization Engine

Document.render_page(page_index, dpi=..., scale=..., background=..., antialias=...) and its Page.render() counterpart both return a RasterizedPage — a packed RGB raster produced by the engine’s rasterizer. RasterizedPage exposes width, height, and raw pixels bytes, plus get_pixel() for a single-pixel lookup, to_png() / to_tiff() for in-memory encoded bytes, and save() to write a .png or .tif/.tiff file directly. Working with the object in memory — rather than only saving to disk — is useful when a caller wants to inspect or transform pixels before deciding whether to keep them.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text("Rendered by the engine", x=72, y=700, font_size=18)

    raster = document.render_page(0, dpi=150)
    print(raster.width, raster.height)

    corner = raster.get_pixel(0, 0)
    print("top-left pixel:", corner)

    with open("page-0.png", "wb") as handle:
        handle.write(raster.to_png())
    raster.save("page-0.tiff")

The Stream Filter Engine

PDF content and object streams are compressed with named filters such as FlateDecode and LZWDecode. aspose_pdf.engine.filters.StreamEncoder.encode(data, filters, decode_parms=None) and StreamDecoder.decode(data, filters, decode_parms, *, limits=None, max_output_bytes=None) implement the encode and decode sides of that filter chain — the same codecs the engine uses internally when it writes and reads a document’s streams. Both accept a single filter name or a list for chained filters, and StreamDecoder.decode() raises PdfValidationException on an unrecognized filter name instead of returning silently-wrong bytes.

from aspose_pdf.engine.filters import StreamDecoder, StreamEncoder

raw = b"Sample content-stream payload.\n" * 40
compressed = StreamEncoder.encode(raw, "FlateDecode")
restored = StreamDecoder.decode(compressed, "FlateDecode", None)

assert restored == raw
print(f"{len(raw)} bytes -> {len(compressed)} bytes with FlateDecode")

The Encryption Engine

aspose_pdf.engine.encryption.EncryptionUtils is the static-method utility class SimplePdf calls into for every encryption-related operation: Document.encrypt(), decrypt(), and change_passwords() all resolve to EncryptionUtils calls under the hood. Its methods implement AES-CBC and RC4 encryption directly (encrypt_aes_cbc, decrypt_aes_cbc, encrypt_rc4, decrypt_rc4), key derivation for the PDF standard security handler revisions (compute_owner_key_v4, compute_user_key_v4, compute_user_owner_keys_v6), and generate_file_id() for the random 16-byte ID new documents need.

from aspose_pdf.engine.encryption import EncryptionUtils

key = b"0123456789ABCDEF"  # 16 bytes -> AES-128
ciphertext = EncryptionUtils.encrypt_aes_cbc(key, b"Reviewer notes: approved")
plaintext = EncryptionUtils.decrypt_aes_cbc(key, ciphertext)
assert plaintext == b"Reviewer notes: approved"

file_id = EncryptionUtils.generate_file_id()
print(file_id.hex())

Quick Start

Install the package, then render a page straight from the engine layer in a single script.

pip install aspose-pdf-foss-for-python

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text("Engine-rendered page", x=72, y=740, font_size=20)

    raster = document.render_page(0, dpi=150)
    raster.save("engine-render.png")

    document.save("engine-quickstart.pdf")

print("Saved engine-quickstart.pdf and engine-render.png")

Supported Formats

FormatExtensionReadWrite
PDFpdfYesYes
TIFFtiff-Yes

PDF read and write is Aspose.PDF FOSS for Python’s core function — the Document/SimplePdf engine pair loads and writes PDF documents on every code path in this post. Document.render_page(), Page.render(), and RasterizedPage.to_png() / to_tiff() additionally produce PNG and TIFF raster output; these are page-rasterization outputs rather than document-loading formats.

Open Source & Licensing

Aspose.PDF FOSS for Python is released under the MIT license: no usage restrictions, no runtime fees, and no registration requirements for commercial or personal use. Source code is hosted at github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, and the package is published on PyPI as aspose-pdf-foss-for-python.

Getting Started