Python API-referentie

In het kort

De NextPDF Python Software Development Kit (SDK) biedt twee clients, één gedeelde namespace met Abstract Syntax Tree-methoden (AST) genaamd ast, Pydantic-modellen voor elke respons, een nextpdf-opdrachtregelinterface (CLI) en een uitzonderingshiërarchie van zes klassen. Gebruik deze pagina als referentie voor de publieke symbolen van de application programming interface (API) voor het werken met Portable Document Format-documenten (PDF).

Importeer publieke symbolen uit het pakket op het hoogste niveau:

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

Elke extractiemethode accepteert ruwe PDF-bytes (bytes) als eerste positionele argument en retourneert een getypeerd Pydantic-model. Geef opties door als alleen-trefwoordargumenten. De synchrone NextPDF.ast.*-methoden en de asynchrone AsyncNextPDF.ast.*-methoden hebben identieke signaturen. Asynchrone methoden zijn coöroutines; roep ze aan met await.

Client

De synchrone NextPDF-client is een wrapper rond de asynchrone client en voert elke coöroutine tot voltooiing uit. AsyncNextPDF is zowel een asynchrone client als een asynchrone contextmanager. Gebruik bij voorkeur de contextmanager-vorm, zodat het onderliggende transport deterministisch wordt gesloten.

Constructors

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of mislukt met	Notities
NextPDF(*, base_url, api_key, api_version='v1')	Alleen-trefwoordargumenten voor basis-URL, API-sleutel en optionele API-versie.	Maakt een synchrone client voor de externe back-end.	NextPDF	ValueError wanneer base_url of api_key leeg is.	Voert asynchroon werk synchroon uit; veilig in notebooks en binnen een actieve event loop.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	Alleen-trefwoordargumenten voor basis-URL, API-sleutel, optionele API-versie en optionele geïnjecteerde back-end.	Maakt een asynchrone client voor de externe back-end wanneer er geen back-end is geïnjecteerd.	AsyncNextPDF	ValueError wanneer base_url of api_key leeg is en er geen backend is opgegeven.	Geef backend= door om in tests een aangepaste of lokale back-end te injecteren.
AsyncNextPDF.__aenter__()	Geen.	Gaat de asynchrone context binnen en retourneert de client.	AsyncNextPDF	Geen verwacht.	Gebruik async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Genegeerde uitzonderingsargumenten.	Roept close() aan wanneer de context wordt verlaten.	None	Geen verwacht.	Maakt het transport vrij, ook wanneer de body een uitzondering werpt.
AsyncNextPDF.close()	Geen.	Sluit de eigen externe back-end en geeft de verbindingspool vrij.	None	Geen verwacht.	Idempotent; geïnjecteerde back-ends worden niet gesloten.

Bewaar de API-sleutel niet in de broncode. Lees base_url en api_key uit de omgeving (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) of uit een secret manager.

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

Synchrone AST-methoden — NextPDF.ast.*

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of mislukt met	Notities
NextPDF.ast.get_document_ast()	pdf_data: bytes; trefwoord page_range_start, page_range_end, token_budget.	Bouwt de volledige Semantic AST voor elke pagina.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Verklein het paginabereik wanneer een build een time-out krijgt.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; trefwoord page_index, headings_only.	Extraheert alle tekstblokken met citatieankers.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Stel headings_only=True in om alleen kopknooppunten op te halen.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; trefwoord page_range (dict met start en end).	Extraheert alle tabellen met citatieankers op celniveau.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Laat page_range weg om het hele document te scannen.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Haalt één knooppunt op via de identificator.	GetAstNodeResponse	NextPDFError wanneer het knooppunt niet wordt gevonden.	De node_id-indeling is ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; trefwoord node_type, page_index, text_query, max_results=100.	Retourneert ondiepe knooppunten die aan de filters voldoen.	SearchAstNodesResponse	NextPDFAPIError.	text_query matcht op een substring zonder onderscheid tussen hoofdletters en kleine letters.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Vergelijkt twee documenten op structuur.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Rapporteert toegevoegde, verwijderde en gewijzigde knooppunten.

Asynchrone AST-methoden — AsyncNextPDF.ast.*

Elke asynchrone methode is een coöroutine met dezelfde parameters, standaardwaarden, hetzelfde retourtype en dezelfde faalmodi als de synchrone tegenhanger. Roep de methode aan met await binnen een asyncio-runtime.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of mislukt met	Notities
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; trefwoord page_range_start, page_range_end, token_budget.	Bouwt de volledige Semantic AST voor elke pagina.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	await het resultaat.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; trefwoord page_index, headings_only.	Extraheert alle tekstblokken met citatieankers.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	await het resultaat.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; trefwoord page_range.	Extraheert alle tabellen met citatieankers op celniveau.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	await het resultaat.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Haalt één knooppunt op via de identificator.	GetAstNodeResponse	NextPDFError wanneer het knooppunt niet wordt gevonden.	await het resultaat.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; trefwoord node_type, page_index, text_query, max_results=100.	Retourneert ondiepe knooppunten die aan de filters voldoen.	SearchAstNodesResponse	NextPDFAPIError.	await het resultaat.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Vergelijkt twee documenten op structuur.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	await het resultaat.

Gebruik de asynchrone client als contextmanager om twee extracties tegelijk uit te voeren:

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

Modellen

Elke respons is een Pydantic-model. Importeer modelklassen uit nextpdf of nextpdf.models.ast.

Symbool	Soort	Belangrijkste velden	Notities
AstDocument	Documentwortel	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (property).	Geretourneerd door get_document_ast(). Accepteert aliassen schemaVersion, sourceHash en pageCount.
AstNode	Boomknooppunt	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Recursief knooppunt dat de documentboom bevat.
AstNodeMeta	Responsmetadata	etag, pages_processed.	Frozen; gekoppeld aan knooppunt- en zoekresponsen.
AstNodeShallow	Zoektreffer	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Frozen; bevat geen diepe onderliggende knooppunten.
BoundingBox	Waardeobject	x, y, width, height (elk 0.0–1.0).	Genormaliseerde coördinaten binnen een pagina.
CitationAnchor	Waardeobject	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Herkomstrecord voor elk blok.
CitedTextBlock	Tekstblok	text, citation: CitationAnchor, node_type, chunk_index, depth.	Elk item in de extract_cited_text()-lijst.
CitedTableBlock	Tabelblok	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Frozen; één tabel.
CitedTableCell	Tabelcel	row, col, row_span, col_span, text, bbox, confidence.	Frozen; één cel.
NodeType	Enum	document, section, heading, paragraph, list, table, figure en andere.	String-enum voor waarden van knooppunttypen.
GetAstNodeResponse	Respons	node: AstNode, meta: AstNodeMeta.	Geretourneerd door get_ast_node().
SearchAstNodesResponse	Respons	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Geretourneerd door search_ast_nodes().
ExtractCitedTablesResponse	Respons	tables: list[CitedTableBlock], table_count, pages_processed.	Geretourneerd door extract_cited_tables().
AstDiffEntry	Diff-item	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Eén wijziging in een diff.
AstDiffSummary	Diff-totalen	added_node_count, removed_node_count, changed_node_count.	Geaggregeerde aantallen.
GetAstDiffResponse	Respons	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Geretourneerd door get_ast_diff().

Lees het citatieanker van een geëxtraheerd tekstblok:

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

CLI-opdrachten

De nextpdf-opdracht voert extracties uit vanuit de terminal. Geef --base-url en --api-key, of stel NEXTPDF_BASE_URL en NEXTPDF_API_KEY in de omgeving in. Elke opdracht behalve version vereist verbindingsinstellingen. Als PDF_PATH de waarde - heeft, leest de opdracht PDF-bytes van de standaardinvoer.

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of mislukt met	Notities
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Geeft geciteerde tekstblokken uit als JavaScript Object Notation (JSON).	Schrijft naar de standaarduitvoer of een --output-bestand.	Afsluitcode 1 voor elke NextPDFError.	--page selecteert één op 0 gebaseerde pagina-index.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Geeft tabellen uit als JSON.	Schrijft naar de standaarduitvoer of een --output-bestand.	Afsluitcode 1 voor elke NextPDFError.	--format csv schrijft één blok met door komma’s gescheiden waarden (CSV) per tabel.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Geeft de volledige Semantic AST uit als JSON.	Schrijft naar de standaarduitvoer of een --output-bestand.	Afsluitcode 1 voor elke NextPDFError.	Gebruik --token-budget om de responsgrootte te begrenzen.
nextpdf info	PDF_PATH.	Geeft documentmetadata uit: aantal pagina’s, schemaversie, bronhash, geschat aantal tokens en wortelsamenvatting.	Schrijft JSON naar de standaarduitvoer of een --output-bestand.	Afsluitcode 1 voor elke NextPDFError.	Lichtgewicht inspectieopdracht.
nextpdf version	Geen.	Drukt de geïnstalleerde SDK-versie af.	Schrijft naar de standaarduitvoer.	Geen verwacht.	Neemt geen contact op met een server; heeft geen credentials nodig.
python -m nextpdf.mcp	Geen (leest NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Voert de Model Context Protocol-server uit via standaardinvoer/-uitvoer.	Langlopend serverproces.	RuntimeError wanneer de omgevingsvariabelen niet zijn ingesteld.	Vereist de nextpdf[mcp]-extra.

Tabellen extraheren als door komma’s gescheiden waarden (CSV) uit een paginabereik:

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

Uitzonderingen

De uitzonderingshiërarchie staat in nextpdf.models.errors en wordt opnieuw geëxporteerd vanuit nextpdf. Vang de meest specifieke klasse op die je code kan verwerken en val daarna terug op de basisklasse. De server meldt fouten met statussemantiek van Hypertext Transfer Protocol (HTTP), afgestemd op Request for Comments 9110 (RFC). Elke uitzondering bevat de oorspronkelijke status_code en, indien beschikbaar, een error_code.

Symbool	Basisklasse	status_code	Wanneer deze wordt geworpen	Notities
NextPDFError	Exception	optioneel	Basisklasse voor elke SDK-fout.	Bevat een optionele status_code. Vang deze als laatste fallback op.
NextPDFAPIError	NextPDFError	vereist	Het Connect-eindpunt retourneerde een HTTP-fout.	Voegt error_code toe.
NextPDFLicenseError	NextPDFAPIError	402	De server vereist voor deze functie een licentie van een hoger niveau.	error_code is license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Een snelheidslimiet of quotum is overschreden.	Bevat retry_after; respecteer deze waarde voordat je het opnieuw probeert.
AstNoStructTreeError	NextPDFAPIError	422	De PDF is niet getagd en de heuristische fallback is niet ingeschakeld.	Schakel de heuristische modus in of lever een getagde PDF aan.
AstBuildTimeoutError	NextPDFAPIError	504	Het bouwen van de AST kreeg op de server een time-out.	Verklein het paginabereik en probeer opnieuw.

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)

Ontwikkelnotities

• De synchrone NextPDF-client delegeert elke aanroep aan AsyncNextPDF. Je kunt deze aanroepen vanuit een notebook of een thread die al een event loop uitvoert, omdat de coöroutine naar een werkthread wordt doorgestuurd zodra een actieve loop wordt gedetecteerd.
• Gebruik bij voorkeur de asynchrone contextmanager-vorm async with AsyncNextPDF(...) as client: zodat de verbindingspool deterministisch wordt gesloten. Wanneer je AsyncNextPDF rechtstreeks aanmaakt, roep je zelf close().
• Het bearertoken wordt nooit gelogd of in foutmeldingen opgenomen, en Transport Layer Security-verificatie (TLS) is standaard ingeschakeld. Neem geen credentials op in de broncode; lees ze uit de omgeving of uit een secret manager.
• Alle modellen zijn Pydantic v2-klassen; verschillende responsmodellen zijn frozen (onveranderlijk). Behandel geëxtraheerde blokken als alleen-lezen waarden.
• De CLI sluit af met statuscode 1 voor elke NextPDFError en drukt het bericht af naar de standaardfoutuitvoer. Gebruik die afsluitcode in pipelines.

Zie ook

• Python SDK-ontwikkelaarsgids — architectuur, asynchrone batchverwerking en foutafhandeling.
• Python CLI — extractie vanaf de terminal en streaming voor grote bestanden.
• Python MCP-server — extractietools beschikbaar maken voor agenten met kunstmatige intelligentie (AI).
• RFC 9110 (HTTP Semantics) en RFC 9457 (Problem Details for HTTP APIs) beschrijven de statussemantiek en de machineleesbare foutinhoud die het Connect-eindpunt retourneert. Raadpleeg de IETF RFC-index voor de gezaghebbende tekst.