Como Carregar um Documento em Python

Aspose.PDF FOSS para Python carrega um PDF a partir de um caminho de arquivo, bytes brutos ou um fluxo binário em um objeto Document que você pode inspecionar e manipular. A biblioteca é puro Python e instala com um único comando.

Guia Passo a Passo

Etapa 2: Importar Classes Necessárias

Importe Document para carregar e manter um PDF, além das classes de exceção que você lidará quando uma carga falhar:

from aspose_pdf import (
    Document,
    InvalidPasswordException,
    InvalidPdfFileFormatException,
    PdfCorruptedError,
    PdfParseException,
)

Etapa 3: Carregar um PDF a partir de um Caminho de Arquivo

Passe um caminho de arquivo diretamente ao construtor Document, ou chame load_from explicitamente em uma instância existente — ambos aceitam um caminho, bytes, ou um fluxo binário. Use Document como um gerenciador de contexto para que os manipuladores de arquivo subjacentes sejam liberados automaticamente:

from aspose_pdf import Document

with Document("report.pdf") as document:
    print(f"Loaded {document.page_count} page(s)")

A forma do construtor Document(source) é equivalente a Document().load_from(source):

document = Document()
document.load_from("report.pdf")
print(f"Loaded {document.page_count} page(s)")
document.close()

Etapa 4: Carregar um PDF protegido por senha

Tanto Document(source, password=...) quanto Document.load_from(source, password, limits) aceitam um argumento password para PDFs criptografados com uma senha de usuário:

from aspose_pdf import Document

with Document("locked.pdf", password="secret") as document:
    print(f"Opened encrypted document: {document.page_count} page(s)")
    print(f"Encrypted: {document.is_encrypted}")

Se a origem não estiver protegida por senha, omita o argumento — passar password=None (o padrão) funciona também para PDFs comuns.

Etapa 5: Tratar exceções de carregamento

Um arquivo ausente, dados que não são PDF, uma senha ausente ou incorreta, ou um PDF corrompido nunca retornam um Document silenciosamente vazio — ele gera uma exceção em vez disso. Capture as classes de exceção específicas para reagir adequadamente:

from aspose_pdf import (
    Document,
    InvalidPasswordException,
    InvalidPdfFileFormatException,
    PdfCorruptedError,
    PdfParseException,
)

try:
    document = Document("report.pdf", password="maybe-wrong")
except InvalidPasswordException:
    print("The PDF is encrypted; supply the correct password.")
except InvalidPdfFileFormatException:
    print("The file is not a valid PDF.")
except PdfCorruptedError as error:
    print(f"Unrecoverable corruption at offset {error.offset}: {error.message}")
except PdfParseException as error:
    print(f"Could not parse the PDF: {error}")
else:
    print(f"Loaded {document.page_count} page(s)")
    document.close()

PdfCorruptedError e seu irmão PdfMalformedError ambos possuem propriedades message, offset e recoverable, o que é útil para registrar exatamente onde um arquivo quebrado falhou ao ser analisado. Ao processar entrada não confiável, também capture PdfResourceLimitException, que é gerada quando um documento excederia a política de segurança padrão PdfLoadLimits (tamanho da entrada, contagem de objetos, tamanho do fluxo decodificado e limites semelhantes).

Etapa 7: Liberar recursos do documento

Usando Document como um gerenciador de contexto (with Document(...) as document:) fecha o documento automaticamente quando o bloco termina. Quando você cria um Document fora de um bloco with, chame close() ou dispose() explicitamente quando terminar com ele:

document = Document()
document.load_from("report.pdf")
try:
    print(document.page_count)
finally:
    document.close()

Problemas Comuns e Correções

InvalidPasswordException é gerada mesmo que eu não acreditasse que o arquivo estivesse criptografado

O PDF de origem tem uma senha de usuário definida. Confirme isso com a origem do arquivo, então passe o valor correto como argumento password para Document(...) ou load_from(...).

InvalidPdfFileFormatException em um arquivo que parece estar correto

O arquivo não é um PDF válido — pode ser uma página de erro HTML, um download truncado ou um formato diferente salvo com extensão .pdf. Abra o arquivo em um editor de texto e confirme que ele começa com %PDF-.

PdfCorruptedError em um arquivo que abre em outros visualizadores

Alguns leitores de PDF reparam estruturas quebradas silenciosamente. Document gera PdfCorruptedError para corrupção irrecuperável e PdfMalformedError para problemas estruturais recuperáveis — inspecione a propriedade offset na exceção para localizar a área problemática no fluxo de bytes.

PdfResourceLimitException em um PDF grande ou complexo

O documento excedeu um limite padrão de PdfLoadLimits (tamanho da entrada, contagem de objetos, tamanho do fluxo decodificado e limites semelhantes projetados para proteger contra entrada não confiável). Construa um PdfLoadLimits personalizado e passe-o como limits= para Document(...) ou load_from(...) se o arquivo for confiável e limites maiores forem apropriados.

Esquecer de fechar um Document aberto fora de um with block

Chame document.close() (ou document.dispose()) quando terminar, ou carregue o arquivo com with Document(source) as document: para que a limpeza ocorra automaticamente mesmo que uma exceção ocorra dentro do bloco.

Perguntas Frequentes

O que posso passar como argumento `source` ao carregar um PDF?

Document(source) e Document.load_from(source, password, limits) aceitam um caminho de arquivo, bytes bruto, ou qualquer fluxo binário.

Como faço para carregar um PDF que já está na memória em vez de no disco?

Passe o objeto bytes diretamente: Document(pdf_bytes), ou chame document.load_from(pdf_bytes) em uma instância existente de Document.

Carregar um PDF requer a senha correta logo no início, ou posso verificar primeiro?

is_encrypted só está disponível após um carregamento bem-sucedido, portanto um PDF criptografado deve ser aberto com o argumento password correto na mesma chamada. Capture InvalidPasswordException se precisar solicitar uma senha interativamente.