Entwicklerhandbuch für das Python-SDK

Auf einen Blick

Das NextPDF Python Software Development Kit (SDK) ist ein schlanker, typisierter Client für einen NextPDF Connect-Endpunkt. Ihre Anwendung ist für die Eingabevalidierung, den Umgang mit Anmeldedaten und die Nebenläufigkeitsrichtlinie verantwortlich; das SDK übernimmt den Aufbau der Anfrage, den Transport und die Typisierung der Antwort. Machen Sie diese Grenze explizit: Lesen Sie das PDF sicher ein, wählen Sie einen Client, rufen Sie die benötigte ast-Methode auf und behandeln Sie den konkreten Fehler.

Nutzen Sie dieses Handbuch, wenn Sie Extraktionsdienste, asyncio-Batch-Jobs, Werkzeuge für KI-Agenten oder einen Kommandozeilen-Workflow rund um das SDK entwickeln. Es setzt voraus, dass Sie den Überblick und den Schnelleinstieg gelesen haben und dass Ihnen Python 3.10 oder neuer sowie ein NextPDF Connect-Endpunkt zur Verfügung stehen.

Architekturgrenze

Schicht	Verantwortet von	Verantwortung	Hier nicht ablegen
Eingabequelle	Anwendung	Aufrufer autorisieren, PDF-Quelle validieren, Extraktionsrichtlinie wählen.	Literalwerte für Endpunkt-URL oder Anmeldedaten.
Client-Erstellung	Anwendung	base_url und api_key aus der Umgebung oder einem Secret-Manager lesen.	Hartcodierte Geheimnisse.
NextPDF / AsyncNextPDF	SDK	Anfrage erstellen, Connect aufrufen, typisierte Pydantic-Modelle zurückgeben.	Domänenlogik oder Speicherrichtlinie.
ast-Methoden-Namespace	SDK	Methodenaufrufe Connect-Endpunkten zuordnen und Antworten parsen.	Retry- oder Backoff-Richtlinie über das hinaus, was Sie konfigurieren.
NextPDF Connect-Endpunkt	Deployment	Extraktion ausführen, Authentifizierung, Kontingente und Lizenzierung erzwingen.	Anwendungsautorisierung.

Das SDK führt niemals optische Zeichenerkennung (OCR) aus. Ein gescanntes oder reines Bild-PDF erfordert vor der Extraktion einen OCR-Schritt; behandeln Sie das als Aufgabe der Anwendung außerhalb dieser Grenze.

Laufzeit-Lebenszyklus

Phase	Verhalten	Entwickleraktion
Client-Erstellung	base_url und api_key werden validiert; ein leerer Wert löst ValueError aus.	Lesen Sie beide Werte aus der Umgebung; schreiben Sie sie niemals fest in den Code.
Backend-Erstellung	Ein Remote-Backend öffnet eine gepoolte Verbindung zu Connect.	Verwenden Sie einen Client über mehrere Aufrufe hinweg wieder, statt ihn pro Anfrage neu zu erstellen.
Methodenaufruf	Die ast-Methode serialisiert die Anfrage, sendet die PDF-Bytes und parst die Antwort in ein Pydantic-Modell.	Übergeben Sie bereits validierte bytes.
Fehlerzuordnung	Ein nicht erfolgreicher HTTP-Status wird einer bestimmten Exception-Unterklasse zugeordnet.	Fangen Sie zuerst die spezifischste Klasse ab.
Herunterfahren	AsyncNextPDF.close() gibt den Verbindungspool frei; der asynchrone Context-Manager ruft die Methode für Sie auf.	Verwenden Sie async with oder rufen Sie close() in einem finally-Block auf.

Empfohlene Anwendungsstruktur

Pfad	Zweck
app/pdf/clients.py	Erstellt und cacht einen konfigurierten NextPDF oder AsyncNextPDF.
app/pdf/extraction.py	Anwendungs-Wrapper für Aufrufe der ast-Methoden.
app/pdf/validation.py	Validierung der PDF-Quelle, Größenlimits und Inhaltsprüfungen.
tests/pdf/	Tests für Extraktion, Fehlermodi und asynchrones Batching.

Trennen Sie die PDF-Validierung von der Extraktion. Die Extraktionsschicht sollte bereits autorisierte, größengeprüfte Bytes erhalten und sich als zusätzliche Verteidigungsebene weiterhin auf den Endpunkt verlassen.

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)

Synchrones Client-Muster

Verwenden Sie den synchronen NextPDF-Client für Skripte, Batch-Jobs und Notebooks. Validieren Sie die Eingabe, bevor Sie das SDK aufrufen, und behandeln Sie die konkreten Fehler, die der Aufruf auslösen kann.

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

Erwartete Struktur eines Ergebniselements:

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

Async- und Batching-Muster

Verwenden Sie den asynchronen AsyncNextPDF-Client in asyncio-Laufzeiten wie FastAPI. Erstellen Sie einen Client als asynchronen Context-Manager und teilen Sie ihn über nebenläufige Aufrufe hinweg; öffnen Sie keinen Client pro Dokument. Begrenzen Sie die Nebenläufigkeit mit einer Semaphore, damit Sie das Kontingent des Endpunkts einhalten.

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

Schreiben Sie niemals ein leeres except. Reagieren Sie entweder auf den Fehler, wandeln Sie ihn in ein definiertes Ergebnis um oder lösen Sie ihn erneut aus.

Erweiterungspunkte

Erweiterungspunkt	Verwendung	Einschränkung
AsyncNextPDF(backend=...)	Injizieren Sie in Tests ein eigenes oder lokales Backend.	Das Backend muss das PdfBackend-Protokoll erfüllen.
api_version-Argument	Fixieren Sie eine Connect-API-Version.	Standardmäßig v1; ändern Sie das nur, wenn der Endpunkt die Zielversion unterstützt.
Umgebungskonfiguration	Stellen Sie NEXTPDF_BASE_URL und NEXTPDF_API_KEY dem CLI und dem MCP-Server bereit.	Behandeln Sie den Schlüssel als ein auf die Arbeitslast beschränktes Geheimnis.
MCP-Server (python -m nextpdf.mcp)	Stellen Sie MCP-fähigen Agenten Extraktionswerkzeuge bereit.	Erfordert das nextpdf[mcp]-Extra und einen kontrollierten Endpunkt.

Entwicklungs-Workflow

1. Installieren Sie das SDK mit pip install nextpdf oder mit pip install nextpdf[mcp] für den Agenten-Server.
2. Lesen Sie NEXTPDF_BASE_URL und NEXTPDF_API_KEY aus der Umgebung, damit kein Geheimnis in die Versionsverwaltung gelangt.
3. Validieren Sie jede PDF-Quelle — Existenz, Größe und die %PDF--Magic-Bytes —, bevor Sie das SDK aufrufen.
4. Erstellen Sie einen Client pro Prozess und verwenden Sie ihn wieder; halten Sie ihn für asyncio mit async with offen.
5. Rufen Sie die spezifischste ast-Methode für die Aufgabe auf: extract_cited_text() für Fließtext, extract_cited_tables() für Tabellen, get_document_ast() nur, wenn Sie den vollständigen Baum brauchen.
6. Fangen Sie die spezifischste Exception ab, auf die Sie reagieren können, und greifen Sie dann auf NextPDFError zurück.
7. Verwenden Sie für Dokumente über 100 MiB den Streaming-Pfad des CLI, statt jeden Block im Speicher zu materialisieren.
8. Führen Sie die Typprüfung mit mypy im Strict-Modus aus und fügen Sie für jede Exception, die Sie behandeln, einen Fehlermodus-Test hinzu.

Fehlerbehandlung

Fehler	Exception	Empfohlene Reaktion
Nicht getaggtes PDF, Heuristik deaktiviert	AstNoStructTreeError (HTTP 422)	Aktivieren Sie den Heuristik-Modus auf dem Endpunkt oder liefern Sie ein getaggtes PDF.
Serverseitiges Build-Timeout	AstBuildTimeoutError (HTTP 504)	Reduzieren Sie den Seitenbereich und versuchen Sie es erneut.
Lizenzstufe erforderlich	NextPDFLicenseError (HTTP 402)	Aktualisieren Sie die Serverlizenz oder weichen Sie auf eine erlaubte Funktion aus.
Ratenbegrenzung oder Kontingent	QuotaExceededError (HTTP 429)	Warten Sie retry_after Sekunden und versuchen Sie es dann mit Backoff erneut.
Anderer HTTP-Fehler	NextPDFAPIError	Prüfen Sie status_code und error_code; protokollieren Sie den Fehler und geben Sie einen definierten Fehler aus.
Jeder SDK-Fehler	NextPDFError	Letzter Auffangfall; lassen Sie ihn niemals als unbehandelte Exception entweichen.

Der Endpunkt meldet Fehler mit HTTP-Status-Semantik gemäß RFC 9110 und maschinenlesbaren Fehlerkörpern gemäß RFC 9457. Jede Exception bewahrt den ursprünglichen status_code. Bilden Sie diese auf Ihre eigenen Fehlerantworten ab, statt Transportdetails an Aufrufer durchsickern zu lassen.

Sichere Standardwerte

Anliegen	Standard	Wann überschreiben
API-Version	v1.	Ändern Sie das nur, wenn der Endpunkt eine neuere Version unterstützt.
TLS-Verifizierung	Aktiviert; kein unsicherer Schalter ist verfügbar.	Deaktivieren Sie sie niemals für Produktionsverkehr.
Anmeldedaten	Aus der Umgebung gelesen; niemals hartcodiert.	Verwenden Sie in der Produktion einen Secret-Manager.
In-Memory-Größenlimit	PDFs über 100 MiB werden auf dem Client-Pfad abgelehnt.	Setzen Sie es für mandantenfähige Dienste niedriger; verwenden Sie für größere Dateien das CLI.
Nebenläufigkeit	In asynchronen Batches durch eine Semaphore begrenzt.	Stimmen Sie sie auf das Kontingent des Endpunkts ab, nicht auf die Anzahl der Kerne des Hosts.
Logging	Protokollieren Sie Dateiname, Größe, Status und Dauer.	Protokollieren Sie niemals PDF-Bytes oder den API-Schlüssel.

Test-Checkliste

• Tests zur Erstellung stellen sicher, dass ein leeres base_url oder api_key ein ValueError auslöst.
• Validierungstests decken fehlende, leere, übergroße und nicht als PDF erkennbare Eingaben ab.
• Extraktionstests prüfen die zurückgegebenen Modelltypen und stellen sicher, dass auf jedem Block ein CitationAnchor vorhanden ist.
• Fehlermodus-Tests decken AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError und NextPDFAPIError ab.
• Async-Tests stellen sicher, dass der Client als async with-Context-Manager verwendet wird und dass die Nebenläufigkeit innerhalb der Semaphore-Grenze bleibt.
• Lebenszyklus-Tests stellen sicher, dass close() den Transport freigibt und idempotent ist.
• Injizieren Sie mit AsyncNextPDF(backend=...) ein gefälschtes Backend, damit Tests ohne aktiven Endpunkt laufen.

Siehe auch

• Python-API-Referenz — jede Client-Methode, jedes Modell und jede Exception.
• Python-CLI — Streaming-Extraktion für große Dokumente.
• Python-MCP-Server — Extraktionswerkzeuge für KI-Agenten bereitstellen.
• Überblick über das Python-SDK — Backend-Optionen und Einschränkungen.