Guia do desenvolvedor para o SDK Python

Visão geral

O Software Development Kit (SDK) Python do NextPDF é um cliente leve e tipado para um endpoint do NextPDF Connect. A aplicação é responsável por validar a entrada em Portable Document Format (PDF), tratar credenciais e definir a política de concorrência. O SDK é responsável por construir a requisição, realizar o transporte e tipar a resposta. Mantenha esse limite claro: leia o PDF com segurança, escolha um cliente, chame o método ast de que você precisa e trate a falha específica.

Use este guia ao criar serviços de extração, jobs em lote com asyncio, ferramentas para agentes de inteligência artificial (IA) ou fluxos de trabalho de linha de comando em torno do SDK. Ele pressupõe que você leu a visão geral e o guia de início rápido, e que tem Python 3.10 ou mais recente e um endpoint do NextPDF Connect.

Limite de arquitetura

Camada	Responsável por	Responsabilidade	Não coloque aqui
Origem de entrada	Aplicação	Autorize o chamador, valide a origem do PDF e escolha a política de extração.	Literais de Uniform Resource Locator (URL) de endpoint ou de credenciais.
Construção do cliente	Aplicação	Leia base_url e api_key do ambiente ou de um gerenciador de segredos.	Segredos embutidos no código.
NextPDF / AsyncNextPDF	SDK	Monte a requisição, chame o Connect e retorne modelos Pydantic tipados.	Lógica de domínio ou política de armazenamento.
ast (namespace do método)	SDK	Mapeie uma chamada de método para um endpoint do Connect e analise a resposta.	Política de repetição ou de espera progressiva (backoff) além da que você configurar.
Endpoint do NextPDF Connect	Implantação	Execute a extração e imponha autenticação, cotas e licenciamento.	Autorização da aplicação.

O SDK nunca realiza reconhecimento óptico de caracteres (OCR). Se um PDF for digitalizado ou composto apenas por imagem, execute o OCR antes da extração. Trate essa etapa como uma responsabilidade da aplicação, fora deste limite.

Ciclo de vida em tempo de execução

Estágio	Comportamento	Ação do desenvolvedor
Construção do cliente	base_url e api_key são validados; qualquer valor vazio gera ValueError.	Leia ambos do ambiente; nunca os insira diretamente no código.
Criação do backend	Um backend remoto abre uma conexão em pool com o Connect.	Reutilize um único cliente entre as chamadas em vez de criar um a cada requisição.
Chamada de método	O método ast serializa a requisição, envia os bytes do PDF e analisa a resposta em um modelo Pydantic.	Passe bytes já validados.
Mapeamento de erros	O SDK mapeia um status do Hypertext Transfer Protocol (HTTP) de falha para uma subclasse de exceção específica.	Capture primeiro a classe mais específica.
Encerramento	AsyncNextPDF.close() libera o pool de conexões; o gerenciador de contexto assíncrono chama esse método por você.	Use async with ou chame close() em um bloco finally.

Estrutura de aplicação recomendada

Caminho	Finalidade
app/pdf/clients.py	Construa e armazene em cache um NextPDF ou AsyncNextPDF configurado.
app/pdf/extraction.py	Wrapper da aplicação para as chamadas do método ast.
app/pdf/validation.py	Validação da origem do PDF, limites de tamanho e verificações de conteúdo.
tests/pdf/	Testes de extração, de modos de falha e de processamento assíncrono em lote.

Mantenha a validação do PDF separada da extração. Passe para a camada de extração apenas bytes autorizados e com tamanho verificado e, ainda assim, conte com o endpoint como camada de defesa em profundidade.

import os

from nextpdf import NextPDF


def build_client() -> NextPDF:
    """Construct a synchronous client from environment configuration.

    Raises:
        KeyError: When a required environment variable is missing.
    """
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]
    return NextPDF(base_url=base_url, api_key=api_key)

Padrão de cliente síncrono

Use o cliente síncrono NextPDF para scripts, jobs em lote e notebooks. Valide a entrada antes de chamar o SDK e trate as falhas específicas que a chamada puder gerar.

from pathlib import Path

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

MAX_PDF_BYTES = 100 * 1024 * 1024  # Reject documents above 100 MiB for the in-memory path.


def read_pdf(path: Path) -> bytes:
    """Read and validate a PDF from disk.

    Raises:
        ValueError: When the file is missing, empty, oversized, or not a PDF.
    """
    if not path.is_file():
        raise ValueError(f"Not a file: {path}")
    data = path.read_bytes()
    if not data:
        raise ValueError("PDF is empty")
    if len(data) > MAX_PDF_BYTES:
        raise ValueError("PDF exceeds the configured size limit; use the CLI streaming path")
    if not data.startswith(b"%PDF-"):
        raise ValueError("File does not look like a PDF")
    return data


def extract_text(client: NextPDF, path: Path) -> list[CitedTextBlock]:
    """Extract cited text blocks, handling the most specific failures first."""
    pdf_bytes = read_pdf(path)
    try:
        return 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 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

Um item de resultado tem este formato:

block = blocks[0]
print(block.text)                  # the extracted text
print(block.citation.page_index)   # 0-based page index
print(block.citation.confidence)   # 0.0 - 1.0

Padrão assíncrono e de processamento em lote

Use o cliente assíncrono AsyncNextPDF em runtimes asyncio, como FastAPI. Construa um único cliente como gerenciador de contexto assíncrono e compartilhe-o entre as chamadas concorrentes; não abra um cliente para cada documento. Limite a concorrência com um semáforo para respeitar a cota do endpoint.

import asyncio
import os

from nextpdf import (
    AsyncNextPDF,
    ExtractCitedTablesResponse,
    NextPDFError,
    QuotaExceededError,
)


async def extract_tables_batch(
    pdfs: list[bytes],
    *,
    max_concurrency: int = 4,
) -> list[ExtractCitedTablesResponse | None]:
    """Extract tables from many PDFs concurrently with one shared client.

    Returns one response per input PDF, or None where extraction failed.
    """
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]
    semaphore = asyncio.Semaphore(max_concurrency)

    async with AsyncNextPDF(base_url=base_url, api_key=api_key) as client:

        async def one(pdf_bytes: bytes) -> ExtractCitedTablesResponse | None:
            async with semaphore:
                try:
                    return await client.ast.extract_cited_tables(pdf_bytes)
                except QuotaExceededError as error:
                    # Surface the backpressure signal; do not silently drop it.
                    raise RuntimeError(f"Quota exceeded; retry after {error.retry_after}s") from error
                except NextPDFError:
                    return None

        return await asyncio.gather(*(one(pdf) for pdf in pdfs))

Nunca escreva um except vazio. Trate a falha, converta-a em um resultado definido ou propague-a novamente.

Pontos de extensão

Ponto de extensão	Use para	Restrição
AsyncNextPDF(backend=...)	Injete um backend personalizado ou local em testes.	O backend deve satisfazer o protocolo PdfBackend.
api_version (argumento)	Fixe uma versão da application programming interface (API) do Connect.	O padrão é v1; altere somente quando o endpoint suportar a versão desejada.
Configuração de ambiente	Forneça NEXTPDF_BASE_URL e NEXTPDF_API_KEY para a interface de linha de comando (CLI) e para o servidor Model Context Protocol (MCP).	Trate a chave como um segredo restrito à carga de trabalho.
Servidor MCP (python -m nextpdf.mcp)	Exponha ferramentas de extração para agentes compatíveis com MCP.	Requer o extra nextpdf[mcp] e um endpoint controlado.

Fluxo de trabalho de desenvolvimento

1. Instale o SDK com pip install nextpdf ou use pip install nextpdf[mcp] para o servidor de agentes.
2. Leia NEXTPDF_BASE_URL e NEXTPDF_API_KEY do ambiente para que nenhum segredo entre no controle de versão.
3. Valide toda origem de PDF em relação à existência, ao tamanho e aos magic bytes %PDF- antes de chamar o SDK.
4. Construa um cliente por processo e reutilize-o; para asyncio, mantenha-o aberto com async with.
5. Chame o método ast mais restrito para a tarefa: extract_cited_text() para prosa, extract_cited_tables() para tabelas, get_document_ast() somente quando você precisar da árvore completa.
6. Capture a exceção mais específica sobre a qual você consiga agir e, em seguida, recorra a NextPDFError.
7. Para documentos acima de 100 MiB, use o fluxo de streaming da CLI em vez de materializar cada bloco na memória.
8. Execute o mypy em modo estrito e adicione um teste de modo de falha para cada exceção que você tratar.

Tratamento de falhas

Falha	Exceção	Resposta recomendada
PDF sem marcação (untagged), heurística desativada	AstNoStructTreeError (HTTP 422)	Ative o modo heurístico no endpoint ou forneça um PDF com marcação (tagged).
Timeout de build do lado do servidor	AstBuildTimeoutError (HTTP 504)	Reduza o intervalo de páginas e tente novamente.
Nível de licença exigido	NextPDFLicenseError (HTTP 402)	Atualize a licença do servidor ou recorra a um recurso permitido.
Limite de taxa ou cota	QuotaExceededError (HTTP 429)	Aguarde retry_after segundos e, em seguida, tente novamente com espera progressiva (backoff).
Outro erro HTTP	NextPDFAPIError	Inspecione status_code e error_code; registre e exponha um erro definido.
Qualquer erro do SDK	NextPDFError	Fallback de último recurso; nunca deixe que ele escape como uma exceção não tratada.

O endpoint relata falhas com semântica de status HTTP alinhada à Request for Comments (RFC) 9110 e corpos de erro legíveis por máquina alinhados à RFC 9457. Cada exceção preserva o status_code de origem. Mapeie essas falhas para suas próprias respostas de erro em vez de vazar detalhes de transporte para os chamadores.

Padrões seguros

Aspecto	Padrão	Quando substituir
Versão da API	v1.	Altere somente quando o endpoint suportar uma versão mais recente.
Verificação de Transport Layer Security (TLS)	Ativada; nenhuma opção insegura é exposta.	Nunca desative para tráfego de produção.
Credenciais	Lidas do ambiente; nunca embutidas no código.	Use um gerenciador de segredos em produção.
Limite de tamanho em memória	Rejeita PDFs acima de 100 MiB no fluxo do cliente.	Reduza para serviços multilocatário; use a CLI para arquivos maiores.
Concorrência	Limitada por um semáforo em lotes assíncronos.	Ajuste para a cota do endpoint, não para a contagem de núcleos do host.
Registro de logs	Registre o nome do arquivo, o tamanho, o status e a duração.	Nunca registre os bytes do PDF nem a chave de API.

Checklist de testes

• Os testes de construção verificam se um base_url ou api_key vazio gera ValueError.
• Os testes de validação cobrem entradas ausentes, vazias, grandes demais e que não sejam PDF.
• Os testes de extração verificam os tipos dos modelos retornados e um CitationAnchor em cada bloco.
• Os testes de modos de falha cobrem AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError e NextPDFAPIError.
• Os testes assíncronos verificam se o cliente funciona como um gerenciador de contexto async with e se a concorrência permanece dentro do limite do semáforo.
• Os testes de ciclo de vida verificam se close() libera o transporte e é idempotente.
• Injete um backend falso com AsyncNextPDF(backend=...) para que os testes sejam executados sem um endpoint ativo.

Consulte também

• Referência da API Python — todos os métodos de cliente, modelos e exceções.
• CLI Python — extração por streaming para documentos grandes.
• Servidor MCP Python — ferramentas de extração para agentes de IA.
• Visão geral do SDK Python — escolhas de backend e limitações.