使用生成的兼容性 API

使用生成的兼容性 API

Aspose.PDF FOSS for Python 提供了第二套更小的 API 接口，位于 aspose_pdf.generated 子包下：generated.document.Document、generated.forms.UnsignedContent 和 UnsignedContentAbsorber，以及 generated.pdfa.PdfAValidateOptions 和 PdfAValidationResult。这些类的名称与库的主 API（aspose_pdf.Document、aspose_pdf.UnsignedContent 等）中的类相同，但它们是独立定义的、方法集合更精简的类。它们作为独立的兼容层存在——始终使用完整的 aspose_pdf.generated.* 路径导入，以确保调用到正确的类。

通过生成的 Document 管理文档生命周期

generated.document.Document 支持核心文档生命周期：加载、保存、基本优化、加密和验证。其大多数属性的类型为 Any，而不是主 Document 类中暴露的更丰富的类型。

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()

加密和密码更改使用单密码形式，而不是主 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")

提取未签名内容

generated.forms.UnsignedContentAbsorber 将文档中尚未签名的页面、表单字段和批注提取到 UnsignedContent 容器中。调用 extract() 进行提取，然后使用 get_extracted() 或 has_extracted() 检查结果，而无需重新运行。

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 也可以直接构建并填充，独立于吸收器：

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 验证选项和结果

generated.pdfa.PdfAValidateOptions 和 PdfAValidationResult 是用于 PDF/A 风格验证工作流的独立选项/结果对。它们不是由主 API 的 Document.validate_pdfa() 返回的类，也不是被 PdfAValidator.process() 消费的——后者使用它们自己单独定义的 PdfAValidateOptions 和 PdfAValidationResult 类，具有更丰富的表面（level、warnings、is_heuristic，以及一个 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

提示与最佳实践

• 通过完整的子模块路径导入每个 generated 类（from aspose_pdf.generated.document import Document，以及同样适用于 generated.forms 和 generated.pdfa）——永远不要假设裸露的 Document 或 UnsignedContent 导入会解析为兼容版本。
• 每当同一模块的文件同时使用主 API 时，为导入的类指定一个区分度高的本地名称，以便在每个调用点两种表面保持明显分离。
• 将 generated.pdfa.PdfAValidateOptions/PdfAValidationResult 视为自包含的配对：构建选项，运行您自己的验证逻辑，并自行使用 add_error() 记录发现——它们不会被 Document.validate_pdfa() 自动填充。
• 如果不确定 extract() 已经运行，请在调用 get_extracted() 之前检查 UnsignedContentAbsorber.has_extracted()。
• 除非你特别需要精简的、生成的兼容层，否则在新代码中应优先使用主要的 aspose_pdf.Document API。

常见问题

FAQ

aspose_pdf.generated 是存根还是占位符？

不是。它是一个真实的、可导入的子包，包含可用的类 —— Document、UnsignedContent、UnsignedContentAbsorber、PdfAValidateOptions 和 PdfAValidationResult —— 它只是比库的主要 API 更小的、独立的表面而已。

为什么 generated.document.Document 与 aspose_pdf.Document 同名？

它们是两个独立定义的类，恰好共享同一个名称。从 aspose_pdf.generated.document 导入会得到兼容版本；而导入 aspose_pdf.Document（或 from aspose_pdf import Document）则会得到主要版本。

我可以将 generated.pdfa.PdfAValidateOptions 传递给 PdfAValidator.process() 吗？

不。PdfAValidator.process() 是主要 API 的一部分，并且期望主要 API 自己的 PdfAValidateOptions 类，该类具有不同的方法签名（add_input(source) 而不是无参数的 add_input()）。

UnsignedContentAbsorber.extract() 需要 Document 参数吗？

不。extract() 在生成的兼容层中不接受任何参数；构造吸收器并直接调用 extract()。

API Reference 摘要

另请参阅

• Aspose.PDF for Python — Enterprise Documentation