Panduan pengembang Python SDK

Sekilas pandang

Python Software Development Kit (SDK) NextPDF adalah klien ringan bertipe untuk endpoint NextPDF Connect. Aplikasi Anda bertanggung jawab atas validasi masukan Portable Document Format (PDF), penanganan kredensial, dan kebijakan konkurensi. SDK menangani penyusunan permintaan, transport, dan respons bertipe. Pertahankan batas tanggung jawab itu dengan jelas: baca PDF dengan aman, pilih klien, panggil metode ast yang Anda perlukan, dan tangani kegagalan spesifiknya.

Gunakan panduan ini saat membangun layanan ekstraksi, pekerjaan batch asyncio, alat bantu agen kecerdasan buatan (AI), atau alur kerja baris perintah berbasis SDK. Panduan ini mengasumsikan Anda sudah membaca ikhtisar dan mulai cepat, serta memiliki Python 3.10 atau yang lebih baru dan endpoint NextPDF Connect.

Batas arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan letakkan di sini
Sumber masukan	Aplikasi	Mengotorisasi pemanggil, memvalidasi sumber PDF, dan memilih kebijakan ekstraksi.	URL endpoint atau kredensial literal.
Pembuatan klien	Aplikasi	Membaca base_url dan api_key dari lingkungan atau pengelola rahasia.	Rahasia yang ditulis langsung di kode.
NextPDF / AsyncNextPDF	SDK	Membangun permintaan, memanggil Connect, dan mengembalikan model Pydantic bertipe.	Logika domain atau kebijakan penyimpanan.
Namespace metode ast	SDK	Memetakan panggilan metode ke endpoint Connect dan mengurai respons.	Kebijakan retry atau backoff di luar konfigurasi Anda.
Endpoint NextPDF Connect	deployment	Menjalankan ekstraksi serta menegakkan autentikasi, kuota, dan lisensi.	Otorisasi aplikasi.

SDK tidak pernah melakukan optical character recognition (OCR). Jika PDF merupakan hasil pemindaian atau hanya berisi gambar, jalankan OCR sebelum ekstraksi. Perlakukan langkah tersebut sebagai tanggung jawab aplikasi di luar batas ini.

Siklus hidup runtime

Tahap	Perilaku	Tindakan pengembang
Pembuatan klien	base_url dan api_key divalidasi; nilai kosong pada salah satunya akan memunculkan ValueError.	Baca keduanya dari lingkungan; jangan pernah menuliskannya langsung di kode.
Pembuatan backend	Backend jarak jauh membuka pool koneksi ke Connect.	Gunakan kembali satu klien untuk semua panggilan, bukan membuatnya per permintaan.
Panggilan metode	Metode ast menserialisasi permintaan, mengirim bita PDF, dan mengurai respons menjadi model Pydantic.	Berikan bytes yang sudah divalidasi.
Pemetaan kesalahan	SDK memetakan status Hypertext Transfer Protocol (HTTP) yang gagal ke subkelas eksepsi tertentu.	Tangkap kelas yang paling spesifik terlebih dahulu.
Penutupan	AsyncNextPDF.close() melepaskan pool koneksi; context manager asinkron memanggilnya untuk Anda.	Gunakan async with atau panggil close() dalam blok finally.

Struktur aplikasi yang direkomendasikan

Path	Tujuan
app/pdf/clients.py	Membangun dan menyimpan NextPDF atau AsyncNextPDF yang sudah dikonfigurasi dalam cache.
app/pdf/extraction.py	Wrapper aplikasi untuk panggilan metode ast.
app/pdf/validation.py	Validasi sumber PDF, batas ukuran, dan pemeriksaan konten.
tests/pdf/	Tes ekstraksi, mode kegagalan, dan batch asinkron.

Pisahkan validasi PDF dari ekstraksi. Berikan hanya bita yang sudah diotorisasi dan diperiksa ukurannya ke lapisan ekstraksi, dan tetap andalkan endpoint untuk pertahanan berlapis.

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)

Pola klien sinkron

Gunakan klien NextPDF sinkron untuk skrip, pekerjaan batch, dan notebook. Validasi masukan sebelum memanggil SDK, lalu tangani kegagalan spesifik yang dapat muncul dari panggilan tersebut.

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

Satu item hasil terlihat seperti ini:

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

Pola asinkron dan batch

Gunakan klien AsyncNextPDF asinkron di dalam runtime asyncio seperti FastAPI. Buat satu klien sebagai context manager asinkron dan bagikan ke semua panggilan bersamaan; jangan membuka satu klien per dokumen. Batasi konkurensi dengan semafor agar tetap mematuhi kuota endpoint.

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

Jangan pernah menulis blok except kosong. Tindak lanjuti kegagalan tersebut, ubah menjadi hasil yang terdefinisi, atau munculkan kembali.

Titik ekstensi

Titik ekstensi	Gunakan untuk	Batasan
AsyncNextPDF(backend=...)	Menyuntikkan backend khusus atau lokal dalam pengujian.	Backend harus memenuhi protokol PdfBackend.
Argumen api_version	Mengunci versi application programming interface (API) Connect.	Standarnya v1; ubah hanya ketika endpoint mendukung versi target.
Konfigurasi lingkungan	Menyediakan NEXTPDF_BASE_URL dan NEXTPDF_API_KEY untuk command-line interface (CLI) dan server Model Context Protocol (MCP).	Perlakukan kunci sebagai rahasia yang dibatasi pada beban kerja tertentu.
Server MCP (python -m nextpdf.mcp)	Mengekspos alat ekstraksi ke agen yang mendukung MCP.	Membutuhkan extra nextpdf[mcp] dan endpoint yang terkontrol.

Alur kerja pengembangan

1. Pasang SDK dengan pip install nextpdf, atau gunakan pip install nextpdf[mcp] untuk server agen.
2. Baca NEXTPDF_BASE_URL dan NEXTPDF_API_KEY dari lingkungan agar tidak ada rahasia yang masuk ke kendali sumber.
3. Validasi setiap sumber PDF untuk keberadaan, ukuran, dan bita ajaib %PDF- sebelum memanggil SDK.
4. Buat satu klien per proses dan gunakan kembali; untuk asyncio, pertahankan klien tetap terbuka dengan async with.
5. Panggil metode ast yang paling spesifik untuk tugas tersebut: extract_cited_text() untuk prosa, extract_cited_tables() untuk tabel, get_document_ast() hanya ketika Anda membutuhkan seluruh pohon.
6. Tangkap eksepsi paling spesifik yang dapat Anda tangani, lalu gunakan NextPDFError sebagai fallback.
7. Untuk dokumen di atas 100 MiB, gunakan jalur streaming CLI alih-alih memuat setiap blok ke memori.
8. Jalankan mypy dalam mode strict dan tambahkan tes mode kegagalan untuk setiap eksepsi yang Anda tangani.

Penanganan kegagalan

Kegagalan	Eksepsi	Respons yang direkomendasikan
PDF tanpa tag, heuristik nonaktif	AstNoStructTreeError (HTTP 422)	Aktifkan mode heuristik pada endpoint atau sediakan PDF bertag.
Timeout build sisi server	AstBuildTimeoutError (HTTP 504)	Persempit rentang halaman, lalu coba lagi.
Tingkat lisensi diperlukan	NextPDFLicenseError (HTTP 402)	Tingkatkan lisensi server atau gunakan fitur yang diizinkan sebagai fallback.
Batas laju atau kuota	QuotaExceededError (HTTP 429)	Tunggu selama retry_after detik, lalu coba lagi dengan backoff.
Kesalahan HTTP lainnya	NextPDFAPIError	Periksa status_code dan error_code; catat log dan munculkan kesalahan yang terdefinisi.
Kesalahan SDK apa pun	NextPDFError	Pengaman terakhir; jangan pernah membiarkannya lolos sebagai eksepsi yang tidak tertangani.

Endpoint melaporkan kegagalan dengan semantik status HTTP yang selaras dengan Request for Comments (RFC) 9110 dan badan kesalahan yang dapat dibaca mesin yang selaras dengan RFC 9457. Setiap eksepsi mempertahankan status_code asalnya. Petakan kegagalan tersebut ke respons kesalahan Anda sendiri, alih-alih membocorkan detail transport kepada pemanggil.

Default yang aman

Aspek	Default	Kapan menggantinya
Versi API	v1.	Ubah hanya ketika endpoint mendukung versi yang lebih baru.
Verifikasi Transport Layer Security (TLS)	Aktif; tidak ada sakelar tidak aman yang diekspos.	Jangan pernah menonaktifkannya untuk lalu lintas produksi.
Kredensial	Dibaca dari lingkungan; tidak pernah ditulis langsung di kode.	Gunakan pengelola rahasia di produksi.
Batas ukuran in-memory	Tolak PDF di atas 100 MiB pada jalur klien.	Turunkan untuk layanan multi-tenant; gunakan CLI untuk berkas yang lebih besar.
Konkurensi	Dibatasi oleh semafor dalam batch asinkron.	Sesuaikan dengan kuota endpoint, bukan dengan jumlah inti host.
Pencatatan log	Catat nama berkas, ukuran, status, dan durasi.	Jangan pernah mencatat bita PDF atau kunci API.

Daftar periksa pengujian

• Tes pembuatan memastikan bahwa base_url atau api_key yang kosong memunculkan ValueError.
• Tes validasi mencakup masukan yang hilang, kosong, melebihi ukuran, dan bukan PDF.
• Tes ekstraksi memastikan tipe model yang dikembalikan dan keberadaan CitationAnchor pada setiap blok.
• Tes mode kegagalan mencakup AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError, dan NextPDFAPIError.
• Tes asinkron memastikan klien berjalan sebagai context manager async with dan bahwa konkurensi tetap berada dalam batas semafor.
• Tes siklus hidup memastikan bahwa close() melepaskan transport dan bersifat idempoten.
• Suntikkan backend palsu dengan AsyncNextPDF(backend=...) agar tes dapat berjalan tanpa endpoint aktif.

Lihat juga

• Referensi API Python — setiap metode klien, model, dan eksepsi.
• CLI Python — ekstraksi streaming untuk dokumen besar.
• Server MCP Python — perkakas ekstraksi untuk agen AI.
• Ikhtisar Python SDK — pilihan backend dan keterbatasan.