Working with the Generated Compatibility API

Aspose.PDF FOSS for Python ships a second, smaller API surface under the aspose_pdf.generated subpackage: generated.document.Document, generated.forms.UnsignedContent and UnsignedContentAbsorber, and generated.pdfa.PdfAValidateOptions and PdfAValidationResult. Each of these classes shares its name with a class in the library’s primary API (aspose_pdf.Document, aspose_pdf.UnsignedContent, and so on), but they are separate, independently defined classes with a reduced method surface. They exist as a standalone compatibility layer — always import them by their full aspose_pdf.generated.* path so you know which one you are calling.

Document lifecycle via the generated Document

generated.document.Document supports the core document lifecycle: loading, saving, basic optimization, encryption, and validation. Most of its properties are typed Any rather than the richer types exposed on the primary Document class.

from aspose_pdf.generated.document import Document

doc = Document()
doc.load_from("input.pdf")

doc.optimize(compress_images=True)
doc.optimize_resources(remove_unused=True)

if doc.validate():
    doc.save("output.pdf")

doc.dispose()

Encryption and password changes use a single-password form rather than the separate user/owner passwords of the primary Document.encrypt:

from aspose_pdf.generated.document import Document

doc = Document()
doc.load_from("input.pdf")

doc.encrypt("secret")
doc.change_passwords("secret", "new-secret")
doc.save("protected.pdf")

Extracting unsigned content

generated.forms.UnsignedContentAbsorber extracts the pages, form fields, and annotations of a document that have not yet been signed into an UnsignedContent container. Call extract() to run the extraction, then get_extracted() or has_extracted() to check the result without re-running it.

from aspose_pdf.generated.document import Document
from aspose_pdf.generated.forms import UnsignedContentAbsorber

doc = Document()
doc.load_from("input.pdf")

absorber = UnsignedContentAbsorber()
extracted = absorber.extract()

print(len(extracted.pages), len(extracted.form_fields), extracted.annotations)

if absorber.has_extracted():
    same_result = absorber.get_extracted()

absorber.reset()

UnsignedContent can also be built and populated directly, independent of an absorber:

from aspose_pdf.generated.forms import UnsignedContent

bundle = UnsignedContent()
bundle.add_page(some_page)
bundle.add_form_field(some_field)
bundle.add_annotation(some_annotation)

bundle.remove_page(some_page)
bundle.reset()

PDF/A validation options and results

generated.pdfa.PdfAValidateOptions and PdfAValidationResult are a standalone options/result pair for PDF/A-style validation workflows. They are not the classes returned by the primary API’s Document.validate_pdfa() or consumed by PdfAValidator.process() — those use their own, separately defined PdfAValidateOptions and PdfAValidationResult classes with a richer surface (level, warnings, is_heuristic, and a font_lookup_directory).

from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

options = PdfAValidateOptions()
options.add_input()
options.set_option("level", "1b")

stored_options = options.get_options()

result = PdfAValidationResult()
result.add_error("Font not embedded: Arial")

summary = result.to_dict()
is_valid = result.is_valid

Tips and Best Practices

Import every generated class through its full submodule path (from aspose_pdf.generated.document import Document, and similarly for generated.forms and generated.pdfa) — never assume a bare Document or UnsignedContent import resolves to the compatibility version.
Give the imported class a distinguishing local name whenever a file also uses the primary API in the same module, so the two surfaces stay visibly separate at every call site.
Treat generated.pdfa.PdfAValidateOptions/PdfAValidationResult as a self-contained pair: build the options, run your own validation logic, and record findings with add_error() yourself — they are not auto-populated by Document.validate_pdfa().
Check UnsignedContentAbsorber.has_extracted() before calling get_extracted() if you are not certain extract() has already run.
Prefer the primary aspose_pdf.Document API for new code unless you specifically need the reduced, generated-compatibility surface.

Common Issues

Issue	Cause	Fix
Wrong `Document` methods available (missing `pages`, `form`, `xmp_metadata`, and similar)	Imported `generated.document.Document` instead of the primary `aspose_pdf.Document`	Import the primary class (`import aspose_pdf; aspose_pdf.Document()`) unless the reduced surface is what you intend
`PdfAValidateOptions`/`PdfAValidationResult` from `generated.pdfa` don’t work with `PdfAValidator.process()`	The primary API’s `PdfAValidator` expects its own `PdfAValidateOptions`/`PdfAValidationResult` classes, not the `generated.pdfa` versions	Use the `PdfAValidateOptions`/`PdfAValidationResult` classes exported from `aspose_pdf` for `PdfAValidator` workflows
`get_extracted()` returns `None`	`extract()` was never called on that `UnsignedContentAbsorber` instance	Call `extract()` before `get_extracted()`, or check `has_extracted()` first
Properties on `generated.document.Document` are typed `Any` and give no autocomplete	The generated surface trades static typing for a smaller, simpler API	Cast or document the expected type at the call site, or switch to the primary `Document` class for richer typing

FAQ

Is aspose_pdf.generated a stub or placeholder?

No. It is a real, importable subpackage with working classes — Document, UnsignedContent, UnsignedContentAbsorber, PdfAValidateOptions, and PdfAValidationResult — it is simply a smaller, standalone surface than the library’s primary API.

Why does generated.document.Document have the same name as aspose_pdf.Document?

They are two independently defined classes that happen to share a name. Importing from aspose_pdf.generated.document gives you the compatibility version; importing aspose_pdf.Document (or from aspose_pdf import Document) gives you the primary version.

Can I pass a generated.pdfa.PdfAValidateOptions to PdfAValidator.process()?

No. PdfAValidator.process() is part of the primary API and expects the primary API’s own PdfAValidateOptions class, which has a different method signature (add_input(source) instead of a no-argument add_input()).

Does UnsignedContentAbsorber.extract() need a Document argument?

No. extract() takes no arguments in the generated compatibility surface; construct the absorber and call extract() directly.

API Reference Summary

Class / Method	Description
`Document.load_from`	Loads a document from a file path, bytes, or stream
`Document.save`	Saves the document to a destination
`Document.optimize`	Performs generic optimization, optionally compressing images
`Document.optimize_resources`	Optimizes shared resources such as fonts and images
`Document.encrypt`	Encrypts the document with a single password
`Document.change_passwords`	Changes the document’s password
`Document.validate`	Returns whether the document is structurally valid
`Document.dispose`	Releases resources associated with the document
`UnsignedContent.add_page` / `remove_page`	Adds or removes a page from an unsigned-content bundle
`UnsignedContent.add_form_field` / `remove_form_field`	Adds or removes a form field from an unsigned-content bundle
`UnsignedContent.add_annotation` / `remove_annotation`	Adds or removes an annotation from an unsigned-content bundle
`UnsignedContentAbsorber.extract`	Extracts unsigned content into an `UnsignedContent` instance
`UnsignedContentAbsorber.get_extracted`	Returns the last extracted `UnsignedContent`, if any
`UnsignedContentAbsorber.has_extracted`	Reports whether extraction has been performed
`PdfAValidateOptions.add_input`	Registers an input source for validation
`PdfAValidateOptions.set_option` / `get_options`	Sets or reads validation option values
`PdfAValidationResult.add_error`	Adds an error message and marks the result invalid
`PdfAValidationResult.to_dict`	Returns a dictionary representation of the validation result

Working with the Generated Compatibility API