Introduction

Aspose.PDF FOSS for Python includes an aspose_pdf.generated subpackage with four modules: document.py, forms.py, pdfa.py, and security.py. None of them are re-exported from the top-level aspose_pdf package, so every class in this guide is imported by its full dotted path — from aspose_pdf.generated.document import Document, not from aspose_pdf import Document.

The four modules take two different approaches. generated.document and generated.forms and generated.pdfa each define their own classes: independent implementations that mirror the shape of the main package’s Document, UnsignedContent/UnsignedContentAbsorber, and PdfAValidateOptions/PdfAValidationResult — useful for code written against that mirrored namespace layout, but a real, separate set of classes rather than aliases. generated.security, on the other hand, does no reimplementation at all: it imports CompromiseCheckResult, SignaturesCompromiseDetector, and the validation enums directly from aspose_pdf.security and aspose_pdf.validation and re-exports them, so both import paths resolve to the identical class object.

This guide covers all four, and is explicit about where a generated class behaves differently from its main-package counterpart of the same name — Document and UnsignedContentAbsorber both exist in two places with two different implementations, which is exactly the kind of thing that is easy to get wrong when importing by name alone.

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

A Second Document Implementation

aspose_pdf.generated.document.Document implements the same core lifecycle as the main aspose_pdf.Document — load_from(), save(), encrypt()/decrypt()/change_passwords(), optimize()/optimize_resources(), repair(), flatten(), and validate()/check() — on top of the same aspose_pdf.engine.simple_pdf.SimplePdf engine. It mirrors a subset of the main Document: it has no pages.add()-style page authoring, no form/outlines/attachments, and no render_page(). Because the class name collides with the main package’s Document, import it under an alias when both are needed in the same module.

from aspose_pdf import Document
from aspose_pdf.generated.document import Document as CompatDocument

with Document() as document:
    document.pages.add()
    document.save("source.pdf")

compat = CompatDocument()
compat.load_from("source.pdf")
print(compat.page_count, compat.is_encrypted)

compat.optimize(compress_images=True)
compat.save("optimized.pdf", overwrite=True)
compat.dispose()

Packaging Unsigned Content

aspose_pdf.generated.forms.UnsignedContentAbsorber and UnsignedContent provide a container for unsigned form fields, pages, and annotations. This is different from the top-level aspose_pdf.UnsignedContentAbsorber(document), which takes a real Document and filters its form_fields/annotations for items whose is_signed/signed attribute is falsy. The generated.forms version takes no document at all — extract() simply packages whatever pages, form_fields, and annotations you pass it as keyword arguments into an UnsignedContent instance, which is useful when the unsigned items were already collected elsewhere and just need the shared container and its add_page()/remove_page()-style mutators.

from aspose_pdf.generated.forms import UnsignedContentAbsorber

absorber = UnsignedContentAbsorber()
content = absorber.extract(
    form_fields=["signature_field", "initials_field"],
    annotations=["review_stamp"],
)
print(absorber.has_extracted(), content.form_fields, content.annotations)

content.add_page("page-1")
absorber.reset()
print(absorber.get_extracted())

PDF/A Validation Options and Results

aspose_pdf.generated.pdfa.PdfAValidateOptions collects validation settings and input sources; PdfAValidationResult collects the outcome. PdfAValidateOptions.add_input() checks a string path with Path.exists() before accepting it and raises PdfIOException if the file is missing, so a caller finds out about a bad input path immediately rather than at validation time.

from aspose_pdf import Document
from aspose_pdf.exceptions import PdfIOException
from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

with Document() as document:
    document.pages.add()
    document.save("candidate.pdf")

options = PdfAValidateOptions()
options.set_option("pdfa_version", "PDF/A-2b")
options.add_input("candidate.pdf")
print(options.get_options(), options.inputs)

try:
    options.add_input("missing.pdf")
except PdfIOException as error:
    print(f"rejected: {error}")

result = PdfAValidationResult()
result.add_error("Missing /OutputIntent for PDF/A-2b")
print(result.is_valid, result.to_dict())

Re-exported Security and Validation Types

aspose_pdf.generated.security imports CompromiseCheckResult and SignaturesCompromiseDetector straight from aspose_pdf.security, and CertificationLevel, RevocationStatus, TrustStatus, ValidationMethod, ValidationMode, ValidationOptions, ValidationResult, and ValidationStatus from aspose_pdf.validation. Unlike Document and UnsignedContentAbsorber, there is no independent reimplementation here — both import paths return the same object.

from aspose_pdf.generated.security import SignaturesCompromiseDetector
from aspose_pdf.security import SignaturesCompromiseDetector as CanonicalDetector

assert SignaturesCompromiseDetector is CanonicalDetector

detector = SignaturesCompromiseDetector(document=None)
result = detector.check()
print(result.compromised, result.reasons)

Quick Start

Install the package, then build a document with the main Document, save it, and run it past the generated.pdfa options and result objects.

pip install aspose-pdf-foss-for-python

from aspose_pdf import Document
from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

with Document() as document:
    page = document.pages.add()
    page.add_text("PDF/A candidate", x=72, y=740, font_size=20)
    document.save("candidate.pdf")

options = PdfAValidateOptions()
options.set_option("pdfa_version", "PDF/A-2b")
options.add_input("candidate.pdf")

result = PdfAValidationResult()
if not options.inputs:
    result.add_error("No inputs registered")

print(result.to_dict())

Supported Formats

FormatExtensionReadWrite
PDFpdfYesYes

PDF read and write is Aspose.PDF FOSS for Python’s core function. Every class in this guide — the main Document, the generated.document.Document mirror, and the PDF/A helpers — operates on PDF input and output through the shared SimplePdf engine; aspose_pdf.generated changes which class you import, not what file format is being processed.

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