Skip to content
PDF Oxide

Referência da API Python

O PDF Oxide oferece bindings nativos de Python construídos com PyO3. Há wheels pré-compilados disponíveis para Python 3.8–3.14 em Linux, macOS e Windows (x86_64 e ARM64).

pip install pdf_oxide

Para a API Rust, consulte a Referência da API Rust. Para a API JavaScript, consulte a Referência da API JavaScript (Node.js) ou a Referência da API JavaScript (WASM). Para detalhes de tipos, consulte Tipos e Enums.

PdfDocument

A classe principal para abrir, extrair, editar e salvar arquivos PDF.

from pdf_oxide import PdfDocument

Construtor

PdfDocument(path: str, password: str | None = None)
Parâmetro Tipo Descrição
path str Caminho para o arquivo PDF
password str | None Senha opcional para PDFs criptografados (padrão: None)

Passe password= para abrir PDFs criptografados em uma única etapa. Como alternativa, você também pode usar doc.authenticate(password) após abrir o arquivo.

Lança FileNotFoundError se o arquivo não existir. Lança PdfError se o arquivo não for um PDF válido.

Métodos de Classe

PdfDocument.from_bytes(data: bytes, password: str | None = None) -> PdfDocument

Abre um PDF a partir de bytes em memória (por exemplo, baixado do S3, recebido via HTTP). Aceita uma senha opcional para PDFs criptografados.

Parâmetro Tipo Descrição
data bytes Bytes brutos do arquivo PDF
password str | None Senha opcional para PDFs criptografados (padrão: None) 
from pdf_oxide import PdfDocument

# Open PDF from bytes (e.g., downloaded from S3)
doc = PdfDocument.from_bytes(pdf_bytes)

# Also supports password:
doc = PdfDocument.from_bytes(pdf_bytes, password="secret")

Métodos

Geral

Método Tipo de Retorno Descrição
version() tuple[int, int] Versão do PDF como (major, minor) (ex.: (1, 7))
authenticate(password) bool Autentica um PDF criptografado com a senha de usuário ou de proprietário

Informações do Documento

doc.page_count() -> int

Retorna o número de páginas do documento.

doc.has_structure_tree() -> bool

Verifica se o documento é um Tagged PDF com árvore de estrutura.

Autenticação

doc.authenticate(password: str) -> bool

Autentica com uma senha após abrir o arquivo. Retorna True se a autenticação for bem-sucedida.

Extração de Texto

doc.extract_text(
    page: int,
    region: tuple[float, float, float, float] | None = None,
    exclude_layers: list[str] | None = None,
    exclude_inks: list[str] | None = None,
    extract_tables: bool = True
) -> str

Extrai texto puro de uma única página. As páginas têm índice baseado em zero. Opcionalmente, recorte para uma region, exclua camadas de conteúdo opcional (optional-content) nomeadas ou nomes de tintas/separações, e ative ou desative a reconstrução de tabelas.

doc.extract_chars(
    page: int,
    region: tuple[float, float, float, float] | None = None,
    exclude_layers: list[str] | None = None,
    exclude_inks: list[str] | None = None
) -> list[TextChar]

Extrai o posicionamento por caractere e os metadados de fonte. Retorna uma lista de objetos TextChar.

doc.extract_spans(page: int, region: tuple | None = None, reading_order: str | None = None) -> list[TextSpan]

Extrai spans de texto com metadados de fonte. Cada span é uma sequência de texto com estilo idêntico. Passe reading_order="column_aware" para PDFs com múltiplas colunas.

doc.extract_words(
    page: int,
    *,
    include_artifacts: bool = True,
    region: tuple | None = None,
    word_gap_threshold: float | None = None,
    profile: ExtractionProfile | None = None
) -> list[TextWord]

Extrai texto agrupado por palavras com caixas delimitadoras. Retorna uma lista de objetos TextWord.

doc.extract_text_lines(
    page: int,
    *,
    include_artifacts: bool = True,
    region: tuple | None = None,
    word_gap_threshold: float | None = None,
    line_gap_threshold: float | None = None,
    profile: ExtractionProfile | None = None
) -> list[TextLine]

Extrai texto agrupado por linhas. Retorna uma lista de objetos TextLine.

doc.extract_page_text(page: int, reading_order: str | None = None) -> dict

Extrai spans, caracteres e dimensões da página em uma única passagem. Retorna um dict com as chaves: spans, chars, page_width, page_height, text. Mais eficiente do que chamar extract_spans() + extract_chars() separadamente.

doc.page_layout_params(page: int) -> LayoutParams

Calcula parâmetros de layout adaptativos (limiares de espaçamento entre palavras/linhas, métricas medianas, contagem de colunas) para uma página. Consulte LayoutParams.

doc.within(page: int, bbox: tuple[float, float, float, float]) -> PdfPageRegion

Cria um handle de região recortada para extrair texto, palavras, linhas, tabelas, imagens e caminhos dentro de bbox. Consulte PdfPageRegion.

Extração Automática e Classificação

doc.extract_text_auto(page: int) -> str

Seleciona automaticamente a melhor estratégia de extração (texto nativo vs. OCR) para uma página e retorna texto puro.

doc.extract_page_auto(page: int, options_json: str | None = None) -> str

Extrai uma página automaticamente e retorna um documento JSON; passe uma string options_json em JSON para ajustar o pipeline.

doc.classify_page(page: int) -> str

Classifica uma única página (ex.: "text", "scanned", "mixed").

doc.classify_document() -> str

Classifica o documento inteiro amostrando suas páginas.

doc.has_text_layer(page: int) -> bool

Verifica se uma página já possui uma camada de texto nativo extraível (em vez de exigir OCR).

Conversão

doc.to_plain_text(
    page: int,
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None
) -> str

Converte uma página para texto puro com opções de layout.

doc.to_plain_text_all(
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None
) -> str

Converte todas as páginas para texto puro.

doc.to_markdown(
    page: int,
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Converte uma página para Markdown.

doc.to_markdown_all(
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Converte todas as páginas para Markdown.

doc.to_html(
    page: int,
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Converte uma página para HTML.

doc.to_html_all(
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Converte todas as páginas para HTML.

Conversão para Office

Método Tipo de Retorno Descrição
to_docx(path) – Converte o PDF em um arquivo de documento do Word
to_docx_bytes() bytes Converte o PDF em bytes DOCX
to_pptx(path) – Converte o PDF em um arquivo do PowerPoint
to_pptx_bytes() bytes Converte o PDF em bytes PPTX
to_xlsx(path) – Converte o PDF em um arquivo de pasta de trabalho do Excel
to_xlsx_bytes() bytes Converte o PDF em bytes XLSX

Extração de Imagens

doc.extract_images(page: int) -> list[ImageInfo]

Extrai todas as imagens de uma página, incluindo imagens em content streams e Form XObjects aninhados.

doc.extract_image_bytes(page: int) -> list[dict]

Extrai os bytes brutos de imagem de uma página. Cada dict contém width, height, data (bytes) e format.

Busca

doc.search(
    pattern: str,
    case_insensitive: bool = False,
    literal: bool = False,
    whole_word: bool = False,
    max_results: int = 0
) -> list[SearchResult]

Busca texto em todas as páginas. Defina max_results=0 para resultados ilimitados. Retorna uma lista de correspondências com número da página, texto e coordenadas.

doc.search_page(
    page: int,
    pattern: str,
    case_insensitive: bool = False,
    literal: bool = False,
    whole_word: bool = False,
    max_results: int = 0
) -> list[SearchResult]

Busca texto em uma única página.

Edição de Metadados

Método Parâmetros Descrição
set_title(title) str Define o título do documento
set_author(author) str Define o autor do documento
set_subject(subject) str Define o assunto do documento
set_keywords(keywords) str Define as palavras-chave do documento

Rotação de Páginas

Método Parâmetros Retorna Descrição
page_rotation(page) int int Obtém a rotação atual (0, 90, 180, 270)
set_page_rotation(page, degrees) int, int – Define a rotação absoluta
rotate_page(page, degrees) int, int – Adiciona à rotação atual
rotate_all_pages(degrees) int – Rotaciona todas as páginas

Dimensões de Página

Método Parâmetros Retorna Descrição
page_media_box(page) int tuple[float, float, float, float] Obtém o MediaBox (llx, lly, urx, ury)
set_page_media_box(page, llx, lly, urx, ury) int, float, float, float, float – Define o MediaBox
page_crop_box(page) int `tuple None`
set_page_crop_box(page, llx, lly, urx, ury) int, float, float, float, float – Define o CropBox
crop_margins(left, right, top, bottom) float, float, float, float – Recorta todas as margens da página

Apagar / Whiteout

Método Parâmetros Descrição
erase_region(page, llx, lly, urx, ury) int, float, float, float, float Apaga uma região retangular
erase_regions(page, rects) int, list[tuple] Apaga múltiplas regiões
clear_erase_regions(page) int Limpa as operações de apagamento pendentes

Anotações

doc.get_annotations(page: int) -> list[dict]

Obtém os metadados das anotações (tipo, rect, conteúdo, etc.) de uma página.

Método Parâmetros Retorna Descrição
flatten_page_annotations(page) int – Achata (flatten) as anotações de uma página
flatten_all_annotations() – – Achata todas as anotações
is_page_marked_for_flatten(page) int bool Verifica se a página está marcada para achatamento
unmark_page_for_flatten(page) int – Desmarca uma página para achatamento

Redação

doc.add_redaction(
    page: int,
    rect: tuple[float, float, float, float],
    fill: tuple[float, float, float] | None = None
) -> None

Marca uma região retangular para redação com uma cor de preenchimento RGB opcional.

doc.redaction_count(page: int) -> int

Retorna o número de redações pendentes em uma página.

doc.apply_redactions_destructive(
    scrub_metadata: bool = True,
    remove_javascript: bool = True,
    remove_embedded_files: bool = True,
    fill: tuple[float, float, float] = (0.0, 0.0, 0.0)
) -> None

Aplica todas as redações de forma destrutiva, removendo o conteúdo subjacente e, opcionalmente, limpando metadados, JavaScript e arquivos embutidos.

doc.sanitize_document(
    scrub_metadata: bool = True,
    remove_javascript: bool = True,
    remove_embedded_files: bool = True
) -> None

Sanitiza o documento sem redigir regiões: remove metadados, JavaScript e/ou arquivos embutidos.

Método Parâmetros Retorna Descrição
apply_page_redactions(page) int – Aplica as redações em uma página
apply_all_redactions() – – Aplica todas as redações pendentes
is_page_marked_for_redaction(page) int bool Verifica se a página está marcada para redação
unmark_page_for_redaction(page) int – Desmarca uma página para redação

Camadas e Tintas

Método Parâmetros Retorna Descrição
get_layers() – list[str] Lista os nomes das camadas de conteúdo opcional (OCG)
get_page_inks(page) int list[str] Lista os nomes dos colorantes de tinta / separação em uma página
get_page_inks_deep(page) int list[str] Lista as tintas, incluindo as aninhadas em Form XObjects

Limpeza de Cabeçalho / Rodapé

doc.remove_headers(threshold: float = 0.8) -> int
doc.remove_footers(threshold: float = 0.8) -> int
doc.remove_artifacts(threshold: float = 0.8) -> int

Detecta e remove cabeçalhos, rodapés ou artefatos de página repetidos ao longo do documento. threshold é a razão de repetição entre páginas. Retorna o número de elementos removidos.

Método Parâmetros Descrição
erase_header(page) int Apaga a região de cabeçalho detectada em uma página
edit_header(page) int Marca a região de cabeçalho para edição
erase_footer(page) int Apaga a região de rodapé detectada em uma página
edit_footer(page) int Marca a região de rodapé para edição
erase_artifacts(page) int Apaga os artefatos detectados em uma página
sync_editor_erasures() – Descarrega os apagamentos pendentes de cabeçalho/rodapé/artefato no editor

Campos de Formulário

doc.get_form_fields() -> list[FormField]

Obtém todos os campos de formulário. Consulte FormField para ver as propriedades.

doc.get_form_field_value(name: str) -> str | bool | list | None

Obtém o valor de um campo de formulário pelo nome. Retorna o tipo Python apropriado com base no tipo do campo.

doc.set_form_field_value(name: str, value: str | bool) -> None

Define o valor de um campo de formulário pelo nome.

doc.has_xfa() -> bool

Verifica se o documento contém formulários XFA.

doc.export_form_data(path: str, format: str = "fdf") -> None

Exporta os dados do formulário para um arquivo. Formatos suportados: "fdf" e "xfdf".

Método Parâmetros Descrição
flatten_forms() – Achata todos os campos de formulário no conteúdo da página
flatten_forms_on_page(page) int Achata os formulários em uma página específica

Manipulação de Imagens

doc.page_images(page: int) -> list[dict]

Obtém os nomes e os limites das imagens para operações de posicionamento. Cada dict contém name, bounds [x, y, width, height] e matrix.

Método Parâmetros Descrição
reposition_image(page, name, x, y) int, str, float, float Move uma imagem
resize_image(page, name, width, height) int, str, float, float Redimensiona uma imagem
set_image_bounds(page, name, x, y, width, height) int, str, float, float, float, float Define a posição e o tamanho da imagem
clear_image_modifications(page) int Limpa as modificações de imagem pendentes
has_image_modifications(page) int → bool Verifica se há modificações de imagem pendentes

Operações de Documento

doc.merge_from(source: str | PdfDocument) -> int

Mescla páginas de outro PDF. Aceita um caminho de arquivo ou uma instância de PdfDocument. Retorna o número de páginas mescladas.

doc.embed_file(name: str, data: bytes) -> None

Anexa um arquivo ao PDF.

doc.get_outline() -> list[dict] | None

Obtém os marcadores / sumário do documento. Retorna None se não houver outline.

doc.extract_paths(page: int, region: tuple | None = None) -> list[dict]

Obtém os caminhos vetoriais (linhas, curvas, formas) de uma página.

doc.extract_rects(page: int, region: tuple | None = None) -> list[dict]

Obtém os retângulos alinhados aos eixos (de caminhos preenchidos/traçados) em uma página.

doc.extract_lines(page: int, region: tuple | None = None) -> list[dict]

Obtém os segmentos de linha retos em uma página.

doc.extract_tables(page: int, region: tuple | None = None, table_settings: dict | None = None) -> list[dict]

Detecta e extrai tabelas. Cada tabela é um dict com linhas e células (texto + caixas delimitadoras). Passe table_settings para ajustar a estratégia de detecção.

doc.extract_structured(page: int) -> str

Extrai a página como um documento JSON estruturado (ordem lógica de leitura, blocos e papéis).

doc.page_labels() -> list[dict]

Obtém os intervalos de rótulos de página. Cada dict contém start_page, style, prefix e start_value.

doc.xmp_metadata() -> dict | None

Obtém os metadados XMP como um dicionário com campos como dc_title, dc_creator, xmp_create_date, etc. Retorna None se não houver metadados XMP.

OCR

doc.extract_text_ocr(page: int, engine: OcrEngine | None = None) -> str

Extrai texto usando OCR. Requer o recurso ocr no build em Rust. Passe um OcrEngine personalizado ou None para o engine padrão.

Extração e Reordenação de Páginas

doc.extract_pages(pages: list[int], output: str) -> None

Extrai os índices de página fornecidos para um novo arquivo PDF em output.

doc.extract_pages_to_bytes(pages: list[int]) -> bytes

Extrai os índices de página fornecidos para um novo PDF retornado como bytes.

doc.extract_page_ranges_to_bytes(ranges: list[tuple[int, int]]) -> bytes

Extrai um ou mais intervalos de páginas (start, end) para um novo PDF retornado como bytes.

Método Parâmetros Descrição
select_pages(pages) list[int] Mantém apenas as páginas listadas, na ordem fornecida
delete_page(index) int Exclui uma única página
move_page(from_index, to_index) int, int Move uma página para uma nova posição

Conformidade e Validação

doc.validate_pdf_a(level: str = "1b") -> dict

Valida em relação a um nível de conformidade PDF/A (ex.: "1b", "2b", "3b"). Retorna um dict de relatório.

doc.convert_to_pdf_a(level: str = "2b") -> dict

Converte o documento para PDF/A e retorna um dict de relatório de conversão.

doc.validate_pdf_ua() -> dict

Valida em relação aos requisitos do PDF/UA (acessibilidade).

doc.validate_pdf_x(level: str = "1a_2001") -> dict

Valida em relação a um nível de conformidade PDF/X (produção para impressão).

Permissões e Avisos

doc.permissions() -> dict

Retorna os flags de permissão de criptografia do documento (imprimir, copiar, modificar, anotar, etc.).

doc.structured_warnings() -> list

Retorna os avisos coletados durante a extração de conteúdo estruturado / marcado.

doc.flatten_warnings() -> list[str]

Retorna os avisos coletados durante o achatamento de formulários/anotações.

Assinaturas e Document Security Store

doc.signatures() -> list[Signature]

Retorna todas as assinaturas digitais do documento. Consulte Signature.

doc.signature_count() -> int

Retorna o número de assinaturas digitais.

doc.dss() -> Dss | None

Retorna o Document Security Store analisado do documento (material LTV), ou None. Consulte Dss.

API de Páginas (v0.3.34)

PdfDocument é iterável e indexável, retornando objetos Page preguiçosos. Consulte Page.

len(doc)                  # number of pages
doc[i]                    # page at index i (negative indexing supported)
doc[-1]                   # last page
for page in doc: ...      # iterate pages

Acesso ao DOM

doc.page(index: int) -> PdfPage

Obtém um handle de página estilo DOM para edição em nível de elemento. Consulte PdfPage.

doc.save_page(page: PdfPage) -> None

Salva uma PdfPage modificada de volta no documento.

Renderização

doc.render_page(
    page: int,
    dpi: int | None = None,
    format: str | None = None,
    background: tuple[float, float, float, float] | None = None,
    transparent: bool = False,
    render_annotations: bool | None = None,
    jpeg_quality: int | None = None,
    excluded_layers: list[str] | None = None
) -> bytes

Renderiza uma página para bytes PNG ou JPEG, com controle sobre DPI, plano de fundo, transparência, renderização de anotações, qualidade JPEG e camadas excluídas.

doc.render_pixmap(page: int, dpi: int | None = None) -> RenderedPixmap

Renderiza uma página para um RenderedPixmap RGBA bruto (named tuple com width, height, data).

doc.render_separations(page: int, dpi: int | None = None) -> list[SeparationPlate]

Renderiza as chapas de separação por tinta de uma página. Retorna uma lista de named tuples SeparationPlate (name, width, height, data).

doc.render_separation(page: int, ink_name: str, dpi: int | None = None) -> SeparationPlate

Renderiza a chapa de separação de uma única tinta nomeada.

Método Tipo de Retorno Descrição
render_page_fit(page, fit_width, fit_height, format=0) bytes Renderiza uma página dimensionada para caber em uma caixa de pixels
flatten_to_images(dpi=150) bytes Achata todas as páginas em um PDF baseado em imagens

Salvamento

doc.save(path: str, compress: bool = True, garbage_collect: bool = True, linearize: bool = False) -> None

Salva o PDF em um arquivo. Ative ou desative a compressão de streams, a coleta de lixo de objetos mortos e a linearização (fast web view).

doc.to_bytes(compress: bool = True, garbage_collect: bool = True, linearize: bool = False) -> bytes

Serializa o PDF para bytes com as mesmas opções de save().

doc.save_encrypted(
    path: str,
    user_password: str,
    owner_password: str | None = None,
    allow_print: bool = True,
    allow_copy: bool = True,
    allow_modify: bool = True,
    allow_annotate: bool = True
) -> None

Salva com proteção por senha AES-256 e controles de permissão. Se owner_password for None, a senha de usuário é utilizada.

doc.to_bytes_encrypted(
    user_password: str,
    owner_password: str | None = None,
    allow_print: bool = True,
    allow_copy: bool = True,
    allow_modify: bool = True,
    allow_annotate: bool = True
) -> bytes

Serializa um PDF criptografado com AES-256 para bytes.

Page

Um handle de página preguiçoso retornado por doc[i] ou pela iteração sobre PdfDocument. Todas as propriedades são calculadas no acesso e despachadas para o documento pai.

from pdf_oxide import PdfDocument

with PdfDocument("paper.pdf") as doc:
    page = doc[0]
    text = page.text
    md = page.markdown(detect_headings=True)

Propriedades (preguiçosas)

Propriedade Tipo Descrição
index int Índice da página baseado em zero
width, height float Dimensões da página em pontos PDF
bbox tuple[float, 4] (llx, lly, urx, ury)
text str Texto puro extraído
chars, words, lines, spans list[...] Texto estruturado
tables list[dict] Tabelas com linhas + células (texto + bboxes)
images, paths, annotations list[...] Conteúdo da página

Métodos

page.markdown(preserve_layout=False, detect_headings=True,
              include_images=False, image_output_dir=None,
              embed_images=True, include_form_fields=True) -> str
page.plain_text(...) -> str
page.html(...) -> str
page.render(dpi=None, format=None, background=None, transparent=False,
            render_annotations=None, jpeg_quality=None, excluded_layers=None) -> bytes
page.render_pixmap(dpi=None) -> RenderedPixmap
page.search(pattern, case_insensitive=False, literal=False,
            whole_word=False, max_results=100) -> list
page.region(x, y, width, height) -> PdfPageRegion

O objeto de página preguiçoso também é exposto como doc.pages() (um iterador equivalente a iterar o documento diretamente).

PdfPage

Handle de página estilo DOM para acesso e edição em nível de elemento. Obtido via PdfDocument.page().

from pdf_oxide import PdfDocument

doc = PdfDocument("file.pdf")
page = doc.page(0)

Propriedades

Propriedade Tipo Descrição
index int Índice da página baseado em zero
width float Largura da página em pontos PDF
height float Altura da página em pontos PDF

Métodos

page.children() -> list[PdfElement]

Obtém todos os elementos da página.

page.find_text_containing(needle: str) -> list[PdfText]

Encontra todos os elementos de texto que contêm a substring fornecida.

page.find_images() -> list[PdfImage]

Encontra todos os elementos de imagem na página.

page.get_element(element_id: str) -> PdfElement | None

Obtém um elemento específico pelo seu ID.

page.set_text(text_id: PdfTextId, new_text: str) -> None

Substitui o conteúdo de texto de um elemento identificado pelo seu PdfTextId.

page.annotations() -> list[PdfAnnotation]

Obtém todas as anotações da página.

page.add_link(x: float, y: float, width: float, height: float, url: str) -> str

Adiciona uma anotação de link de URL. Retorna o ID da anotação.

page.add_highlight(x: float, y: float, width: float, height: float, color: tuple[float, float, float]) -> str

Adiciona uma anotação de destaque com uma cor RGB. Retorna o ID da anotação.

page.add_note(x: float, y: float, text: str) -> str

Adiciona uma anotação de nota adesiva. Retorna o ID da anotação.

page.remove_annotation(index: int) -> bool

Remove uma anotação por índice. Retorna True se removida.

page.add_text(text: str, x: float, y: float, font_size: float = 12.0) -> PdfTextId

Adiciona novo texto à página. Retorna um PdfTextId para referência posterior.

page.remove_element(element_id: PdfTextId) -> bool

Remove um elemento pelo seu ID. Retorna True se removido.

Exemplo

from pdf_oxide import PdfDocument

doc = PdfDocument("invoice.pdf")
page = doc.page(0)

# Find and replace text
for text in page.find_text_containing("DRAFT"):
    page.set_text(text.id, "FINAL")

# Add a link
page.add_link(100, 700, 200, 20, "https://example.com")

doc.save_page(page)
doc.save("invoice_updated.pdf")

Pdf

A classe unificada para criar PDFs a partir de vários formatos de origem.

from pdf_oxide import Pdf

Métodos de Fábrica

Pdf.from_markdown(content: str, title: str | None = None, author: str | None = None) -> Pdf

Cria um PDF a partir de conteúdo Markdown.

Pdf.from_html(content: str, title: str | None = None, author: str | None = None) -> Pdf

Cria um PDF a partir de conteúdo HTML.

Pdf.from_text(content: str, title: str | None = None, author: str | None = None) -> Pdf

Cria um PDF a partir de texto puro.

Pdf.from_markdown_with_template(content: str, template: str, title: str | None = None, author: str | None = None) -> Pdf

Cria um PDF a partir de Markdown renderizado por meio de um template CSS/layout nomeado.

Pdf.from_image(path: str) -> Pdf

Cria um PDF de uma única página a partir de um arquivo de imagem (JPEG, PNG).

Pdf.from_bytes(data: bytes) -> Pdf

Abre um PDF existente a partir de bytes em memória para modificação. Útil para carregar PDFs baixados do S3, de HTTP ou de bancos de dados.

from pdf_oxide import Pdf

pdf = Pdf.from_bytes(existing_pdf_bytes)
pdf.save("modified.pdf")

Pdf.from_images(paths: list[str]) -> Pdf

Cria um PDF de múltiplas páginas a partir de vários arquivos de imagem, uma página por imagem.

Pdf.from_image_bytes(data: bytes) -> Pdf

Cria um PDF de uma única página a partir de bytes de imagem.

Pdf.merge(paths: list[str]) -> Pdf

Mescla múltiplos arquivos PDF (por caminho) em um único Pdf.

Métodos

pdf.save(path: str) -> None

Salva o PDF em um arquivo.

pdf.to_bytes() -> bytes

Obtém o conteúdo do PDF como bytes.

len(pdf) -> int

Obtém o tamanho do PDF em bytes (via __len__).

PdfText

Representa um elemento de texto em uma página. Retornado por PdfPage.find_text_containing().

Propriedade Tipo Descrição
id PdfTextId Identificador único do elemento
value str Conteúdo de texto
text str Conteúdo de texto (alias de value)
bbox tuple[float, float, float, float] Caixa delimitadora (x0, y0, x1, y1)
font_name str Nome PostScript da fonte
font_size float Tamanho da fonte em pontos
is_bold bool Se o texto está em negrito
is_italic bool Se o texto está em itálico

Métodos

Método Parâmetros Retorna Descrição
contains(needle) str bool Verifica se o texto contém a substring
starts_with(prefix) str bool Verifica se o texto começa com o prefixo
ends_with(suffix) str bool Verifica se o texto termina com o sufixo

PdfImage

Representa um elemento de imagem em uma página. Retornado por PdfPage.find_images().

Propriedade Tipo Descrição
bbox tuple[float, float, float, float] Caixa delimitadora (x0, y0, x1, y1)
width int Largura da imagem em pixels
height int Altura da imagem em pixels
aspect_ratio float Razão largura / altura

PdfAnnotation

Representa uma anotação em uma página. Retornada por PdfPage.annotations().

Propriedade Tipo Descrição
subtype str Tipo de anotação (ex.: "Link", "Highlight", "Text")
rect tuple[float, float, float, float] Posição (x0, y0, x1, y1)
contents `str None`
color `tuple[float, float, float] None`
is_modified bool Se a anotação foi modificada
is_new bool Se a anotação foi adicionada recentemente

PdfElement

Wrapper genérico de elemento. Retornado por PdfPage.children().

Método Retorna Descrição
is_text() bool Verifica se o elemento é texto
is_image() bool Verifica se o elemento é uma imagem
is_path() bool Verifica se o elemento é um caminho vetorial
is_table() bool Verifica se o elemento é uma tabela
is_structure() bool Verifica se o elemento é um elemento de estrutura
as_text() `PdfText None`
as_image() `PdfImage None`
Propriedade Tipo Descrição
bbox tuple[float, float, float, float] Caixa delimitadora

TextChar

Representa um único caractere com posicionamento e metadados de fonte. Retornado por PdfDocument.extract_chars().

from pdf_oxide import TextChar  # or access via PdfDocument
Atributo Tipo Descrição
char str O caractere Unicode
bbox tuple[float, float, float, float] Caixa delimitadora (x0, y0, x1, y1)
font_name str Nome PostScript da fonte
font_size float Tamanho da fonte em pontos
font_weight str Peso ("thin", "light", "normal", "medium", "semi-bold", "bold", "extra-bold", "black")
is_italic bool Se o caractere está em itálico
color tuple[float, float, float] Cor RGB (r, g, b), valores de 0.0–1.0
rotation_degrees float Rotação do caractere em graus
origin_x float Posição X da origem do texto
origin_y float Posição Y da origem do texto
advance_width float Largura de avanço do glifo
mcid `int None`

Exemplo

from pdf_oxide import PdfDocument

doc = PdfDocument("paper.pdf")
chars = doc.extract_chars(0)

for ch in chars[:5]:
    print(f"'{ch.char}' at bbox={ch.bbox} "
          f"font={ch.font_name} size={ch.font_size:.1f} "
          f"weight={ch.font_weight} italic={ch.is_italic}")

TextSpan

Representa uma sequência de texto que compartilha a mesma fonte e estilo. Retornado por PdfDocument.extract_spans().

Atributo Tipo Descrição
text str O conteúdo de texto
bbox tuple[float, float, float, float] Caixa delimitadora (x0, y0, x1, y1)
font_name str Nome PostScript da fonte
font_size float Tamanho da fonte em pontos
is_bold bool Se o span está em negrito
is_italic bool Se o span está em itálico
is_monospace bool Se a fonte é de largura fixa (Courier, Consolas, etc.)
char_widths list[float] Larguras de avanço por glifo para caixas delimitadoras precisas
color tuple[float, float, float] Cor RGB (r, g, b), valores de 0.0–1.0

Exemplo

from pdf_oxide import PdfDocument

doc = PdfDocument("paper.pdf")
spans = doc.extract_spans(0)

for span in spans:
    print(f"'{span.text}' font={span.font_name} size={span.font_size:.1f} "
          f"bold={span.is_bold} italic={span.is_italic} color={span.color}")

Extração de Imagens

extract_images() retorna objetos ImageInfo com metadados de imagem. Use extract_image_bytes() para obter os dados brutos de imagem adequados para salvar em disco.

Formato de Retorno de extract_image_bytes()

Cada dict retornado por extract_image_bytes() tem as seguintes chaves:

Chave Tipo Descrição
width int Largura da imagem em pixels
height int Altura da imagem em pixels
data bytes Dados brutos da imagem
format str Formato da imagem (ex.: "png", "jpeg")

Exemplo

from pdf_oxide import PdfDocument

doc = PdfDocument("brochure.pdf")
images = doc.extract_image_bytes(0)

for i, img in enumerate(images):
    print(f"Image {i}: {img['width']}x{img['height']}")
    with open(f"image_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

SearchResult

Representa uma correspondência de busca de texto. Retornado por search() e search_page().

Atributo Tipo Descrição
page int Índice da página baseado em zero
text str Texto correspondente
x float Posição X em pontos PDF
y float Posição Y em pontos PDF

FormField

Representa um campo de formulário. Retornado por PdfDocument.get_form_fields().

Propriedade Tipo Descrição
name str Nome totalmente qualificado do campo
field_type str Tipo do campo: "text", "button", "choice", "signature" ou "unknown"
value `str bool
tooltip `str None`
bounds `tuple[float, float, float, float] None`
flags `int None`
max_length `int None`
is_readonly bool Se o campo é somente leitura
is_required bool Se o campo é obrigatório

TextWord

Uma sequência de texto agrupada por palavra. Retornada por PdfDocument.extract_words() e PdfPageRegion.extract_words().

Propriedade Tipo Descrição
text str O texto da palavra
bbox tuple[float, float, float, float] Caixa delimitadora (x0, y0, x1, y1)
font_name str Nome PostScript da fonte
font_size float Tamanho da fonte em pontos
is_bold bool Se a palavra está em negrito
is_italic bool Se a palavra está em itálico
chars list[TextChar] Caracteres constituintes

TextLine

Uma sequência de texto agrupada por linha. Retornada por PdfDocument.extract_text_lines() e PdfPageRegion.extract_text_lines().

Propriedade Tipo Descrição
text str O texto da linha
bbox tuple[float, float, float, float] Caixa delimitadora (x0, y0, x1, y1)
words list[TextWord] Palavras da linha
chars list[TextChar] Caracteres da linha

PdfPageRegion

Uma região recortada de uma página. Retornada por PdfDocument.within() e PdfPage.region().

Propriedade Tipo Descrição
bbox tuple[float, float, float, float] Os limites da região

Métodos

region.extract_text() -> str
region.extract_words() -> list[TextWord]
region.extract_text_lines() -> list[TextLine]
region.extract_tables(table_settings: dict | None = None) -> list[dict]
region.extract_images() -> list
region.extract_paths() -> list

Métodos de extração restritos à caixa delimitadora da região.

LayoutParams

Parâmetros de layout adaptativos calculados para uma página. Retornados por PdfDocument.page_layout_params().

Propriedade Tipo Descrição
word_gap_threshold float Limiar de espaçamento entre palavras em pontos
line_gap_threshold float Limiar de espaçamento entre linhas em pontos
median_char_width float Largura mediana de caractere
median_font_size float Tamanho mediano de fonte
median_line_spacing float Espaçamento mediano entre linhas
column_count int Número detectado de colunas de texto

ExtractionProfile

Um perfil de extração de texto ajustável passado para extract_words() / extract_text_lines().

from pdf_oxide import ExtractionProfile

Construtores Estáticos

ExtractionProfile.conservative()
ExtractionProfile.aggressive()
ExtractionProfile.balanced()
ExtractionProfile.academic()
ExtractionProfile.policy()
ExtractionProfile.form()
ExtractionProfile.government()
ExtractionProfile.scanned_ocr()
ExtractionProfile.adaptive()
ExtractionProfile.available() -> list[str]   # names of all built-in profiles

Propriedades

Propriedade Tipo Descrição
name str Nome do perfil
tj_offset_threshold float Limiar de quebra de palavra por offset de array TJ
word_margin_ratio float Razão de margem de palavra
space_threshold_em_ratio float Limiar de largura de espaço (razão em)
space_char_multiplier float Multiplicador de caractere de espaço
use_adaptive_threshold bool Se os limiares adaptativos estão habilitados

OfficeConverter

Converte documentos do Office (DOCX, XLSX, PPTX) para PDF. Requer o recurso office no build em Rust.

from pdf_oxide import OfficeConverter

OfficeConverter()   # instances are stateless; the conversion methods are also usable as static methods

Métodos

OfficeConverter.from_docx(path: str) -> Pdf

Converte um documento do Word em um objeto Pdf.

OfficeConverter.from_docx_bytes(data: bytes) -> Pdf

Converte bytes de documento do Word em um objeto Pdf.

OfficeConverter.from_xlsx(path: str) -> Pdf

Converte uma planilha do Excel em um objeto Pdf.

OfficeConverter.from_xlsx_bytes(data: bytes) -> Pdf

Converte bytes de planilha do Excel em um objeto Pdf.

OfficeConverter.from_pptx(path: str) -> Pdf

Converte uma apresentação do PowerPoint em um objeto Pdf.

OfficeConverter.from_pptx_bytes(data: bytes) -> Pdf

Converte bytes de apresentação do PowerPoint em um objeto Pdf.

OfficeConverter.convert(path: str) -> Pdf

Detecta o formato automaticamente e converte qualquer documento do Office suportado em um objeto Pdf.

Exemplo

from pdf_oxide import OfficeConverter

pdf = OfficeConverter.from_docx("report.docx")
pdf.save("report.pdf")

# Or use convert() for auto-detection
pdf = OfficeConverter.convert("spreadsheet.xlsx")
pdf.save("spreadsheet.pdf")

Classes de Gráficos

Estas classes estão disponíveis para a criação avançada de PDFs com gráficos:

Color

from pdf_oxide import Color

Color(r: float, g: float, b: float)  # RGB, values 0.0-1.0
Color.from_hex("#ff0000")
Color.black()
Color.white()
Color.red()
Color.green()
Color.blue()

BlendMode

from pdf_oxide import BlendMode

BlendMode.NORMAL()
BlendMode.MULTIPLY()
BlendMode.SCREEN()
BlendMode.OVERLAY()
BlendMode.DARKEN()
BlendMode.LIGHTEN()
BlendMode.COLOR_DODGE()
BlendMode.COLOR_BURN()
BlendMode.HARD_LIGHT()
BlendMode.SOFT_LIGHT()
BlendMode.DIFFERENCE()
BlendMode.EXCLUSION()

ExtGState

from pdf_oxide import ExtGState

gs = ExtGState()
gs = gs.fill_alpha(0.5)
gs = gs.stroke_alpha(0.8)
gs = gs.alpha(0.5)  # Set both fill and stroke
gs = gs.blend_mode(BlendMode.MULTIPLY())

gs = ExtGState.semi_transparent()  # Preset

LineCap / LineJoin

from pdf_oxide import LineCap, LineJoin

LineCap.BUTT()       # Default
LineCap.ROUND()
LineCap.SQUARE()

LineJoin.MITER()     # Default
LineJoin.ROUND()
LineJoin.BEVEL()

Gradientes

from pdf_oxide import LinearGradient, RadialGradient, Color

# Linear gradient (fluent API)
grad = (LinearGradient()
    .start(0, 0)
    .end(100, 0)
    .add_stop(0.0, Color.red())
    .add_stop(1.0, Color.blue()))

# Convenience constructors
hgrad = LinearGradient.horizontal(200, Color.red(), Color.blue())
vgrad = LinearGradient.vertical(100, Color(1, 1, 0), Color(0, 0, 1))

# Radial gradient
rgrad = RadialGradient.centered(50, 50, 50)
rgrad = rgrad.add_stop(0.0, Color(1, 1, 0))
rgrad = rgrad.add_stop(1.0, Color(1, 0, 0))

PatternPresets

from pdf_oxide import PatternPresets, Color

PatternPresets.horizontal_stripes(width, height, stripe_height, color)
PatternPresets.vertical_stripes(width, height, stripe_width, color)
PatternPresets.checkerboard(size, color1, color2)
PatternPresets.dots(spacing, radius, color)
PatternPresets.diagonal_lines(size, line_width, color)
PatternPresets.crosshatch(size, line_width, color)

Classes de OCR

Requer o recurso ocr no build em Rust.

OcrEngine

from pdf_oxide import OcrEngine, OcrConfig

engine = OcrEngine(
    det_model_path: str,
    rec_model_path: str,
    dict_path: str,
    config: OcrConfig | None = None
)

OcrConfig

from pdf_oxide import OcrConfig

config = OcrConfig(
    det_threshold: float | None = None,
    box_threshold: float | None = None,
    rec_threshold: float | None = None,
    num_threads: int | None = None,
    max_candidates: int | None = None,
    use_v5: bool = False
)

DocumentBuilder

Builder fluente para compor PDFs página por página. Veja o exemplo abaixo e Criar do zero.

from pdf_oxide import DocumentBuilder

Métodos em Nível de Documento

Método Parâmetros Descrição
DocumentBuilder() – Constrói um novo builder
title(title) str Define o título do documento
author(author) str Define o autor do documento
subject(subject) str Define o assunto do documento
keywords(keywords) str Define as palavras-chave do documento
creator(creator) str Define o nome da aplicação produtora
on_open(script) str Define uma ação JavaScript de abertura em nível de documento
tagged_pdf_ua1() – Emite um documento acessível Tagged PDF/UA-1
language(lang) str Define o idioma do documento (ex.: "en-US")
role_map(custom, standard) str, str Mapeia uma tag de estrutura personalizada para uma padrão
register_embedded_font(name, font) str, EmbeddedFont Registra uma fonte (consome o EmbeddedFont)

Fábricas de Página

builder.a4_page() -> FluentPageBuilder       # 595 x 842 pt
builder.letter_page() -> FluentPageBuilder   # 612 x 792 pt
builder.page(width: float, height: float) -> FluentPageBuilder

Saída

builder.build() -> bytes
builder.save(path: str) -> None
builder.save_encrypted(path: str, user_password: str, owner_password: str) -> None
builder.to_bytes_encrypted(user_password: str, owner_password: str) -> bytes

FluentPageBuilder

Armazena em buffer as operações em nível de página até done(). Retornado por DocumentBuilder.a4_page() / letter_page() / page(). Cada método retorna self para encadeamento; done() confirma a página e retorna o DocumentBuilder pai.

Texto e Layout

Método Parâmetros Descrição
font(name, size) str, float Define a fonte e o tamanho atuais
at(x, y) float, float Move o cursor para uma posição absoluta
text(text) str Desenha texto na posição do cursor
heading(level, text) int, str Desenha um título (nível 1–6)
paragraph(text) str Desenha um parágrafo com quebra de linha
space(points) float Avança espaço vertical
horizontal_rule() – Desenha um divisor horizontal
columns(column_count, gap_pt, text) int, float, str Fluxo de texto balanceado em múltiplas colunas
footnote(ref_mark, note_text) str, str Marca de referência inline + nota ao pé da página
new_page_same_size() – Inicia uma nova página com as mesmas dimensões
measure(text) -> float str Mede a largura do texto renderizado em pontos
remaining_space() -> float – Espaço vertical restante na página

Sequências Inline

page.inline(text: str)
page.inline_bold(text: str)
page.inline_italic(text: str)
page.inline_color(text: str, r: float, g: float, b: float)
page.newline()

page.link_url(url: str)
page.link_page(page: int)
page.link_named(name: str)
page.link_javascript(script: str)
page.on_open(script: str)
page.on_close(script: str)
page.field_keystroke(script: str)
page.field_format(script: str)
page.field_validate(script: str)
page.field_calculate(script: str)

Anotações de Marcação

page.highlight(color: tuple[float, float, float])
page.underline(color: tuple[float, float, float])
page.strikeout(color: tuple[float, float, float])
page.squiggly(color: tuple[float, float, float])
page.sticky_note(text: str)
page.sticky_note_at(x: float, y: float, text: str)
page.watermark(text: str)
page.watermark_confidential()
page.watermark_draft()
page.stamp(name: str)
page.freetext(x: float, y: float, w: float, h: float, text: str)

Widgets AcroForm

page.text_field(name: str, x: float, y: float, w: float, h: float, default_value: str | None = None)
page.checkbox(name: str, x: float, y: float, w: float, h: float, checked: bool = False)
page.combo_box(name: str, x: float, y: float, w: float, h: float, options: list[str], selected: str | None = None)
page.radio_group(name: str, buttons: list[tuple[str, float, float, float, float]], selected: str | None = None)
page.push_button(name: str, x: float, y: float, w: float, h: float, caption: str)
page.signature_field(name: str, x: float, y: float, w: float, h: float)

Gráficos

page.rect(x: float, y: float, w: float, h: float)
page.filled_rect(x: float, y: float, w: float, h: float, r: float, g: float, b: float)
page.line(x1: float, y1: float, x2: float, y2: float)
page.text_in_rect(x: float, y: float, w: float, h: float, text: str, align: int | None = None)
page.stroke_rect(x, y, w, h, width=1.0, color=(0.0, 0.0, 0.0))
page.stroke_rect_dashed(x, y, w, h, dash, width=1.0, color=(0.0, 0.0, 0.0), phase=0.0)
page.stroke_line(x1, y1, x2, y2, width=1.0, color=(0.0, 0.0, 0.0))
page.stroke_line_dashed(x1, y1, x2, y2, dash, width=1.0, color=(0.0, 0.0, 0.0), phase=0.0)

Imagens e Códigos de Barras

page.image_with_alt(bytes: bytes, x: float, y: float, w: float, h: float, alt_text: str)
page.image_artifact(bytes: bytes, x: float, y: float, w: float, h: float)
page.barcode_1d(barcode_type: int, data: str, x: float, y: float, w: float, h: float)
page.barcode_qr(data: str, x: float, y: float, size: float)

barcode_type: 0=Code128, 1=Code39, 2=EAN13, 3=EAN8, 4=UPCA, 5=ITF, 6=Code93, 7=Codabar.

Tabelas

page.table(table: Table)
page.streaming_table(
    columns: list[Column],
    repeat_header: bool = False,
    mode: str = "fixed",
    sample_rows: int = 50,
    min_col_width_pt: float = 20.0,
    max_col_width_pt: float = 400.0,
    max_rowspan: int = 1,
    batch_size: int = 256
) -> StreamingTable

Confirmação

page.done() -> DocumentBuilder

EmbeddedFont

Uma fonte TTF/OTF registrada com um DocumentBuilder.

from pdf_oxide import EmbeddedFont

EmbeddedFont.from_file(path: str) -> EmbeddedFont
EmbeddedFont.from_bytes(data: bytes, name: str | None = None) -> EmbeddedFont
Propriedade Tipo Descrição
name str O nome registrado da fonte

Tabelas

Objetos de valor para a API fluente de tabelas.

Align

from pdf_oxide import Align

Align.LEFT     # 0
Align.CENTER   # 1
Align.RIGHT    # 2

Column

from pdf_oxide import Column

Column(header: str, width: float = 100.0, align: Align | int | None = None)
Propriedade Tipo Descrição
header str Texto do cabeçalho da coluna
width float Largura da coluna em pontos
align int Alinhamento da célula

Table

from pdf_oxide import Table

Table(columns: list[Column], rows: list[list[str]], has_header: bool = False)

Uma tabela em buffer consumida por FluentPageBuilder.table(). Com has_header=True, os cabeçalhos das colunas são renderizados como uma linha de cabeçalho estilizada.

StreamingTable

Um handle de tabela com streaming de linhas retornado por FluentPageBuilder.streaming_table(), para tabelas grandes demais para serem materializadas de uma só vez.

Método Parâmetros Descrição
push_row(cells) list[str] Adiciona uma linha de strings de célula
push_row_span(cells) list[tuple[str, int]] Adiciona uma linha de células (text, colspan)
flush() – Descarrega o lote atual
finish() – Finaliza a tabela, retornando o FluentPageBuilder
column_count() – → int Número de colunas
pending_row_count() – → int Linhas em buffer ainda não confirmadas
batch_count() – → int Número de lotes concluídos

Templates de Página

Artefatos de cabeçalho/rodapé repetidos aplicados ao longo das páginas.

Artifact / ArtifactStyle

from pdf_oxide import Artifact, ArtifactStyle

Artifact()                       # empty artifact
Artifact.center(text: str)       # centered artifact text
artifact.with_left(text: str)    # add left-aligned text

style = ArtifactStyle()
style = style.font(name: str, size: float)
style = style.bold()

from pdf_oxide import Header, Footer

Header()                  # or Header.center(text: str)
Footer()                  # or Footer.center(text: str)

PageTemplate

from pdf_oxide import PageTemplate, Header, Footer

template = (PageTemplate()
    .header(Header.center("Confidential"))
    .footer(Footer.center("Page")))

Assinaturas Digitais

Assine, carimbe a data/hora e verifique PDFs (PAdES / LTV). Requer os recursos signatures (e, opcionalmente, tsa-client) no build em Rust.

Certificate

from pdf_oxide import Certificate

Certificate.load(data: bytes) -> Certificate                       # DER certificate (verify only)
Certificate.load_pem(cert_pem: str, key_pem: str) -> Certificate   # signing credential
Certificate.load_pkcs12(data: bytes, password: str) -> Certificate # PKCS#12 / .p12 signing credential
Método Retorna Descrição
subject() str DN do titular (subject) do certificado
issuer() str DN do emissor (issuer) do certificado
serial() str Número de série
validity() tuple[int, int] Timestamps Unix (not_before, not_after)
is_valid() bool Se o certificado está atualmente dentro da sua janela de validade

Signature

Retornada por PdfDocument.signatures().

Propriedade / Método Tipo Descrição
signer_name `str None`
reason `str None`
location `str None`
contact_info `str None`
signing_time `int None`
covers_whole_document bool Se a assinatura cobre o arquivo inteiro
pades_level PadesLevel Baseline PAdES detectado (B-B/B-T/B-LT)
verify() bool Verifica a assinatura criptograficamente
verify_detached(pdf_data) bool Verifica incluindo o messageDigest em relação aos bytes do arquivo

Timestamp

from pdf_oxide import Timestamp

Timestamp.parse(data: bytes) -> Timestamp
Propriedade / Método Tipo Descrição
time int Hora do timestamp (Unix)
serial str Número de série da resposta da TSA
policy_oid str OID de política da TSA
tsa_name str Nome da TSA
hash_algorithm int Código do algoritmo de hash do message-imprint
message_imprint bytes O message imprint com hash
verify() bool Verifica o token de timestamp

TsaClient

from pdf_oxide import TsaClient

client = TsaClient(
    url: str,
    username: str | None = None,
    password: str | None = None,
    timeout_seconds: int = 30,
    hash_algorithm: int = 2,
    use_nonce: bool = True,
    cert_req: bool = True
)
client.request_timestamp(data: bytes) -> Timestamp
client.request_timestamp_hash(digest: bytes, algorithm: int = 2) -> Timestamp

PadesLevel

from pdf_oxide import PadesLevel

PadesLevel.B_B     # baseline
PadesLevel.B_T     # + trusted timestamp
PadesLevel.B_LT    # + long-term validation material
PadesLevel.B_LTA   # + archival timestamp

RevocationMaterial

from pdf_oxide import RevocationMaterial

RevocationMaterial(
    certs: list[bytes] | None = None,
    crls: list[bytes] | None = None,
    ocsps: list[bytes] | None = None
)

Certificados, CRLs e respostas OCSP codificados em DER para assinatura B-LT.

Dss

Um Document Security Store analisado, retornado por PdfDocument.dss().

Propriedade Tipo Descrição
certs list[bytes] Blobs DER de certificados em nível de documento
crls list[bytes] Blobs DER de CRL
ocsps list[bytes] Blobs DER de resposta OCSP
vri list[str] Chaves VRI por assinatura (SHA-1 hex de /Contents)

Funções em Nível de Módulo

from pdf_oxide import (
    sign_pdf_bytes, sign_pdf_bytes_pades, has_document_timestamp,
    generate_barcode_svg, generate_qr_svg,
    plan_split_by_bookmarks, split_by_bookmarks,
)

Assinatura

sign_pdf_bytes(pdf_data: bytes, cert: Certificate, reason: str | None = None, location: str | None = None) -> bytes

Assina bytes brutos de PDF com um Certificate de assinatura carregado e retorna o PDF assinado.

sign_pdf_bytes_pades(
    pdf_data: bytes,
    cert: Certificate,
    level: PadesLevel,
    tsa_url: str | None = None,
    reason: str | None = None,
    location: str | None = None,
    revocation: RevocationMaterial | None = None
) -> bytes

Assina bytes brutos de PDF em um nível de baseline PAdES. B_T/B_LT exigem um tsa_url.

has_document_timestamp(pdf_data: bytes) -> bool

Se o PDF carrega um timestamp de arquivamento RFC 3161 em nível de documento (PAdES-B-LTA).

Códigos de Barras

generate_barcode_svg(barcode_type: int, data: str) -> str
generate_qr_svg(data: str, error_correction: int, size: int) -> str

Gera um código de barras 1D ou um QR code como uma string SVG. Requer o recurso barcodes.

Divisão por Marcadores

plan_split_by_bookmarks(src_bytes: bytes, title_prefix: str | None = None, ignore_case: bool = False, level: int = 1, include_front_matter: bool = True) -> list[dict]
split_by_bookmarks(src_bytes: bytes, title_prefix: str | None = None, ignore_case: bool = False, level: int = 1, include_front_matter: bool = True) -> list[tuple[dict, bytes]]

Planeja ou executa a divisão de um PDF nos limites dos marcadores. plan_* retorna apenas os metadados dos segmentos; split_* retorna cada segmento emparelhado com seus bytes de PDF.

Provisionamento de Modelos de OCR

prefetch_models(languages: list[str]) -> str
model_manifest() -> str
prefetch_available() -> bool

Provisiona modelos de OCR para uso offline/air-gapped, inspeciona o manifesto de modelos (JSON) e verifica se este build pode baixar modelos.

Logging

setup_logging() -> None
set_log_level(level: str) -> None     # "off" | "error" | "warn" | "info" | "debug" | "trace"
get_log_level() -> str
disable_logging() -> None

Ajuste do Engine

set_max_ops_per_stream(limit: int | None) -> int | None
set_preserve_unmapped_glyphs(preserve: bool) -> bool

Ajusta o limite de operadores por stream (proteção contra entradas adversariais) e a preservação de U+FFFD para glifos não mapeados. Ambos retornam o valor anterior.

Governança Criptográfica

crypto_active_provider() -> str
crypto_available_providers() -> list[str]
crypto_use_fips() -> None                 # install the FIPS aws-lc-rs provider (requires the fips feature)
crypto_set_policy(spec: str) -> None      # e.g. "strict" or "compat;deny:rc4@write"
crypto_policy() -> str
crypto_inventory() -> list[str]
crypto_cbom() -> str                      # CycloneDX 1.6 CBOM (JSON)

API Assíncrona

Wrappers async/await que executam operações bloqueantes em um pool de threads. Os métodos espelham suas contrapartes síncronas.

from pdf_oxide import AsyncPdfDocument, AsyncPdf, AsyncOfficeConverter

async def main():
    doc = await AsyncPdfDocument.open("input.pdf")
    text = await doc.extract_text(0)
    await doc.close()
    # Or use as an async context manager:
    async with await AsyncPdfDocument.from_bytes(pdf_bytes) as doc:
        md = await doc.to_markdown_all()
Classe Construtores Observações
AsyncPdfDocument await AsyncPdfDocument.open(path, password=None), await AsyncPdfDocument.from_bytes(data, password=None) Todos os métodos de PdfDocument estão disponíveis como awaitables; suporta async with e .close()
AsyncPdf encapsula os métodos de fábrica de Pdf await pdf.save(path), await pdf.to_bytes()
AsyncOfficeConverter encapsula os métodos estáticos de OfficeConverter ex.: await AsyncOfficeConverter.from_docx(path)

Tratamento de Erros

PdfError

Todos os erros específicos de PDF lançam PdfError:

from pdf_oxide import PdfDocument, PdfError

try:
    doc = PdfDocument("file.pdf")
    text = doc.extract_text(0)
except PdfError as e:
    print(f"PDF error: {e}")
except FileNotFoundError:
    print("File not found")
except IndexError:
    print("Page index out of range")

Cenários de erro comuns:

Exceção Causa
PdfError PDF malformado, criptografado sem senha, falha de parsing
FileNotFoundError O arquivo não existe
IndexError O índice de página excede page_count()
ValueError Argumento inválido (ex.: índice de página negativo)

Exemplo Completo

from pdf_oxide import PdfDocument, Pdf

# --- Extraction ---
doc = PdfDocument("input.pdf")
print(f"Pages: {doc.page_count()}")

for i in range(doc.page_count()):
    text = doc.extract_text(i)
    print(f"Page {i + 1}: {len(text)} characters")

# Character-level analysis
chars = doc.extract_chars(0)
fonts = set(ch.font_name for ch in chars)
print(f"Fonts on page 1: {fonts}")

# Image extraction
images = doc.extract_image_bytes(0)
for i, img in enumerate(images):
    with open(f"extracted_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

# --- Creation ---
pdf = Pdf.from_markdown("# Report\n\nGenerated by PDF Oxide.",
                        title="Report", author="PDF Oxide")
pdf.save("report.pdf")

# --- Editing ---
doc = PdfDocument("document.pdf")
doc.set_title("Updated Title")
doc.set_author("New Author")
doc.rotate_all_pages(90)

# Search and replace via DOM
page = doc.page(0)
for text in page.find_text_containing("DRAFT"):
    page.set_text(text.id, "FINAL")
doc.save_page(page)

# Form filling
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name} ({f.field_type}) = {f.value}")
doc.set_form_field_value("name", "John Doe")

# Merge another PDF
merged_count = doc.merge_from("appendix.pdf")
print(f"Merged {merged_count} pages")

doc.save("output.pdf")

# --- Search ---
results = doc.search("configuration", case_insensitive=True)
for r in results:
    print(f"Page {r.page + 1}: '{r.text}' at ({r.x:.0f}, {r.y:.0f})")

Adições da v0.3.38

DocumentBuilder / FluentPageBuilder / EmbeddedFont

from pdf_oxide import DocumentBuilder, EmbeddedFont, StampType

font = EmbeddedFont.from_file("DejaVuSans.ttf")
# Alt: EmbeddedFont.from_bytes(data: bytes, name: str | None = None)

(DocumentBuilder()
    .register_embedded_font("DejaVu", font)
    .letter_page()           # or .a4_page() / .page(size)
        .at(72, 720).font("DejaVu", 12).text("Hello")
        .heading(1, "Title")
        .paragraph("Body text with automatic wrapping")
        # Annotations (15 methods)
        .link_url("https://example.com")
        .link_page(2)
        .link_named("glossary")
        .highlight((1.0, 1.0, 0.0))
        .underline((0.0, 0.0, 1.0))
        .strikeout((1.0, 0.0, 0.0))
        .squiggly((1.0, 0.5, 0.0))
        .sticky_note("Review this")
        .stamp(StampType.APPROVED)
        .freetext((100, 500, 200, 50), "Comment")
        .watermark("DRAFT")
        .watermark_confidential()
        .watermark_draft()
        # AcroForm widgets (5 types)
        .text_field("name", 150, 400, 200, 20, "Jane Doe")
        .checkbox("agree", 72, 380, 15, 15, True)
        .combo_box("country", 150, 360, 200, 20, ["US", "UK"], "US")
        .radio_group("tier", [("free", 72, 340, 15, 15), ("pro", 120, 340, 15, 15)], "pro")
        .push_button("submit", 72, 300, 80, 25, "Submit")
        # Graphics primitives
        .rect(50, 270, 500, 2)
        .filled_rect(50, 260, 500, 2, (0.9, 0.9, 0.9))
        .line(50, 250, 550, 250)
    .done()
    .save_encrypted("out.pdf", "user-pw", "owner-pw"))
# Alt: .save("out.pdf") / .build() -> bytes
# Alt: .to_bytes_encrypted("user-pw", "owner-pw") -> bytes

Pipeline HTML + CSS

Pdf.from_html_css(html: str, css: str, font_bytes: bytes) -> Pdf
Pdf.from_html_css_with_fonts(html: str, css: str, fonts: list[tuple[str, bytes]]) -> Pdf

Consulte Criar a partir de HTML.

Verificação de Assinatura

from pdf_oxide import PdfDocument, Timestamp, TsaClient

doc = PdfDocument("signed.pdf")
doc.signature_count()                # int
for sig in doc.signatures():
    sig.signer_name                  # str
    sig.reason                       # str | None
    sig.location                     # str | None
    sig.signing_time                 # datetime | None
    sig.verify()                     # "Valid" | "Invalid" | "Unknown"
    sig.verify_detached(pdf_bytes)   # adds messageDigest check

# Timestamp
ts = Timestamp.parse(tst_bytes)
ts.time, ts.serial, ts.policy_oid, ts.tsa_name, ts.hash_algorithm, ts.message_imprint

# TSA client (behind `tsa-client` feature)
client = TsaClient(url="https://freetsa.org/tsr",
                   username=None, password=None,
                   timeout_seconds=30, hash_algorithm=2,
                   use_nonce=True, cert_req=True)
ts = client.request_timestamp(pdf_bytes)
ts = client.request_timestamp_hash(digest, algorithm=2)

Consulte Assinaturas Digitais para mais detalhes.

Renderização

doc.render_page_region(page: int, x: float, y: float, w: float, h: float, format: int = 0) -> bytes
doc.render_page_fit(page: int, fit_width: int, fit_height: int, format: int = 0) -> bytes

format: 0 = PNG, 1 = JPEG. Coordenadas em pontos PDF a partir do canto inferior esquerdo.

Achatamento de Pdf

doc.flatten_to_images(dpi: int = 150) -> bytes

Other Language Bindings

O PDF Oxide oferece bindings nativos para todos os principais ecossistemas: Rust, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C e Elixir.

Próximos Passos