Riferimento API Python

In breve

L’SDK Python di NextPDF (Software Development Kit) espone due client, un unico spazio dei nomi per i metodi ast condiviso da entrambi, un insieme di modelli Pydantic che tipizzano ogni risposta, un’interfaccia a riga di comando (CLI) nextpdf e una gerarchia di eccezioni a sei classi. Questa pagina documenta la superficie di riferimento di ciascuno di questi simboli.

Importare le API pubbliche dal pacchetto di livello superiore:

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

Ogni metodo di estrazione accetta i byte PDF non elaborati (bytes) come primo argomento posizionale e restituisce un modello Pydantic tipizzato. Le opzioni restanti sono solo tramite parola chiave. I metodi sincroni NextPDF.ast.* e i metodi asincroni AsyncNextPDF.ast.* condividono firme identiche. I metodi asincroni sono coroutine da attendere con await.

Client

Il client sincrono NextPDF fa da wrapper al client asincrono ed esegue ogni coroutine fino al completamento. Il client asincrono AsyncNextPDF è anche un gestore di contesto asincrono. Preferire la forma con gestore di contesto, affinché il trasporto sottostante venga chiuso in modo deterministico.

Costruttori

Simbolo	Parametri	Comportamento predefinito	Valore restituito	Genera o fallisce con	Note
NextPDF(*, base_url, api_key, api_version='v1')	URL di base, chiave API solo tramite parola chiave e versione API facoltativa.	Costruisce un client sincrono con backend remoto.	NextPDF	ValueError quando base_url o api_key è vuoto.	I metodi eseguono il lavoro asincrono in modo sincrono, in sicurezza anche all’interno di notebook e di un ciclo di eventi in esecuzione.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	URL di base, chiave API solo per parola chiave, versione API facoltativa e backend iniettato facoltativo.	Costruisce un client asincrono con backend remoto quando non viene iniettato alcun backend.	AsyncNextPDF	ValueError quando base_url o api_key è vuoto e non viene fornito alcun backend.	Passare backend= per iniettare un backend personalizzato o locale nei test.
AsyncNextPDF.__aenter__()	nessuno.	Entra nel contesto asincrono e restituisce il client.	AsyncNextPDF	nessuna prevista.	Usare async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Argomenti dell’eventuale eccezione in uscita.	Chiama close() all’uscita dal contesto.	None	nessuna prevista.	Rilascia il trasporto anche quando il corpo genera un’eccezione.
AsyncNextPDF.close()	nessuno.	Chiude il backend remoto di proprietà e rilascia il pool di connessioni.	None	nessuna prevista.	Idempotente; i backend iniettati non vengono chiusi.

Mantenere la chiave API fuori dal codice sorgente. Leggere base_url e api_key dall’ambiente (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) o da un gestore di segreti.

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

Metodi AST sincroni — NextPDF.ast.*

Simbolo	Parametri	Comportamento predefinito	Valore restituito	Genera o fallisce con	Note
NextPDF.ast.get_document_ast()	pdf_data: bytes; parola chiave page_range_start, page_range_end, token_budget.	Costruisce l’AST semantico completo su tutte le pagine.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Ridurre l’intervallo di pagine quando una costruzione va in timeout.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; parola chiave page_index, headings_only.	Estrae ogni blocco di testo con un’ancora di citazione.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Impostare headings_only=True per recuperare solo i nodi di intestazione.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; parola chiave page_range (dict con start e end).	Estrae ogni tabella con ancore di citazione a livello di cella.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Omettere page_range per analizzare l’intero documento.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Recupera un nodo in base al relativo identificatore.	GetAstNodeResponse	NextPDFError quando il nodo non viene trovato.	node_id ha il formato ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; parola chiave node_type, page_index, text_query, max_results=100.	Restituisce i nodi superficiali corrispondenti ai filtri.	SearchAstNodesResponse	NextPDFAPIError.	text_query è una corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Confronta due documenti dal punto di vista strutturale.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Segnala i nodi aggiunti, rimossi e modificati.

Metodi AST asincroni — AsyncNextPDF.ast.*

Ogni metodo asincrono è una coroutine con gli stessi parametri, valori predefiniti, tipo restituito e modalità di errore della controparte sincrona riportata sopra. Invocarlo con await all’interno di un runtime asyncio.

Simbolo	Parametri	Comportamento predefinito	Valore restituito	Genera o fallisce con	Note
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; parola chiave page_range_start, page_range_end, token_budget.	Costruisce l’AST semantico completo su tutte le pagine.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Attendere il risultato con await.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; parola chiave page_index, headings_only.	Estrae ogni blocco di testo con un’ancora di citazione.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Attendere il risultato con await.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; parola chiave page_range.	Estrae ogni tabella con ancore di citazione a livello di cella.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Attendere il risultato con await.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Recupera un nodo in base al relativo identificatore.	GetAstNodeResponse	NextPDFError quando il nodo non viene trovato.	Attendere il risultato con await.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; parola chiave node_type, page_index, text_query, max_results=100.	Restituisce i nodi superficiali corrispondenti ai filtri.	SearchAstNodesResponse	NextPDFAPIError.	Attendere il risultato con await.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Confronta due documenti dal punto di vista strutturale.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Attendere il risultato con await.

Usare il client asincrono come gestore di contesto, raggruppando due estrazioni in modo 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}")

Modelli

Ogni risposta è un modello Pydantic. Importare le classi dei modelli da nextpdf o da nextpdf.models.ast.

Simbolo	Tipo	Campi principali	Note
AstDocument	Radice del documento	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (proprietà).	Restituito da get_document_ast(). Accetta schemaVersion, sourceHash, pageCount.
AstNode	Nodo dell’albero	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Nodo ricorsivo che rappresenta l’albero del documento.
AstNodeMeta	Metadati della risposta	etag, pages_processed.	Congelato; allegato alle risposte di nodo e di ricerca.
AstNodeShallow	Risultato della ricerca	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Congelato; senza elementi figlio profondi.
BoundingBox	Oggetto valore	x, y, width, height (ciascuno 0.0–1.0).	Coordinate di pagina normalizzate.
CitationAnchor	Oggetto valore	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Record di provenienza associato a ciascun blocco.
CitedTextBlock	Blocco di testo	text, citation: CitationAnchor, node_type, chunk_index, depth.	Ogni elemento dell’elenco extract_cited_text().
CitedTableBlock	Blocco di tabella	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Congelato; rappresenta una tabella.
CitedTableCell	Cella di tabella	row, col, row_span, col_span, text, bbox, confidence.	Congelato; rappresenta una cella.
NodeType	Enum	document, section, heading, paragraph, list, table, figure e altri.	Enum di stringhe per i valori del tipo di nodo.
GetAstNodeResponse	Risposta	node: AstNode, meta: AstNodeMeta.	Restituito da get_ast_node().
SearchAstNodesResponse	Risposta	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Restituito da search_ast_nodes().
ExtractCitedTablesResponse	Risposta	tables: list[CitedTableBlock], table_count, pages_processed.	Restituito da extract_cited_tables().
AstDiffEntry	Elemento di diff	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Una modifica all’interno di un diff.
AstDiffSummary	Totali del diff	added_node_count, removed_node_count, changed_node_count.	Conteggi aggregati.
GetAstDiffResponse	Risposta	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Restituito da get_ast_diff().

Leggere un’ancora di citazione da un blocco di testo estratto:

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]}"

Comandi della CLI

Il comando nextpdf dell’SDK esegue l’estrazione dal terminale. Passare --base-url e --api-key oppure impostare NEXTPDF_BASE_URL e NEXTPDF_API_KEY nell’ambiente. Ogni comando tranne version richiede le impostazioni di connessione. Un valore PDF_PATH pari a - legge i byte PDF dallo standard input.

Simbolo	Parametri	Comportamento predefinito	Valore restituito	Genera o fallisce con	Note
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Emette i blocchi di testo citati come JSON.	Scrive sullo standard output o nel file --output.	Codice di uscita 1 in caso di qualsiasi NextPDFError.	--page seleziona un indice di pagina in base 0.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Emette le tabelle come JSON.	Scrive sullo standard output o nel file --output.	Codice di uscita 1 in caso di qualsiasi NextPDFError.	--format csv scrive un blocco CSV per tabella.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Emette l’AST semantico completo come JSON.	Scrive sullo standard output o nel file --output.	Codice di uscita 1 in caso di qualsiasi NextPDFError.	Usare --token-budget per limitare la dimensione della risposta.
nextpdf info	PDF_PATH.	Emette i metadati del documento: numero di pagine, versione dello schema, hash di origine, token stimati e riepilogo della radice.	Scrive il JSON sullo standard output o nel file --output.	Codice di uscita 1 in caso di qualsiasi NextPDFError.	Un comando di ispezione leggero.
nextpdf version	nessuno.	Stampa la versione dell’SDK installata.	Scrive sullo standard output.	nessuna prevista.	Non contatta alcun server; non richiede credenziali.
python -m nextpdf.mcp	nessuno (legge NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Esegue il server Model Context Protocol sullo standard input/output.	Processo server a esecuzione prolungata.	RuntimeError quando le variabili di ambiente non sono impostate.	Richiede l’extra nextpdf[mcp].

Estrarre le tabelle come valori separati da virgola (CSV) da un intervallo di pagine:

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

Eccezioni

La gerarchia delle eccezioni risiede in nextpdf.models.errors ed è riesportata da nextpdf. Intercettare la classe più specifica su cui il codice può agire, quindi usare la classe di base come fallback. Il server segnala l’errore con una semantica di stato HTTP allineata a RFC 9110. Ogni eccezione trasporta il valore status_code di origine e, ove applicabile, un valore error_code.

Simbolo	Classe di base	status_code	Quando viene generata	Note
NextPDFError	Exception	facoltativo	Base per ogni errore dell’SDK.	Trasporta un valore facoltativo status_code. Intercettare per ultima come fallback.
NextPDFAPIError	NextPDFError	obbligatorio	L’endpoint Connect ha restituito un errore HTTP.	Aggiunge error_code.
NextPDFLicenseError	NextPDFAPIError	402	La funzionalità richiede una licenza di livello superiore lato server.	error_code è license/tier-required.
QuotaExceededError	NextPDFAPIError	429	È stato superato un limite di frequenza o una quota.	Trasporta retry_after; rispettarlo prima di riprovare.
AstNoStructTreeError	NextPDFAPIError	422	Il PDF non è contrassegnato e il ripiego euristico non è abilitato.	Abilitare la modalità euristica o fornire un PDF contrassegnato.
AstBuildTimeoutError	NextPDFAPIError	504	La costruzione dell’AST è andata in timeout sul server.	Ridurre l’intervallo di pagine e riprovare.

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)

Note di sviluppo

• Il client sincrono NextPDF delega ogni chiamata a AsyncNextPDF. È sicuro chiamarlo da un notebook o da un thread che esegue già un ciclo di eventi, perché la coroutine viene inviata a un thread di lavoro quando viene rilevato un ciclo in esecuzione.
• È preferibile la forma asincrona con gestore di contesto async with AsyncNextPDF(...) as client: affinché il pool di connessioni venga chiuso in modo deterministico. Quando si costruisce AsyncNextPDF direttamente, chiamare close() manualmente.
• Il token bearer non viene mai registrato né inserito nei messaggi di errore e la verifica TLS (Transport Layer Security) è abilitata per impostazione predefinita. Non incorporare le credenziali nel codice sorgente; leggerle dall’ambiente o da un gestore di segreti.
• Tutti i modelli sono classi Pydantic v2; diversi modelli di risposta sono congelati (immutabili). Trattare i blocchi estratti come valori di sola lettura.
• La CLI termina con il codice di uscita 1 in caso di qualsiasi NextPDFError e stampa il messaggio sullo standard error. Integrare tale codice di uscita nelle pipeline.

Vedere anche

• Guida per sviluppatori dell’SDK Python — architettura, raggruppamento asincrono e gestione degli errori.
• CLI Python — estrazione da terminale e streaming per file di grandi dimensioni.
• Server MCP Python — esporre strumenti di estrazione agli agenti IA.
• RFC 9110 (HTTP Semantics) e RFC 9457 (Problem Details for HTTP APIs) descrivono la semantica di stato e i corpi di errore leggibili dalla macchina restituiti dall’endpoint Connect. Consultare l’indice delle RFC IETF per il testo autorevole.