Referência da API Python

Visão geral

O NextPDF Python Software Development Kit (SDK) expõe dois clientes, um namespace compartilhado de métodos da Abstract Syntax Tree (AST) chamado ast, modelos Pydantic para cada resposta, uma command-line interface (CLI) nextpdf e uma hierarquia de exceções com seis classes. Use esta página como referência para os símbolos públicos da application programming interface (API) que operam sobre documentos em Portable Document Format (PDF).

Importe os símbolos públicos do pacote de nível superior:

from nextpdf import (
    AsyncNextPDF,
    NextPDF,
    AstBuildTimeoutError,
    AstNoStructTreeError,
    NextPDFAPIError,
    NextPDFError,
    NextPDFLicenseError,
    QuotaExceededError,
)

Cada método de extração recebe bytes brutos de PDF (bytes) como primeiro argumento posicional e retorna um modelo Pydantic tipado. Passe as opções como argumentos somente nomeados. Os métodos síncronos NextPDF.ast.* e os métodos assíncronos AsyncNextPDF.ast.* têm assinaturas idênticas. Os métodos assíncronos são corrotinas; chame-os com await.

Cliente

O cliente síncrono NextPDF encapsula o cliente assíncrono e executa cada corrotina até a conclusão. AsyncNextPDF funciona tanto como cliente assíncrono quanto como gerenciador de contexto assíncrono. Prefira a forma de gerenciador de contexto para garantir que o transporte subjacente seja fechado de forma determinística.

Construtores

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
NextPDF(*, base_url, api_key, api_version='v1')	Base URL, chave de API e versão opcional da API, somente nomeados.	Cria um cliente síncrono com backend remoto.	NextPDF	ValueError quando base_url ou api_key está vazio.	Executa trabalho assíncrono de forma síncrona; é seguro em notebooks e dentro de um event loop em execução.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	Base URL, chave de API, versão opcional da API e backend injetado opcional, somente nomeados.	Cria um cliente assíncrono com backend remoto quando nenhum backend é injetado.	AsyncNextPDF	ValueError quando base_url ou api_key está vazio e nenhum backend é fornecido.	Passe backend= para injetar um backend personalizado ou local em testes.
AsyncNextPDF.__aenter__()	Nenhum.	Entra no contexto assíncrono e retorna o cliente.	AsyncNextPDF	Nenhum esperado.	Use async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Argumentos de exceção ignorados.	Chama close() ao sair do contexto.	None	Nenhum esperado.	Libera o transporte mesmo se o corpo lançar uma exceção.
AsyncNextPDF.close()	Nenhum.	Fecha o backend remoto pertencente ao cliente e libera o pool de conexões.	None	Nenhum esperado.	Idempotente; backends injetados não são fechados.

Não armazene a chave de API no código-fonte. Leia base_url e api_key do ambiente (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) ou de um gerenciador de segredos.

import os

from nextpdf import AsyncNextPDF


async def extract(pdf_bytes: bytes) -> int:
    """Return the page count of a PDF using the async client as a context manager."""
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]

    async with AsyncNextPDF(base_url=base_url, api_key=api_key) as client:
        document = await client.ast.get_document_ast(pdf_bytes)
        return document.page_count

Métodos AST síncronos — NextPDF.ast.*

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
NextPDF.ast.get_document_ast()	pdf_data: bytes; nomeados page_range_start, page_range_end, token_budget.	Constrói a Semantic AST completa para cada página.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Reduza o intervalo de páginas quando a construção exceder o tempo limite.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; nomeados page_index, headings_only.	Extrai todos os blocos de texto com âncoras de citação.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Defina headings_only=True para recuperar apenas os nós de título.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; nomeado page_range (dict com start e end).	Extrai todas as tabelas com âncoras de citação no nível de célula.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Omita page_range para percorrer o documento inteiro.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Recupera um nó pelo identificador.	GetAstNodeResponse	NextPDFError quando o nó não é encontrado.	node_id tem o formato ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; nomeados node_type, page_index, text_query, max_results=100.	Retorna nós rasos que correspondem aos filtros.	SearchAstNodesResponse	NextPDFAPIError.	text_query é uma correspondência de substring que não diferencia maiúsculas de minúsculas.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Compara dois documentos pela estrutura.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Relata nós adicionados, removidos e alterados.

Métodos AST assíncronos — AsyncNextPDF.ast.*

Cada método assíncrono é uma corrotina com os mesmos parâmetros, valores padrão, tipo de retorno e modos de falha do equivalente síncrono. Chame-o com await dentro de um runtime asyncio.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; nomeados page_range_start, page_range_end, token_budget.	Constrói a Semantic AST completa para cada página.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	await o resultado.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; nomeados page_index, headings_only.	Extrai todos os blocos de texto com âncoras de citação.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	await o resultado.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; nomeado page_range.	Extrai todas as tabelas com âncoras de citação no nível de célula.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	await o resultado.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Recupera um nó pelo identificador.	GetAstNodeResponse	NextPDFError quando o nó não é encontrado.	await o resultado.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; nomeados node_type, page_index, text_query, max_results=100.	Retorna nós rasos que correspondem aos filtros.	SearchAstNodesResponse	NextPDFAPIError.	await o resultado.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Compara dois documentos pela estrutura.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	await o resultado.

Use o cliente assíncrono como gerenciador de contexto para executar duas extrações de forma concorrente:

import asyncio

from nextpdf import AsyncNextPDF


async def extract_pair(first: bytes, second: bytes) -> None:
    """Extract two PDFs concurrently with one shared async client."""
    async with AsyncNextPDF(base_url="https://connect.example.com", api_key="set-from-secret") as client:
        text_blocks, tables = await asyncio.gather(
            client.ast.extract_cited_text(first),
            client.ast.extract_cited_tables(second),
        )
        print(f"text blocks: {len(text_blocks)}; tables: {tables.table_count}")

Modelos

Cada resposta é um modelo Pydantic. Importe as classes de modelo a partir de nextpdf ou nextpdf.models.ast.

Símbolo	Tipo	Campos principais	Observações
AstDocument	Raiz do documento	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (propriedade).	Retornado por get_document_ast(). Aceita os aliases schemaVersion, sourceHash e pageCount.
AstNode	Nó da árvore	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Nó recursivo que representa a árvore do documento.
AstNodeMeta	Metadados da resposta	etag, pages_processed.	Imutável; anexado às respostas de nó e de busca.
AstNodeShallow	Resultado da busca	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Imutável; sem filhos profundos.
BoundingBox	Objeto de valor	x, y, width, height (cada um de 0.0–1.0).	Coordenadas normalizadas dentro de uma página.
CitationAnchor	Objeto de valor	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Registro de proveniência para cada bloco.
CitedTextBlock	Bloco de texto	text, citation: CitationAnchor, node_type, chunk_index, depth.	Cada item da lista de extract_cited_text().
CitedTableBlock	Bloco de tabela	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Imutável; uma tabela.
CitedTableCell	Célula de tabela	row, col, row_span, col_span, text, bbox, confidence.	Imutável; uma célula.
NodeType	Enum	document, section, heading, paragraph, list, table, figure, entre outros.	Enum de string para os valores de tipo de nó.
GetAstNodeResponse	Resposta	node: AstNode, meta: AstNodeMeta.	Retornado por get_ast_node().
SearchAstNodesResponse	Resposta	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Retornado por search_ast_nodes().
ExtractCitedTablesResponse	Resposta	tables: list[CitedTableBlock], table_count, pages_processed.	Retornado por extract_cited_tables().
AstDiffEntry	Item de diff	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Uma alteração em um diff.
AstDiffSummary	Totais do diff	added_node_count, removed_node_count, changed_node_count.	Contagens agregadas.
GetAstDiffResponse	Resposta	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Retornado por get_ast_diff().

Leia a âncora de citação de um bloco de texto extraído:

from nextpdf import CitedTextBlock


def describe(block: CitedTextBlock) -> str:
    """Render a text block with its page index and confidence."""
    anchor = block.citation
    return f"[page {anchor.page_index}, confidence {anchor.confidence:.2f}] {block.text[:80]}"

Comandos da CLI

O comando nextpdf executa extrações pelo terminal. Passe --base-url e --api-key, ou defina NEXTPDF_BASE_URL e NEXTPDF_API_KEY no ambiente. Todos os comandos, exceto version, exigem configuração de conexão. Quando PDF_PATH é -, os bytes do PDF são lidos da entrada padrão.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Observações
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Emite os blocos de texto citados em JavaScript Object Notation (JSON).	Grava na saída padrão ou em um arquivo --output.	Sai com código 1 para qualquer NextPDFError.	--page seleciona um índice de página baseado em 0.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Emite as tabelas como JSON.	Grava na saída padrão ou em um arquivo --output.	Sai com código 1 para qualquer NextPDFError.	--format csv grava um bloco de comma-separated values (CSV) para cada tabela.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Emite a Semantic AST completa como JSON.	Grava na saída padrão ou em um arquivo --output.	Sai com código 1 para qualquer NextPDFError.	Use --token-budget para limitar o tamanho da resposta.
nextpdf info	PDF_PATH.	Emite os metadados do documento: contagem de páginas, versão do schema, hash de origem, tokens estimados e resumo da raiz.	Grava JSON na saída padrão ou em um arquivo --output.	Sai com código 1 para qualquer NextPDFError.	Comando leve de inspeção.
nextpdf version	Nenhum.	Imprime a versão instalada do SDK.	Grava na saída padrão.	Nenhum esperado.	Não contata um servidor; não precisa de credenciais.
python -m nextpdf.mcp	Nenhum (lê NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Executa o servidor Model Context Protocol sobre standard input/output.	Processo de servidor de longa duração.	RuntimeError quando as variáveis de ambiente não estão definidas.	Requer o extra nextpdf[mcp].

Extraia tabelas como comma-separated values (CSV) de um intervalo de páginas:

nextpdf extract tables invoice.pdf --format csv --page-start 0 --page-end 2 --output tables.csv

Exceções

A hierarquia de exceções fica em nextpdf.models.errors e é reexportada de nextpdf. Capture a classe mais específica que o código pode tratar e, em seguida, recorra à classe base. O servidor relata falhas usando a semântica de status do Hypertext Transfer Protocol (HTTP), alinhada à Request for Comments (RFC) 9110. Cada exceção carrega o status_code de origem e, quando disponível, um error_code.

Símbolo	Classe base	status_code	Quando é lançada	Observações
NextPDFError	Exception	opcional	Classe base para todos os erros do SDK.	Carrega um status_code opcional. Capture-a por último como fallback.
NextPDFAPIError	NextPDFError	obrigatório	O endpoint Connect retornou um erro HTTP.	Acrescenta error_code.
NextPDFLicenseError	NextPDFAPIError	402	O servidor exige uma licença de nível superior para o recurso.	error_code é license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Um limite de taxa ou cota foi excedido.	Carrega retry_after; respeite esse valor antes de tentar novamente.
AstNoStructTreeError	NextPDFAPIError	422	O PDF não tem tags e o fallback heurístico não está habilitado.	Habilite o modo heurístico ou forneça um PDF com tags.
AstBuildTimeoutError	NextPDFAPIError	504	A construção da AST excedeu o tempo limite no servidor.	Reduza o intervalo de páginas e tente novamente.

from nextpdf import (
    NextPDF,
    AstBuildTimeoutError,
    NextPDFAPIError,
    NextPDFError,
    QuotaExceededError,
)


def extract_text(client: NextPDF, pdf_bytes: bytes) -> int:
    """Extract cited text, handling the most specific failures first."""
    try:
        blocks = client.ast.extract_cited_text(pdf_bytes)
    except QuotaExceededError as error:
        raise RuntimeError(f"Quota exceeded (retry after {error.retry_after}s)") from error
    except AstBuildTimeoutError as error:
        raise RuntimeError("AST build timed out; reduce the page range") from error
    except NextPDFAPIError as error:
        raise RuntimeError(f"API error {error.status_code}: {error}") from error
    except NextPDFError as error:
        raise RuntimeError(f"SDK error: {error}") from error
    return len(blocks)

Notas de desenvolvimento

• O cliente síncrono NextPDF delega cada chamada para AsyncNextPDF. Você pode chamá-lo a partir de um notebook ou de uma thread que já esteja executando um event loop, porque ele despacha a corrotina para uma thread de trabalho quando detecta um loop em execução.
• Prefira a forma de gerenciador de contexto assíncrono async with AsyncNextPDF(...) as client: para que o pool de conexões seja fechado de forma determinística. Quando você cria AsyncNextPDF diretamente, chame close() você mesmo.
• O bearer token nunca é registrado em log nem incluído em mensagens de erro, e a verificação de Transport Layer Security (TLS) é habilitada por padrão. Não embuta credenciais no código-fonte; leia-as do ambiente ou de um gerenciador de segredos.
• Todos os modelos são classes Pydantic v2; vários modelos de resposta são imutáveis (frozen). Trate os blocos extraídos como valores somente leitura.
• A CLI termina com o código de saída 1 para qualquer NextPDFError e imprime a mensagem na saída de erro padrão. Use esse código de saída nos pipelines.

Consulte também

• Guia do desenvolvedor do Python SDK — arquitetura, processamento assíncrono em lote e tratamento de falhas.
• Python CLI — extração no terminal e streaming para arquivos grandes.
• Servidor Python MCP — expõe ferramentas de extração para AI agents.
• A RFC 9110 (HTTP Semantics) e a RFC 9457 (Problem Details for HTTP APIs) descrevem a semântica de status e os corpos de erro legíveis por máquina que o endpoint Connect retorna. Consulte o índice de RFCs da IETF para obter o texto oficial.