Python-API-Referenz

Auf einen Blick

Das NextPDF Python Software Development Kit (SDK) stellt zwei Clients, einen von beiden gemeinsam genutzten ast-Methoden-Namespace, eine Reihe von Pydantic-Modellen zur Typisierung jeder Antwort, eine nextpdf-Befehlszeilenschnittstelle (CLI) und eine Ausnahmehierarchie aus sechs Klassen bereit. Diese Seite ist die Referenz für alle diese Symbole.

Importieren Sie die öffentliche Schnittstelle aus dem Paket der obersten Ebene:

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

Jede Extraktionsmethode akzeptiert rohe PDF-Bytes (bytes) als erstes Positionsargument und liefert ein typisiertes Pydantic-Modell. Danach folgen ausschließlich als Schlüsselwort übergebene Optionen. Die synchronen NextPDF.ast.*-Methoden und die asynchronen AsyncNextPDF.ast.*-Methoden haben identische Signaturen. Die asynchronen Methoden sind Coroutinen, die Sie mit await aufrufen.

Client

Der synchrone NextPDF-Client umschließt den asynchronen Client und führt jede Coroutine bis zum Abschluss aus. Der asynchrone AsyncNextPDF-Client ist außerdem ein asynchroner Kontextmanager. Bevorzugen Sie die Kontextmanager-Form, damit der zugrunde liegende Transport deterministisch geschlossen wird.

Konstruktoren

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft bzw. schlägt fehl mit	Hinweise
NextPDF(*, base_url, api_key, api_version='v1')	Nur als Schlüsselwort übergebene Basis-URL, API-Schlüssel, optionale API-Version.	Erzeugt einen synchronen Client für ein Remote-Backend.	NextPDF	ValueError, wenn base_url oder api_key leer ist.	Die Methoden führen asynchrone Arbeit synchron aus und sind auch in Notebooks sowie innerhalb einer laufenden Event-Loop sicher verwendbar.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	Nur als Schlüsselwort übergebene Basis-URL, API-Schlüssel, optionale API-Version, optional eingeschleustes Backend.	Erzeugt einen asynchronen Client für ein Remote-Backend, wenn kein Backend eingeschleust wird.	AsyncNextPDF	ValueError, wenn base_url oder api_key leer ist und kein backend übergeben wird.	Übergeben Sie backend=, um in Tests ein eigenes oder lokales Backend einzuschleusen.
AsyncNextPDF.__aenter__()	keine.	Betritt den asynchronen Kontext und gibt den Client zurück.	AsyncNextPDF	keine erwartet.	Verwenden Sie async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Ignorierte Ausnahmeargumente.	Ruft beim Verlassen des Kontexts close() auf.	None	keine erwartet.	Gibt den Transport auch dann frei, wenn der Block eine Ausnahme wirft.
AsyncNextPDF.close()	keine.	Schließt das eigene Remote-Backend und gibt den Verbindungspool frei.	None	keine erwartet.	Idempotent; eingeschleuste Backends werden nicht geschlossen.

Halten Sie den API-Schlüssel aus dem Quellcode heraus. Lesen Sie base_url und api_key aus der Umgebung (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) oder einem 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.*

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft bzw. schlägt fehl mit	Hinweise
NextPDF.ast.get_document_ast()	pdf_data: bytes; Schlüsselwort page_range_start, page_range_end, token_budget.	Baut den vollständigen Semantic AST über alle Seiten auf.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Verkleinern Sie den Seitenbereich, wenn ein Build die Zeit überschreitet.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; Schlüsselwort page_index, headings_only.	Extrahiert jeden Textblock mit einem Zitationsanker.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Setze headings_only=True, um nur Überschriften-Knoten abzurufen.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; Schlüsselwort page_range (dict mit start und end).	Extrahiert jede Tabelle mit Zitationsankern auf Zellenebene.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Lassen Sie page_range weg, um das gesamte Dokument zu durchsuchen.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Ruft einen Knoten anhand seiner Kennung ab.	GetAstNodeResponse	NextPDFError, wenn der Knoten nicht gefunden wird.	node_id hat das Format ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; Schlüsselwort node_type, page_index, text_query, max_results=100.	Gibt flache Knoten zurück, die zu den Filtern passen.	SearchAstNodesResponse	NextPDFAPIError.	text_query ist ein Teilstring-Abgleich ohne Beachtung der Groß- und Kleinschreibung.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Vergleicht zwei Dokumente strukturell.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Meldet hinzugefügte, entfernte und geänderte Knoten.

Asynchrone AST-Methoden — AsyncNextPDF.ast.*

Jede asynchrone Methode ist eine Coroutine mit denselben Parametern und Standardwerten, demselben Rückgabetyp und denselben Fehlermodi wie ihr synchrones Gegenstück oben. Rufen Sie sie mit await innerhalb einer asyncio-Laufzeit auf.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft bzw. schlägt fehl mit	Hinweise
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; Schlüsselwort page_range_start, page_range_end, token_budget.	Baut den vollständigen Semantic AST über alle Seiten auf.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	await das Ergebnis.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; Schlüsselwort page_index, headings_only.	Extrahiert jeden Textblock mit einem Zitationsanker.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	await das Ergebnis.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; Schlüsselwort page_range.	Extrahiert jede Tabelle mit Zitationsankern auf Zellenebene.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	await das Ergebnis.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Ruft einen Knoten anhand seiner Kennung ab.	GetAstNodeResponse	NextPDFError, wenn der Knoten nicht gefunden wird.	await das Ergebnis.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; Schlüsselwort node_type, page_index, text_query, max_results=100.	Gibt flache Knoten zurück, die zu den Filtern passen.	SearchAstNodesResponse	NextPDFAPIError.	await das Ergebnis.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Vergleicht zwei Dokumente strukturell.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	await das Ergebnis.

So bündelt der asynchrone Client als Kontextmanager zwei Extraktionen nebenläufig:

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

Modelle

Jede Antwort ist ein Pydantic-Modell. Importieren Sie die Modellklassen aus nextpdf oder aus nextpdf.models.ast.

Symbol	Art	Schlüsselfelder	Hinweise
AstDocument	Dokumentwurzel	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (Property).	Wird von get_document_ast() zurückgegeben. Akzeptiert die Aliasnamen schemaVersion, sourceHash, pageCount.
AstNode	Baumknoten	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Rekursiver Knoten, der den Dokumentbaum trägt.
AstNodeMeta	Antwortmetadaten	etag, pages_processed.	Eingefroren; an Knoten- und Suchantworten angehängt.
AstNodeShallow	Suchtreffer	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Eingefroren; keine verschachtelten Kinder.
BoundingBox	Wertobjekt	x, y, width, height (jeweils 0.0–1.0).	Normalisierte Seitenkoordinaten.
CitationAnchor	Wertobjekt	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Der Provenance-Datensatz jedes Blocks.
CitedTextBlock	Textblock	text, citation: CitationAnchor, node_type, chunk_index, depth.	Jedes Element in der Liste von extract_cited_text().
CitedTableBlock	Tabellenblock	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Eingefroren; eine Tabelle.
CitedTableCell	Tabellenzelle	row, col, row_span, col_span, text, bbox, confidence.	Eingefroren; eine Zelle.
NodeType	Enum	document, section, heading, paragraph, list, table, figure und weitere.	String-Enum mit Werten für Knotentypen.
GetAstNodeResponse	Antwort	node: AstNode, meta: AstNodeMeta.	Wird von get_ast_node() zurückgegeben.
SearchAstNodesResponse	Antwort	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Wird von search_ast_nodes() zurückgegeben.
ExtractCitedTablesResponse	Antwort	tables: list[CitedTableBlock], table_count, pages_processed.	Wird von extract_cited_tables() zurückgegeben.
AstDiffEntry	Diff-Element	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Eine Änderung in einem Diff.
AstDiffSummary	Diff-Zusammenfassung	added_node_count, removed_node_count, changed_node_count.	Aggregierte Zähler.
GetAstDiffResponse	Antwort	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Wird von get_ast_diff() zurückgegeben.

Lesen Sie einen Zitationsanker aus einem extrahierten Textblock:

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-Befehle

Der Befehl nextpdf führt Extraktionen im Terminal aus. Übergeben Sie --base-url und --api-key, oder setzen Sie NEXTPDF_BASE_URL und NEXTPDF_API_KEY in der Umgebung. Jeder Befehl außer version benötigt Verbindungseinstellungen. Ein PDF_PATH von - liest PDF-Bytes von der Standardeingabe.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft bzw. schlägt fehl mit	Hinweise
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Gibt zitierte Textblöcke als JSON aus.	Schreibt in die Standardausgabe oder in die --output-Datei.	Exit-Code 1 bei jedem NextPDFError.	--page wählt einen 0-basierten Seitenindex.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Gibt Tabellen als JSON aus.	Schreibt in die Standardausgabe oder in die --output-Datei.	Exit-Code 1 bei jedem NextPDFError.	--format csv schreibt einen CSV-Block pro Tabelle.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Gibt den vollständigen Semantic AST als JSON aus.	Schreibt in die Standardausgabe oder in die --output-Datei.	Exit-Code 1 bei jedem NextPDFError.	Verwende --token-budget, um die Antwortgröße zu begrenzen.
nextpdf info	PDF_PATH.	Gibt Dokumentmetadaten aus: Seitenanzahl, Schema-Version, Quell-Hash, geschätzte Tokens und Wurzelzusammenfassung.	Schreibt JSON in die Standardausgabe oder in die --output-Datei.	Exit-Code 1 bei jedem NextPDFError.	Ein leichtgewichtiger Inspektionsbefehl.
nextpdf version	keine.	Gibt die installierte SDK-Version aus.	Schreibt in die Standardausgabe.	keine erwartet.	Kontaktiert keinen Server; benötigt keine Anmeldedaten.
python -m nextpdf.mcp	keine (liest NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Führt den Model Context Protocol-Server über die Standardein- und -ausgabe aus.	Langlaufender Serverprozess.	RuntimeError, wenn die Umgebungsvariablen nicht gesetzt sind.	Erfordert das Extra nextpdf[mcp].

Extrahieren Sie Tabellen als kommagetrennte Werte (CSV) aus einem Seitenbereich:

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

Ausnahmen

Die Ausnahmehierarchie liegt in nextpdf.models.errors und wird aus nextpdf re-exportiert. Fangen Sie die spezifischste Klasse ab, auf die Ihr Code reagieren kann, und greifen Sie dann auf die Basisklasse zurück. Der Server signalisiert Fehler mit HTTP-Status-Semantik, die an RFC 9110 ausgerichtet ist. Jede Ausnahme trägt den ursprünglichen status_code und, wo zutreffend, einen error_code.

Symbol	Basisklasse	status_code	Wann sie ausgelöst wird	Hinweise
NextPDFError	Exception	optional	Basis für alle SDK-Fehler.	Trägt einen optionalen status_code. Fangen Sie ihn zuletzt als Rückfalloption ab.
NextPDFAPIError	NextPDFError	erforderlich	Der Connect-Endpunkt hat einen HTTP-Fehler zurückgegeben.	Fügt error_code hinzu.
NextPDFLicenseError	NextPDFAPIError	402	Die Funktion erfordert auf dem Server eine höhere Lizenzstufe.	error_code ist license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Ein Rate-Limit oder Kontingent wurde überschritten.	Trägt retry_after; beachten Sie ihn vor einem erneuten Versuch.
AstNoStructTreeError	NextPDFAPIError	422	Das PDF ist nicht getaggt und der heuristische Fallback ist nicht aktiviert.	Aktiviere den heuristischen Modus oder liefere ein getaggtes PDF.
AstBuildTimeoutError	NextPDFAPIError	504	Der AST-Build hat auf dem Server die Zeit überschritten.	Verkleinern Sie den Seitenbereich und versuchen Sie es erneut.

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)

Entwicklungshinweise

• Der synchrone NextPDF-Client delegiert jeden Aufruf an AsyncNextPDF. Sie können ihn sicher aus einem Notebook oder einem Thread aufrufen, der bereits eine Event-Loop ausführt, weil die Coroutine an einen Worker-Thread weitergereicht wird, sobald eine laufende Loop erkannt wird.
• Bevorzugen Sie die asynchrone Kontextmanager-Form async with AsyncNextPDF(...) as client:, damit der Verbindungspool deterministisch geschlossen wird. Wenn Sie AsyncNextPDF direkt erzeugen, rufen Sie close() selbst auf.
• Das Bearer-Token wird niemals protokolliert oder in Fehlermeldungen aufgenommen, und die TLS-Prüfung (Transport Layer Security) ist standardmäßig aktiviert. Betten Sie keine Anmeldedaten in den Quellcode ein; lesen Sie sie aus der Umgebung oder einem Secret-Manager.
• Alle Modelle sind Pydantic-v2-Klassen; mehrere Antwortmodelle sind eingefroren (unveränderlich). Behandle extrahierte Blöcke als schreibgeschützte Werte.
• Die CLI beendet sich bei jedem NextPDFError mit Exit-Code 1 und gibt die Meldung auf der Standardfehlerausgabe aus. Binden Sie diesen Exit-Code in Pipelines ein.

Siehe auch

• Python-SDK-Entwicklerhandbuch — Architektur, asynchrones Bündeln und Fehlerbehandlung.
• Python-CLI — Terminal-Extraktion und Streaming für große Dateien.
• Python-MCP-Server — Extraktionswerkzeuge für KI-Agenten bereitstellen.
• RFC 9110 (HTTP Semantics) und RFC 9457 (Problem Details for HTTP APIs) beschreiben die Status-Semantik und die maschinenlesbaren Fehlerkörper, die der Connect-Endpunkt zurückgibt. Den maßgeblichen Text finden Sie im IETF-RFC-Index.