Introduction

Aspose.PDF FOSS for Python is a new open-source library for working with PDF documents from Python code. It is released under the MIT license and implemented entirely in Python — the PDF parser, writer, page rasterizer, and encryption routines are part of the package itself, with required dependencies limited to cryptography and asn1crypto. Optional extras add Pillow-based image support, Brotli-based WOFF2 font decoding, and HarfBuzz-based complex text shaping.

The library is organized around the Document class, which loads a PDF from a path, bytes, or a binary stream and exposes its pages through document.pages, a PageCollection supporting iteration, indexing, and slicing. From there, the API covers adding text and images to pages, reading and modifying annotations, creating and filling AcroForm fields, encrypting and decrypting documents, and extracting text and attachments — the operations needed to build new PDFs or work with existing ones.

This release is for developers who need PDF processing inside a Python codebase without a commercial license: report and invoice generation, document ingestion pipelines, form-filling automation, and services that need to render PDF pages to images or extract text for downstream indexing. The project is currently in alpha, so APIs and feature coverage may evolve before the first stable release. Python 3.11 or newer is required.

What’s Included

Document Creation and Loading

Document() creates an empty document; Document(source, password=..., limits=...) loads an existing one from a path, raw bytes, or a binary stream, and is equivalent to calling Document().load_from(source, ...). Both raise on a missing file, non-PDF data, or a missing password rather than returning an empty document. Document is a context manager, so resources are released automatically when the with block exits.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text("Generated by Aspose.PDF FOSS", x=72, y=720, font_size=14)
    document.save("report.pdf")

with Document("report.pdf") as document:
    print(f"Pages: {document.page_count}")
    print(f"PDF version: {document.version}")

Adding Text and Images

Page.add_text() places Standard-14 or embedded Unicode text at an x/y position with a given font_size; passing font= accepts a FontDescriptor, bytes, or a path to embed a TrueType/OpenType font for Unicode outside the Standard-14 encodings. Page.add_image() places a raw, JPEG, or PNG image XObject on the page at a given position and size.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Quarterly Summary",
        x=72,
        y=740,
        font_size=16,
    )
    page.add_image(
        "chart.png",
        x=72,
        y=420,
        width=300,
        height=200,
    )
    document.save("summary.pdf")

Annotations

Each Page exposes its annotations through page.annotations, an AnnotationCollection. add(subtype, rect, contents, title, appearance_normal, properties) creates and inserts an annotation of a standard subtype such as Square, Circle, Line, Highlight, or FreeText, returning an Annotation. Calling generate_appearance() on the returned annotation synthesizes an appearance stream from its geometry and properties.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    annotation = page.annotations.add(
        "Square",
        (100, 600, 300, 680),
        "Needs review",
        properties={"C": [1, 0, 0]},
    )
    annotation.generate_appearance()
    document.save("annotated.pdf")

Form Fields

document.form returns the document’s Form, which creates AcroForm fields directly: add_text_field(), add_checkbox(), add_radio_group(), add_list_box(), add_combo_box(), and add_push_button() each accept a field name, a Page or page index, and a placement rectangle, returning a Field. Setting field.value updates the field’s value, and form.flatten() bakes every field’s appearance into static page content.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    form = document.form
    field = form.add_text_field(
        "customer_name",
        page,
        (72, 700, 300, 720),
    )
    field.value = "Jane Doe"
    form.flatten()
    document.save("form.pdf")

Encryption

Document.encrypt(user_password, owner_password, permissions) protects a document with a user password, an owner password, and a permission bitmask, returning the same Document for chaining. Document.decrypt(password) reverses the operation, and the is_encrypted property reports the current state. Loading an encrypted document again requires passing password= to the constructor or to load_from().

from aspose_pdf import Document

with Document("report.pdf") as document:
    document.encrypt(user_password="user-pass", owner_password="owner-pass", permissions=0)
    document.save("encrypted.pdf")

with Document("encrypted.pdf", password="user-pass") as document:
    print(f"Encrypted: {document.is_encrypted}")

Text Extraction

PdfExtractor binds to a source with bind_pdf(), then extract_text() walks the document’s pages. get_text() returns all extracted text at once, while has_next_page_text() and get_next_page_text() iterate the result page by page. PdfExtractor is also a context manager.

from aspose_pdf import PdfExtractor

with PdfExtractor() as extractor:
    extractor.bind_pdf("report.pdf")
    extractor.extract_text()
    while extractor.has_next_page_text():
        print(extractor.get_next_page_text())

Quick Start

pip install aspose-pdf-foss-for-python

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Hello from Aspose.PDF FOSS!",
        x=72,
        y=720,
        font_size=18,
    )
    document.save("hello.pdf")

with Document("hello.pdf") as document:
    print(f"Pages: {document.page_count}")
    print(f"PDF version: {document.version}")

Supported Formats

FormatExtensionReadWrite
PDF.pdf✓✓
PNG.png—✓
TIFF.tiff—✓

PDF is the library’s core input and output format, read through Document/load_from() and written through Document.save(). PNG and TIFF are page-rendering outputs produced by Page.render(), Page.save_as_image(), and Document.save_page_as_image().

Open Source & Licensing

Aspose.PDF FOSS for Python is distributed under the MIT license, with the full source available at github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python. The license permits commercial use, modification, and redistribution without a separate agreement.

Getting Started