Como Criar Documentos com o Módulo de Compatibilidade Gerado em Python

Aspose.PDF FOSS para Python fornece um subpacote de compatibilidade generated (aspose_pdf.generated) que reproduz um subconjunto estável da superfície principal API — uma classe Document com as operações principais do ciclo de vida, além de UnsignedContent/UnsignedContentAbsorber e PdfAValidateOptions/PdfAValidationResult. Ele existe para chamadores que desejam essa superfície mais restrita explicitamente em vez das classes de nível superior com recursos completos, e suas classes não são importadas automaticamente por import aspose_pdf — você as importa diretamente de aspose_pdf.generated.*. O pacote é puro Python e é instalado com o comando abaixo.

Guia passo a passo

Etapa 1: Instalar o pacote

Instale o pacote FOSS Aspose.PDF:

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

Verifique a instalação importando o Document gerado e imprimindo uma mensagem de confirmação:

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

Etapa 2: Importar Classes Necessárias

As classes de compatibilidade generated estão em aspose_pdf.generated.document, aspose_pdf.generated.forms e aspose_pdf.generated.pdfa — importe-as explicitamente por submódulo:

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

Etapa 3: Criar e Carregar um Documento

Document(source) carrega imediatamente quando uma fonte é fornecida; chamar Document() sem argumento cria uma instância vazia que você pode carregar posteriormente com load_from. Ambos aceitam um caminho de arquivo, bytes, ou um fluxo binário:

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

Etapa 7: Extrair Conteúdo de Formulário Não Assinado

UnsignedContentAbsorber extrai as páginas, campos de formulário e anotações que não fazem parte de uma assinatura digital. Chame extract() para executar a extração, has_extracted() para verificar se ela foi executada e get_extracted() para obter o resultado novamente sem reextrair:

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

Etapa 8: Construir um Contêiner UnsignedContent Manualmente

UnsignedContent também é um contêiner simples que você pode preencher manualmente com add_page, add_form_field e add_annotation — cada um tem um método remove_* correspondente, e reset() limpa as três coleções de uma só vez:

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

Etapa 9: Configurar e Executar a Validação PDF/A

PdfAValidateOptions coleta as entradas e configurações para uma execução de validação. add_input(source) registra uma entrada, set_option(key, value) armazena uma opção nomeada e get_options() devolve uma cópia das opções armazenadas. PdfAValidationResult contém o resultado — add_error(message) marca o resultado como inválido e adiciona a errors, e to_dict() renderiza is_valid e errors como um dicionário simples:

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

Problemas Comuns e Correções

ImportError or AttributeError ao acessar aspose_pdf.generated

O subpacote generated não é reexportado por import aspose_pdf — importe cada classe do seu submódulo específico, por exemplo from aspose_pdf.generated.document import Document, em vez de esperar que aspose_pdf.generated.Document funcione após um simples import aspose_pdf.

Confundindo o gerado Document com o principal aspose_pdf.Document

aspose_pdf.Document (a classe de nível superior reexportada por import aspose_pdf) tem uma superfície maior — ela adiciona métodos como validate_pdfa, iter_pages e redact_text que aspose_pdf.generated.document.Document não implementa. Se um método estiver ausente no Document gerado, verifique se ele pertence à classe de nível superior Document em vez disso.

save() raises AsposePdfException: Cannot save a disposed document

close()/dispose() libera o estado interno do documento permanentemente — um Document descartado não pode ser salvo, otimizado ou reparado posteriormente. Execute todas as operações restantes antes de chamar close(), ou recarregue a partir da fonte com uma nova chamada Document(...).

change_passwords raises PdfSecurityException: Document is not encrypted

change_passwords apenas rotaciona uma senha em um documento que já está criptografado. Chame encrypt(password) primeiro, ou verifique document.is_encrypted antes de tentar alterar a senha.

PdfAValidationResult.add_error raises TypeError

add_error requer um argumento str. Converta objetos de exceção ou outros detalhes de erro para uma string (str(error)) antes de passá-los para add_error.

Perguntas Frequentes

Por que `aspose_pdf.generated` existe ao lado do `aspose_pdf.Document` principal?

Ele espelha um subconjunto mais estreito e estável do Aspose.PDF API para código escrito contra essa superfície reduzida. Código novo que não precisa especificamente desse subconjunto de compatibilidade deve geralmente usar o aspose_pdf.Document de nível superior, que suporta mais operações (PDF/A conversão, iteração de páginas, redação de texto e outras).

O `UnsignedContentAbsorber.extract()` aceita um `Document` para escanear?

extract() aceita argumentos posicionais e nomeados que são usados para preencher as coleções pages, form_fields e annotations do UnsignedContent retornado — passe as coleções que você deseja representar como argumentos nomeados (pages=, form_fields=, annotations=).

O que acontece se eu chamar `reset()` em `UnsignedContentAbsorber` antes de extrair qualquer coisa?

Ele limpa qualquer resultado extraído anteriormente. get_extracted() então retorna None e has_extracted() retorna False até que extract() seja chamado novamente.

O `PdfAValidateOptions.add_input` pode ser chamado mais de uma vez?

Sim — cada chamada adiciona outra entrada à lista inputs, e retorna self, portanto as chamadas podem ser encadeadas: options.add_input("a.pdf").add_input("b.pdf").

O `close()` é diferente de `dispose()` no `Document` gerado?

Não — close() é um alias direto que chama dispose() com os mesmos argumentos; qualquer um dos nomes libera os recursos do documento.