Як створювати документи за допомогою згенерованого модуля сумісності в Python

Aspose.PDF FOSS для Python постачається з підпакетом сумісності generated (aspose_pdf.generated), який відображає стабільну підмножину основної поверхні API — клас Document з базовими операціями життєвого циклу, а також UnsignedContent/UnsignedContentAbsorber і PdfAValidateOptions/PdfAValidationResult. Він існує для викликачів, які явно потребують цього вузького інтерфейсу замість повнофункціональних класів верхнього рівня, і його класи не імпортуються автоматично import aspose_pdf — ви імпортуєте їх безпосередньо з aspose_pdf.generated.*. Пакет є чистим Python і встановлюється за допомогою наведеної нижче команди.

Покроковий посібник

Крок 1: Встановіть пакет

Встановіть пакет Aspose.PDF FOSS:

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

Перевірте встановлення, імпортуючи згенерований Document і виводячи повідомлення про підтвердження:

import aspose_pdf
from aspose_pdf.generated.document import Document
print("aspose-pdf-foss-for-python is ready.")

Крок 2: Імпорт необхідних класів

Класи сумісності generated розташовані у aspose_pdf.generated.document, aspose_pdf.generated.forms та aspose_pdf.generated.pdfa — імпортуйте їх явно за підмодулем:

import aspose_pdf
from aspose_pdf.generated.document import Document
from aspose_pdf.generated.forms import UnsignedContent, UnsignedContentAbsorber
from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

Крок 3: Створити та завантажити документ

Document(source) завантажується одразу, коли вказано джерело; виклик Document() без аргументу створює порожній екземпляр, який можна завантажити пізніше за допомогою load_from. Обидва приймають шлях до файлу, bytes, або бінарний потік:

from aspose_pdf.generated.document import Document

document = Document("report.pdf")
print(f"Loaded {len(document.pages)} page(s)")

empty_doc = Document()
empty_doc.load_from("report.pdf")

Крок 7: Витягти вміст непідписаної форми

UnsignedContentAbsorber витягує сторінки, поля форми та анотації, які не входять до цифрового підпису. Викличте extract(), щоб запустити витяг, has_extracted(), щоб перевірити, чи він вже був виконаний, і get_extracted(), щоб отримати результат знову без повторного витягування:

from aspose_pdf.generated.forms import UnsignedContentAbsorber

absorber = UnsignedContentAbsorber()
unsigned = absorber.extract()
print(f"Unsigned pages: {len(unsigned.pages)}")
print(f"Unsigned form fields: {len(unsigned.form_fields)}")

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

Крок 8: Побудувати контейнер UnsignedContent вручну

UnsignedContent також є простим контейнером, який ви можете заповнити самостійно за допомогою add_page, add_form_field та add_annotation — у кожного є відповідний метод remove_*, а reset() очищає всі три колекції одночасно:

from aspose_pdf.generated.forms import UnsignedContent

content = UnsignedContent()
content.add_page("page-1")
content.add_annotation("signature-placeholder")
print(content)  # UnsignedContent(pages=1, form_fields=0, annotations=1)

content.remove_annotation("signature-placeholder")
content.reset()

Крок 9: Налаштувати та запустити перевірку PDF/A

PdfAValidateOptions збирає вхідні дані та налаштування для запуску валідації. add_input(source) реєструє вхід, set_option(key, value) зберігає іменовану опцію, а get_options() повертає копію збережених опцій. PdfAValidationResult містить результат — add_error(message) позначає результат недійсним і додає до errors, а to_dict() формує is_valid і errors як простий словник:

from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

options = PdfAValidateOptions()
options.add_input("report.pdf")
options.set_option("pdfa_version", "1b")
print(options.get_options())

result = PdfAValidationResult()
result.add_error("Font 'Arial' is not embedded")
print(result.is_valid)   # False
print(result.to_dict())

Типові проблеми та виправлення

ImportError or AttributeError при доступі aspose_pdf.generated

Підпакет generated не переекспортується import aspose_pdf — імпортуйте кожен клас з його конкретного підмодуля, наприклад from aspose_pdf.generated.document import Document, замість очікування, що aspose_pdf.generated.Document працюватиме після простого import aspose_pdf.

Заплутування згенерованого Document з основним aspose_pdf.Document

aspose_pdf.Document (клас верхнього рівня, переекспортований import aspose_pdf) має ширший інтерфейс — він додає методи, такі як validate_pdfa, iter_pages та redact_text, які aspose_pdf.generated.document.Document не реалізує. Якщо метод відсутній у згенерованому Document, перевірте, чи він належить до класу верхнього рівня Document.

save() raises AsposePdfException: Cannot save a disposed document

close()/dispose() назавжди звільняє внутрішній стан документа — утилізований Document не може бути збережений, оптимізований або відновлений пізніше. Виконайте всі залишкові операції перед викликом close(), або перезавантажте з джерела за допомогою нового виклику Document(...).

change_passwords raises PdfSecurityException: Document is not encrypted

change_passwords лише змінює пароль у документі, який вже зашифрований. Спершу викличте encrypt(password), або перевірте document.is_encrypted перед спробою змінити пароль.

PdfAValidationResult.add_error raises TypeError

add_error потребує аргумент str. Перетворіть об’єкти виключень або інші деталі помилок у рядок (str(error)) перед передачею їх у add_error.

Часто задавані питання

Чому `aspose_pdf.generated` існує поряд з основним `aspose_pdf.Document`?

Він віддзеркалює більш вузьку, стабільну підмножину Aspose.PDF API для коду, написаного проти цієї скороченої поверхні. Новий код, який не потребує саме цієї підмножини сумісності, зазвичай слід використовувати верхньорівневий aspose_pdf.Document, який підтримує більше операцій (PDF/A конверсія, ітерація сторінок, редагування тексту та інші).

Чи приймає `UnsignedContentAbsorber.extract()` `Document` для сканування?

extract() приймає позиційні та іменовані аргументи, які використовуються для заповнення колекцій pages, form_fields та annotations повернутого UnsignedContent — передайте потрібні колекції як іменовані аргументи (pages=, form_fields=, annotations=).

Що станеться, якщо я викликаю `reset()` на `UnsignedContentAbsorber` до того, як щось витягнути?

Він очищає будь-який раніше витягнутий результат. Потім get_extracted() повертає None, а has_extracted() повертає False, доки extract() не буде викликано знову.

Чи можна викликати `PdfAValidateOptions.add_input` більше одного разу?

Так — кожний виклик додає ще один запис до списку inputs і повертає self, тому виклики можна ланцюжити: options.add_input("a.pdf").add_input("b.pdf").

Чи відрізняється `close()` від `dispose()` у згенерованому `Document`?

Ні — close() є прямим псевдонімом, який викликає dispose() з тими ж аргументами; будь-яка назва звільняє ресурси документа.