Référence de l'API Python

En bref

Le SDK Python de NextPDF expose deux clients, un espace de noms de méthodes ast commun aux deux, un ensemble de modèles Pydantic qui typent chaque réponse, une CLI nextpdf et une hiérarchie d’exceptions à six classes. Cette page sert de référence pour chacun de ces symboles.

Importe l’API publique depuis le paquet de premier niveau :

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

Chaque méthode d’extraction accepte des octets PDF bruts (bytes) comme premier argument positionnel et renvoie un modèle Pydantic typé. Les options passées uniquement par mot-clé viennent ensuite. Les méthodes synchrones NextPDF.ast.* et asynchrones AsyncNextPDF.ast.* partagent des signatures identiques. Les méthodes asynchrones sont des coroutines à appeler avec await.

Client

Le client synchrone NextPDF encapsule le client asynchrone et exécute chaque coroutine jusqu’à son terme. Le client asynchrone AsyncNextPDF est également un gestionnaire de contexte asynchrone. Privilégie la forme avec gestionnaire de contexte pour fermer le transport sous-jacent de façon déterministe.

Constructeurs

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
NextPDF(*, base_url, api_key, api_version='v1')	URL de base, clé d’API passée uniquement par mot-clé, version d’API facultative.	Construit un client synchrone relié à un serveur distant.	NextPDF	ValueError quand base_url ou api_key est vide.	Les méthodes exécutent le travail asynchrone de façon synchrone, sans risque dans les notebooks et dans une boucle d’événements déjà active.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	URL de base, clé d’API passée uniquement par mot-clé, version d’API facultative, backend injecté facultatif.	Construit un client asynchrone relié à un serveur distant quand aucun backend n’est injecté.	AsyncNextPDF	ValueError quand base_url ou api_key est vide et qu’aucun backend n’est fourni.	Passe backend= pour injecter un backend personnalisé ou local dans les tests.
AsyncNextPDF.__aenter__()	aucun.	Entre dans le contexte asynchrone et renvoie le client.	AsyncNextPDF	aucune attendue.	Utilise async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Arguments d’exception ignorés.	Appelle close() à la sortie du contexte.	None	aucune attendue.	Libère le transport même si le corps lève une exception.
AsyncNextPDF.close()	aucun.	Ferme le backend distant qu’il possède et libère le pool de connexions.	None	aucune attendue.	Idempotent ; les backends injectés ne sont pas fermés.

Garde la clé d’API hors du code source. Lis base_url et api_key dans l’environnement (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) ou depuis un gestionnaire de secrets.

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éthodes AST synchrones — NextPDF.ast.*

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
NextPDF.ast.get_document_ast()	pdf_data: bytes ; mots-clés page_range_start, page_range_end, token_budget.	Construit l’AST sémantique complet pour toutes les pages.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Réduis la plage de pages si une construction dépasse le délai imparti.
NextPDF.ast.extract_cited_text()	pdf_data: bytes ; mots-clés page_index, headings_only.	Extrait chaque bloc de texte doté d’une ancre de citation.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Définis headings_only=True pour ne récupérer que les nœuds de titre.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes ; mot-clé page_range (dict avec start et end).	Extrait chaque tableau avec des ancres de citation par cellule.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Omets page_range pour analyser tout le document.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Récupère un nœud à partir de son identifiant.	GetAstNodeResponse	NextPDFError quand le nœud est introuvable.	node_id suit le format ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes ; mots-clés node_type, page_index, text_query, max_results=100.	Renvoie les nœuds superficiels qui correspondent aux filtres.	SearchAstNodesResponse	NextPDFAPIError.	text_query effectue une correspondance de sous-chaîne insensible à la casse.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Compare deux documents sur le plan structurel.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Signale les nœuds ajoutés, supprimés et modifiés.

Méthodes AST asynchrones — AsyncNextPDF.ast.*

Chaque méthode asynchrone est une coroutine avec les mêmes paramètres, valeurs par défaut, type de retour et modes d’échec que son équivalent synchrone ci-dessus. Appelle-la avec await dans un runtime asyncio.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes ; mots-clés page_range_start, page_range_end, token_budget.	Construit l’AST sémantique complet pour toutes les pages.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Attends le résultat avec await.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes ; mots-clés page_index, headings_only.	Extrait chaque bloc de texte doté d’une ancre de citation.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Attends le résultat avec await.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes ; mot-clé page_range.	Extrait chaque tableau avec des ancres de citation par cellule.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Attends le résultat avec await.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Récupère un nœud à partir de son identifiant.	GetAstNodeResponse	NextPDFError quand le nœud est introuvable.	Attends le résultat avec await.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes ; mots-clés node_type, page_index, text_query, max_results=100.	Renvoie les nœuds superficiels qui correspondent aux filtres.	SearchAstNodesResponse	NextPDFAPIError.	Attends le résultat avec await.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Compare deux documents sur le plan structurel.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Attends le résultat avec await.

Voici le client asynchrone utilisé comme gestionnaire de contexte, avec deux extractions par lots en parallèle :

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

Modèles

Chaque réponse est un modèle Pydantic. Importe les classes de modèles depuis nextpdf ou depuis nextpdf.models.ast.

Symbole	Type	Champs clés	Notes
AstDocument	Racine du document	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (propriété).	Renvoyé par get_document_ast(). Accepte les alias schemaVersion, sourceHash, pageCount.
AstNode	Nœud de l’arbre	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Nœud récursif qui représente l’arbre du document.
AstNodeMeta	Métadonnées de réponse	etag, pages_processed.	Figé ; attaché aux réponses de nœud et de recherche.
AstNodeShallow	Résultat de recherche	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Figé ; ne contient pas d’enfants profonds.
BoundingBox	Objet-valeur	x, y, width, height (chacun de 0.0–1.0).	Coordonnées de page normalisées.
CitationAnchor	Objet-valeur	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Enregistrement de provenance associé à chaque bloc.
CitedTextBlock	Bloc de texte	text, citation: CitationAnchor, node_type, chunk_index, depth.	Chaque élément de la liste renvoyée par extract_cited_text().
CitedTableBlock	Bloc de tableau	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Figé ; représente un seul tableau.
CitedTableCell	Cellule de tableau	row, col, row_span, col_span, text, bbox, confidence.	Figé ; représente une seule cellule.
NodeType	Énumération	document, section, heading, paragraph, list, table, figure, et d’autres.	Énumération de chaînes pour les valeurs de type de nœud.
GetAstNodeResponse	Réponse	node: AstNode, meta: AstNodeMeta.	Renvoyé par get_ast_node().
SearchAstNodesResponse	Réponse	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Renvoyé par search_ast_nodes().
ExtractCitedTablesResponse	Réponse	tables: list[CitedTableBlock], table_count, pages_processed.	Renvoyé par extract_cited_tables().
AstDiffEntry	Élément de diff	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Une modification dans un diff.
AstDiffSummary	Totaux du diff	added_node_count, removed_node_count, changed_node_count.	Décomptes agrégés.
GetAstDiffResponse	Réponse	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Renvoyé par get_ast_diff().

Lis l’ancre de citation d’un bloc de texte extrait :

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

Commandes CLI

La commande nextpdf lance l’extraction depuis le terminal. Passe --base-url et --api-key, ou définis NEXTPDF_BASE_URL et NEXTPDF_API_KEY dans l’environnement. À l’exception de version, chaque commande requiert des paramètres de connexion. Si PDF_PATH vaut -, les octets PDF sont lus depuis l’entrée standard.

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
nextpdf extract text	PDF_PATH ; --format {json,markdown,plain}, --page, --headings-only.	Produit les blocs de texte cités au format JSON.	Écrit sur la sortie standard ou dans le fichier --output.	Code de sortie 1 pour toute NextPDFError.	--page sélectionne un seul index de page en base 0.
nextpdf extract tables	PDF_PATH ; --format {json,csv}, --page-start, --page-end.	Produit les tableaux au format JSON.	Écrit sur la sortie standard ou dans le fichier --output.	Code de sortie 1 pour toute NextPDFError.	--format csv écrit un bloc CSV par tableau.
nextpdf ast	PDF_PATH ; --page-start, --page-end, --token-budget.	Produit l’AST sémantique complet au format JSON.	Écrit sur la sortie standard ou dans le fichier --output.	Code de sortie 1 pour toute NextPDFError.	Utilise --token-budget pour borner la taille de la réponse.
nextpdf info	PDF_PATH.	Produit les métadonnées du document : nombre de pages, version du schéma, hachage de la source, tokens estimés, résumé de la racine.	Écrit le JSON sur la sortie standard ou dans le fichier --output.	Code de sortie 1 pour toute NextPDFError.	Commande d’inspection légère.
nextpdf version	aucun.	Affiche la version du SDK installée.	Écrit sur la sortie standard.	aucune attendue.	Ne contacte aucun serveur ; n’a besoin d’aucun identifiant.
python -m nextpdf.mcp	aucun (lit NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Exécute le serveur Model Context Protocol sur les entrées/sorties standard.	Processus serveur de longue durée.	RuntimeError quand les variables d’environnement ne sont pas définies.	Requiert l’extra nextpdf[mcp].

Extrais les tableaux sous forme de valeurs séparées par des virgules (CSV) à partir d’une plage de pages :

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

Exceptions

La hiérarchie d’exceptions se trouve dans nextpdf.models.errors et est réexportée depuis nextpdf. Intercepte la classe la plus spécifique sur laquelle ton code peut agir, puis utilise la classe de base en dernier recours. Le serveur signale les échecs avec une sémantique de statut HTTP alignée sur la RFC 9110. Chaque exception porte le status_code d’origine et, le cas échéant, un error_code.

Symbole	Classe de base	status_code	Quand elle est levée	Notes
NextPDFError	Exception	facultatif	Base de toute erreur du SDK.	Porte un status_code facultatif. Intercepte-la en dernier recours.
NextPDFAPIError	NextPDFError	requis	Le point de terminaison Connect a renvoyé une erreur HTTP.	Ajoute error_code.
NextPDFLicenseError	NextPDFAPIError	402	La fonctionnalité requiert une licence de niveau supérieur sur le serveur.	error_code vaut license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Une limite de débit ou un quota a été dépassé.	Porte retry_after ; respecte-le avant de réessayer.
AstNoStructTreeError	NextPDFAPIError	422	Le PDF n’est pas balisé et le mode de repli heuristique n’est pas activé.	Active le mode heuristique ou fournis un PDF balisé.
AstBuildTimeoutError	NextPDFAPIError	504	La construction de l’AST a dépassé le délai imparti sur le serveur.	Réduis la plage de pages et réessaie.

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)

Notes de développement

• Le client synchrone NextPDF délègue chaque appel à AsyncNextPDF. Tu peux l’appeler sans risque depuis un notebook ou un thread qui exécute déjà une boucle d’événements, car la coroutine est déléguée à un thread de travail quand une boucle active est détectée.
• Privilégie la forme avec gestionnaire de contexte asynchrone async with AsyncNextPDF(...) as client: pour que le pool de connexions soit fermé de façon déterministe. Quand tu construis AsyncNextPDF directement, appelle close() toi-même.
• Le jeton d’authentification n’est jamais journalisé ni placé dans les messages d’erreur, et la vérification TLS (Transport Layer Security) est activée par défaut. N’intègre pas d’identifiants dans le code source ; lis-les depuis l’environnement ou un gestionnaire de secrets.
• Tous les modèles sont des classes Pydantic v2 ; plusieurs modèles de réponse sont figés (immuables). Traite les blocs extraits comme des valeurs en lecture seule.
• La CLI se termine avec le code de sortie 1 pour toute NextPDFError et affiche le message sur la sortie d’erreur standard. Intègre ce code de sortie dans tes pipelines.

Voir aussi

• Guide du développeur du SDK Python — architecture, traitement asynchrone par lots et gestion des échecs.
• CLI Python — extraction au terminal et streaming pour les gros fichiers.
• Serveur MCP Python — expose les outils d’extraction aux agents d’IA.
• La RFC 9110 (HTTP Semantics) et la RFC 9457 (Problem Details for HTTP APIs) décrivent la sémantique des statuts et les corps d’erreur lisibles par machine renvoyés par le point de terminaison Connect. Consulte l’index des RFC de l’IETF pour le texte de référence.