Introdução
Aspose.PDF FOSS para Python centra-se na classe Document, que expõe pages, form, outlines, tagged_content e attachments como pontos de entrada para edição estrutural e a nível de documento. Além de adicionar conteúdo de página, a biblioteca cobre as operações que tornam um PDF um artefato completo e distribuível: campos de formulário interativos que coletam e expõem dados estruturados, anexos de arquivos a nível de documento, descoberta e incorporação de fontes para autoria de texto, e uma árvore de marcadores para navegação. Cada uma dessas áreas gera erros através de uma única hierarquia de exceções enraizada em AsposePdfException, permitindo que os chamadores capturem falhas específicas do pacote sem adivinhar os tipos de exceção módulo por módulo.
Este guia mostra como trabalhar com essa camada de gerenciamento de documentos: capturar e distinguir subclasses de AsposePdfException, criar e ler campos AcroForm com Form e Field, incorporar e recuperar anexos através de FileSpecification, resolver fontes com FontRepository e FontRegistry, e construir uma árvore de marcadores com OutlineCollection e OutlineItem. Cada seção usa apenas as classes e métodos presentes no pacote atual.
Aspose.PDF FOSS para Python é um pacote Python, aspose-pdf-foss-for-python, lançado sob a licença MIT, exigindo Python 3.11 ou superior. Seu nome de módulo de nível superior é aspose_pdf. O pacote central depende somente de cryptography e asn1crypto; extras opcionais adicionam decodificação de imagens baseada em Pillow, suporte a fontes WOFF2 baseado em Brotli, e layout de texto complexo baseado em HarfBuzz.
Recursos Principais
Tratamento de Exceções com AsposePdfException
Todo erro específico do pacote em Aspose.PDF FOSS para Python deriva de AsposePdfException. A maioria das falhas de processamento de documentos se enquadra em sua subclasse PdfException, que por sua vez serve de base para PdfParseException (entrada malformada), PdfSecurityException (falhas de criptografia e senha, incluindo InvalidPasswordException), e PdfValidationException (falhas estruturais ou de conformidade). Capturar AsposePdfException por último, após as subclasses mais específicas, permite que o chamador reaja de forma diferente a uma senha incorreta do que a um arquivo corrompido, mantendo ainda um único fallback para todo o resto que o pacote pode gerar.
from aspose_pdf import Document
from aspose_pdf.exceptions import (
AsposePdfException,
InvalidPasswordException,
PdfParseException,
)
def open_document(path, password=None):
try:
document = Document()
document.load_from(path, password=password)
return document
except InvalidPasswordException:
print(f"{path}: a correct password is required")
except PdfParseException as error:
print(f"{path}: not a valid PDF ({error})")
except AsposePdfException as error:
# Catches every other aspose_pdf-specific error not handled above.
print(f"{path}: PDF operation failed ({error})")
return None
Campos de Formulário Interativos
Document.form retorna uma fachada Form sobre os campos AcroForm do documento. Form.add_text_field(), add_checkbox() e add_radio_group() criam novos campos terminais vinculados a uma página e a um retângulo de widget, cada um retornando um Field. Field expõe name, value e field_type para que campos existentes possam ser inspecionados e atualizados por nome, e Field.remove() exclui um campo completamente.
from aspose_pdf import Document
with Document() as document:
page = document.pages.add()
document.form.add_text_field("customer_name", page, (72, 700, 300, 720))
document.form.add_checkbox("subscribe", page, (72, 670, 90, 688), on_value="Yes")
document.form.add_radio_group(
"plan",
page,
{"Basic": (72, 630, 90, 648), "Pro": (72, 600, 90, 618)},
value="Basic",
)
for field in document.form.fields:
print(field.name, field.field_type, field.value)
for field in document.form.fields:
if field.name == "customer_name":
field.value = "Jane Doe"
document.form.generate_appearances()
document.save("form.pdf")
Arquivos Incorporados e Anexos
Document.add_attachment incorpora bytes como um anexo de arquivo ao nível do documento, gravado na árvore de nomes /Names /EmbeddedFiles do PDF ao salvar, junto com um tipo MIME opcional, descrição e datas de criação/modificação. Document.embedded_files lê cada anexo de volta como um FileSpecification tipado (name, contents, mime_type, description, size), e Document.get_embedded_file procura um por nome. FileSpecification.save() grava os bytes recuperados no disco.
from aspose_pdf import Document
with Document() as document:
document.pages.add()
document.add_attachment(
"notes.txt",
b"Reviewed and approved.",
mime="text/plain",
description="Reviewer notes",
)
document.save("with-attachment.pdf")
with Document() as document:
document.load_from("with-attachment.pdf")
for spec in document.embedded_files:
print(spec.name, spec.mime_type, spec.size)
notes = document.get_embedded_file("notes.txt")
if notes is not None:
notes.save("notes-recovered.txt")
Descoberta e Incorporação de Fontes
FontRepository agrega fontes de origem e resolve fontes por nome em todo o documento. FontRepository.add_source() registra um FontSource como FolderFontSource (varre um diretório, opcionalmente de forma recursiva); FontRepository.find_font() e search() então resolvem uma fonte por família, nome completo ou PostScript, recorrendo ao registro de fontes padrão. Cada correspondência é um FontDescriptor, que pode ser passado diretamente para Page.add_text para incorporar e fazer subset da fonte. FontRegistry mapeia nomes não padrão comuns (Arial, Times New Roman e similares) para o equivalente mais próximo do Standard-14 através de search_font_by_name().
from aspose_pdf import Document, FolderFontSource, FontRepository
from aspose_pdf.font_registry import FontRegistry
FontRepository.add_source(FolderFontSource("./fonts", scan_subdirectories=True))
descriptor = FontRepository.find_font("Open Sans")
if descriptor is None:
# Fall back to the closest Standard-14 match for a common font name.
descriptor = FontRegistry().search_font_by_name("Arial")
with Document() as document:
page = document.pages.add()
page.add_text(
"Rendered with a resolved font",
x=72,
y=700,
font_size=14,
font=descriptor,
)
document.save("font-sample.pdf")
Esquemas de Documento e Marcadores
Document.outlines retorna um OutlineCollection, o contêiner de nível superior para a árvore de marcadores de um PDF. OutlineCollection.add adiciona um OutlineItem de nível superior; OutlineItem.add() aninha um marcador filho sob um existente. Cada OutlineItem contém um title, um page_index alvo, e flags de exibição is_bold / is_italic, e expõe sua própria lista de children.
from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem
with Document() as document:
document.pages.add()
document.pages.add()
chapter = OutlineItem("Chapter 1: Overview", page_index=0)
document.outlines.add(chapter)
chapter.add(OutlineItem("Section 1.1", page_index=0, is_italic=True))
document.outlines.add(OutlineItem("Chapter 2: Details", page_index=1, is_bold=True))
document.save("bookmarked.pdf")
Início rápido
Instale o pacote e, em seguida, crie um documento que combine um marcador, metadados do documento e um anexo em um único script.
git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem
with Document() as document:
page = document.pages.add()
page.add_text("Quarterly Report", x=72, y=740, font_size=20)
document.outlines.add(OutlineItem("Quarterly Report", page_index=0))
document.info = {"Title": "Quarterly Report"}
document.add_attachment(
"source-data.csv", b"quarter,total\nQ1,1000\n", mime="text/csv"
)
document.save("report.pdf")
with Document() as reopened:
reopened.load_from("report.pdf")
print(reopened.page_count, "page(s),", reopened.info.get("Title"))
print([spec.name for spec in reopened.embedded_files])
Formatos suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| Sim | Sim | ||
| TIFF | tiff | - | Sim |
Page.render, Page.save_as_image, e Document.save_page_as_image também produzem saída raster PNG ao lado de TIFF.
Essas são saídas de rasterização de página, e não formatos de carregamento de documento.
Código aberto & Licenciamento
Aspose.PDF FOSS para Python é lançado sob a licença MIT: sem restrições de uso, sem taxas de tempo de execução e sem requisitos de registro para uso comercial ou pessoal. O código-fonte está hospedado em github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, e o pacote é publicado em PyPI como aspose-pdf-foss-for-python.
