Ontwikkelaarsgids voor de Python-SDK

In het kort

De NextPDF Python Software Development Kit (SDK) is een lichte, getypeerde client voor een NextPDF Connect-endpoint. Je toepassing is verantwoordelijk voor het valideren van Portable Document Format (PDF)-invoer, het beheren van inloggegevens en het concurrencybeleid. De SDK bouwt verzoeken op, verzorgt het transport en typeert antwoorden. Houd die grens duidelijk: lees de PDF veilig in, kies een client, roep de ast-methode aan die je nodig hebt en handel de specifieke fout af.

Gebruik deze gids wanneer je extractiediensten, asyncio-batchtaken, hulpmiddelen voor AI-agents of opdrachtregelworkflows rond de SDK bouwt. De gids gaat ervan uit dat je het overzicht en de snelstart hebt gelezen en dat je beschikt over Python 3.10 of nieuwer en een NextPDF Connect-endpoint.

Architectuurgrens

Laag	Eigenaar	Verantwoordelijkheid	Hier niet plaatsen
Invoerbron	Toepassing	Autoriseer de aanroeper, valideer de PDF-bron en kies het extractiebeleid.	Letterlijke endpoint-URL (Uniform Resource Locator) of inloggegevens.
Clientconstructie	Toepassing	Lees base_url en api_key uit de omgeving of een secret manager.	Hardgecodeerde secrets.
NextPDF / AsyncNextPDF	SDK	Bouw het verzoek op, roep Connect aan en geef getypeerde Pydantic-modellen terug.	Domeinlogica of opslagbeleid.
Naamruimte van de ast-methode	SDK	Wijs een methodeaanroep toe aan een Connect-endpoint en verwerk het antwoord.	Retry- of backoffbeleid buiten wat je zelf configureert.
NextPDF Connect-endpoint	Deployment	Voer extractie uit en handhaaf authenticatie, quota en licenties.	Toepassingsautorisatie.

De SDK voert nooit optische tekenherkenning (OCR) uit. Als een PDF gescand is of alleen uit afbeeldingen bestaat, voer dan OCR uit voor de extractie. Beschouw die stap als toepassingslogica buiten deze grens.

Levenscyclus tijdens uitvoering

Fase	Gedrag	Actie voor de ontwikkelaar
Clientconstructie	base_url en api_key worden gevalideerd; een lege waarde voor een van beide veroorzaakt een ValueError.	Lees beide uit de omgeving; neem ze nooit inline op.
Backend aanmaken	Een externe backend opent een gepoolde verbinding met Connect.	Hergebruik één client voor alle aanroepen in plaats van er per verzoek een aan te maken.
Methodeaanroep	De ast-methode serialiseert het verzoek, verstuurt PDF-bytes en verwerkt het antwoord tot een Pydantic-model.	Geef reeds gevalideerde bytes door.
Fouttoewijzing	De SDK wijst een niet-geslaagde Hypertext Transfer Protocol (HTTP)-status toe aan een specifieke exception-subklasse.	Vang eerst de meest specifieke klasse af.
Afsluiten	AsyncNextPDF.close() geeft de verbindingspool vrij; de asynchrone context manager roept de methode voor je aan.	Gebruik async with of roep close() aan in een finally-blok.

Aanbevolen toepassingsstructuur

Pad	Doel
app/pdf/clients.py	Bouw en cache een geconfigureerde NextPDF of AsyncNextPDF.
app/pdf/extraction.py	Toepassingswrapper rond de aanroepen van de ast-methode.
app/pdf/validation.py	Validatie van de PDF-bron, groottelimieten en inhoudscontroles.
tests/pdf/	Tests voor extractie, faalmodi en asynchrone batchverwerking.

Houd PDF-validatie gescheiden van extractie. Geef alleen geautoriseerde, op grootte gecontroleerde bytes door aan de extractielaag en blijf daarnaast op het endpoint vertrouwen voor verdediging in de diepte.

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)

Patroon voor de synchrone client

Gebruik de synchrone NextPDF-client voor scripts, batchtaken en notebooks. Valideer de invoer voordat je de SDK aanroept en handel de specifieke fouten af die de aanroep kan veroorzaken.

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

Eén item in het resultaat heeft deze vorm:

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

Patroon voor asynchrone verwerking en batchverwerking

Gebruik de asynchrone AsyncNextPDF-client binnen asyncio-runtimes zoals FastAPI. Maak één client aan als asynchrone context manager en deel deze tussen gelijktijdige aanroepen; open geen client per document. Beperk de concurrency met een semafoor zodat je het quotum van het endpoint respecteert.

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

Schrijf nooit een lege except. Reageer op de fout, zet deze om in een gedefinieerd resultaat of gooi deze opnieuw op.

Uitbreidingspunten

Uitbreidingspunt	Gebruik het voor	Beperking
AsyncNextPDF(backend=...)	Injecteer een aangepaste of lokale backend in tests.	De backend moet voldoen aan het PdfBackend-protocol.
api_version-argument	Pin een versie van de Connect application programming interface (API).	Standaard v1; wijzig dit alleen als het endpoint de doelversie ondersteunt.
Omgevingsconfiguratie	Geef NEXTPDF_BASE_URL en NEXTPDF_API_KEY door aan de opdrachtregelinterface (CLI) en de Model Context Protocol (MCP)-server.	Behandel de sleutel als een secret met een bereik dat beperkt is tot de workload.
MCP-server (python -m nextpdf.mcp)	Stel extractiehulpmiddelen beschikbaar aan MCP-compatibele agents.	Vereist de extra nextpdf[mcp] en een gecontroleerd endpoint.

Ontwikkelworkflow

1. Installeer de SDK met pip install nextpdf, of gebruik pip install nextpdf[mcp] voor de agentserver.
2. Lees NEXTPDF_BASE_URL en NEXTPDF_API_KEY uit de omgeving zodat er geen secret in versiebeheer terechtkomt.
3. Valideer elke PDF-bron op bestaan, grootte en de %PDF--magic bytes voordat je de SDK aanroept.
4. Bouw één client per proces en hergebruik deze; houd deze voor asyncio open met async with.
5. Roep voor de taak de meest specifieke ast-methode aan: extract_cited_text() voor proza, extract_cited_tables() voor tabellen, en get_document_ast() alleen wanneer je de volledige boom nodig hebt.
6. Vang de meest specifieke exception af waarop je kunt reageren, en val daarna terug op NextPDFError.
7. Gebruik voor documenten boven 100 MiB het CLI-streamingpad in plaats van elk blok in het geheugen te materialiseren.
8. Voer mypy uit in de strikte modus en voeg een faalmodus-test toe voor elke exception die u afhandelt.

Foutafhandeling

Fout	Exception	Aanbevolen reactie
Niet-getagde PDF, heuristiek uit	AstNoStructTreeError (HTTP 422)	Schakel de heuristische modus in op het endpoint of lever een getagde PDF aan.
Time-out bij het bouwen aan de serverzijde	AstBuildTimeoutError (HTTP 504)	Verklein het paginabereik en probeer het opnieuw.
Vereist licentieniveau	NextPDFLicenseError (HTTP 402)	Upgrade de serverlicentie of val terug op een toegestane functie.
Snelheidslimiet of quotum	QuotaExceededError (HTTP 429)	Wacht retry_after seconden en probeer het daarna opnieuw met backoff.
Andere HTTP-fout	NextPDFAPIError	Inspecteer status_code en error_code; log en presenteer een gedefinieerde fout.
Elke SDK-fout	NextPDFError	Laatste vangnet; laat deze nooit als een onafgehandelde exception ontsnappen.

Het endpoint rapporteert fouten met HTTP-statussemantiek conform Request for Comments (RFC) 9110 en machineleesbare foutlichamen conform RFC 9457. Elke exception behoudt de oorspronkelijke status_code. Wijs die fouten toe aan je eigen foutreacties in plaats van transportdetails naar aanroepers te laten lekken.

Veilige standaardwaarden

Aandachtspunt	Standaard	Wanneer overschrijven
API-versie	v1.	Wijzig dit alleen wanneer het endpoint een nieuwere versie ondersteunt.
Verificatie via Transport Layer Security (TLS)	Ingeschakeld; er is geen onveilige schakelaar beschikbaar.	Schakel dit nooit uit voor productieverkeer.
Inloggegevens	Uit de omgeving gelezen; nooit inline opgenomen.	Gebruik een secret manager in productie.
Groottelimiet in het geheugen	Wijs PDF-bestanden boven 100 MiB af op het clientpad.	Verlaag dit voor multitenant-diensten; gebruik de CLI voor grotere bestanden.
Concurrency	Begrensd door een semafoor in asynchrone batches.	Stem af op het quotum van het endpoint, niet op het aantal cores van de host.
Logging	Log de bestandsnaam, grootte, status en duur.	Log nooit PDF-bytes of de API-sleutel.

Testchecklist

• Constructietests verifiëren dat een lege base_url of api_key een ValueError veroorzaakt.
• Validatietests dekken ontbrekende, lege, te grote en niet-PDF-invoer.
• Extractietests verifiëren de teruggegeven modeltypen en een CitationAnchor voor elk blok.
• Faalmodus-tests dekken AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError en NextPDFAPIError.
• Asynchrone tests verifiëren dat de client als async with-context manager draait en dat de concurrency binnen de semafoorgrens blijft.
• Levenscyclustests verifiëren dat close() het transport vrijgeeft en idempotent is.
• Injecteer een nep-backend met AsyncNextPDF(backend=...) zodat tests draaien zonder live endpoint.

Zie ook

• Python API-referentie — elke clientmethode, elk model en elke exception.
• Python CLI — streaming-extractie voor grote documenten.
• Python MCP-server — extractiehulpmiddelen voor AI-agents.
• Overzicht van de Python-SDK — backendkeuzes en beperkingen.