Referensi API Python

Sekilas

NextPDF Python Software Development Kit (SDK) menyediakan dua klien, namespace metode Abstract Syntax Tree (AST) bersama bernama ast, model Pydantic untuk setiap respons, command-line interface (CLI) nextpdf, dan hierarki exception yang berisi enam kelas. Gunakan halaman ini sebagai referensi untuk simbol publik dalam application programming interface (API) yang bekerja dengan dokumen Portable Document Format (PDF).

Impor simbol publik dari paket tingkat atas:

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

Setiap metode ekstraksi menerima byte PDF mentah (bytes) sebagai argumen posisional pertama dan mengembalikan model Pydantic bertipe. Berikan opsi sebagai argumen keyword-only. Metode NextPDF.ast.* sinkron dan metode AsyncNextPDF.ast.* asinkron memiliki tanda tangan yang identik. Metode asinkron merupakan coroutine; panggil dengan await.

Klien

Klien NextPDF yang sinkron membungkus klien asinkron dan menjalankan setiap coroutine hingga selesai. AsyncNextPDF berfungsi sebagai klien asinkron sekaligus context manager async. Utamakan bentuk context manager agar transport di bawahnya ditutup secara deterministik.

Konstruktor

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
NextPDF(*, base_url, api_key, api_version='v1')	base URL keyword-only, API key, dan versi API opsional.	Membuat klien sinkron berbasis remote.	NextPDF	ValueError ketika base_url atau api_key kosong.	Menjalankan pekerjaan async secara sinkron; aman di dalam notebook dan event loop yang sedang berjalan.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	base URL keyword-only, API key, versi API opsional, dan backend opsional yang disuntikkan.	Membuat klien asinkron berbasis remote ketika tidak ada backend yang disuntikkan.	AsyncNextPDF	ValueError ketika base_url atau api_key kosong dan tidak ada backend yang diberikan.	Berikan backend= untuk menyuntikkan backend kustom atau lokal dalam pengujian.
AsyncNextPDF.__aenter__()	Tidak ada.	Memasuki konteks async dan mengembalikan klien.	AsyncNextPDF	Tidak diharapkan ada.	Gunakan async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Argumen exception yang ditekan.	Memanggil close() saat keluar dari konteks.	None	Tidak diharapkan ada.	Melepaskan transport bahkan ketika body melempar exception.
AsyncNextPDF.close()	Tidak ada.	Menutup backend remote yang dimiliki dan melepaskan connection pool.	None	Tidak diharapkan ada.	Idempoten; backend yang disuntikkan tidak ditutup.

Jangan simpan API key di dalam kode sumber. Baca base_url dan api_key dari environment (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) atau 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

Metode AST sinkron — NextPDF.ast.*

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
NextPDF.ast.get_document_ast()	pdf_data: bytes; keyword page_range_start, page_range_end, token_budget.	Membangun Semantic AST lengkap untuk setiap halaman.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Kurangi rentang halaman jika build melewati batas waktu.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; keyword page_index, headings_only.	Mengekstrak semua blok teks beserta jangkar kutipan.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Atur headings_only=True untuk hanya mengambil node heading.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; keyword page_range (dict dengan start dan end).	Mengekstrak semua tabel beserta jangkar kutipan tingkat sel.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Hilangkan page_range untuk memindai seluruh dokumen.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Mengambil satu node berdasarkan pengenalnya.	GetAstNodeResponse	NextPDFError ketika node tidak ditemukan.	Format node_id adalah ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; keyword node_type, page_index, text_query, max_results=100.	Mengembalikan node dangkal yang cocok dengan filter.	SearchAstNodesResponse	NextPDFAPIError.	text_query menggunakan pencocokan substring yang tidak peka huruf besar-kecil.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Membandingkan dua dokumen berdasarkan struktur.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Melaporkan node yang ditambahkan, dihapus, dan diubah.

Metode AST asinkron — AsyncNextPDF.ast.*

Setiap metode asinkron merupakan coroutine dengan parameter, nilai baku, tipe kembalian, dan mode kegagalan yang sama seperti padanan sinkronnya. Panggil dengan await di dalam runtime asyncio.

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; keyword page_range_start, page_range_end, token_budget.	Membangun Semantic AST lengkap untuk setiap halaman.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	await hasilnya.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; keyword page_index, headings_only.	Mengekstrak semua blok teks beserta jangkar kutipan.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	await hasilnya.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; keyword page_range.	Mengekstrak semua tabel beserta jangkar kutipan tingkat sel.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	await hasilnya.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Mengambil satu node berdasarkan pengenalnya.	GetAstNodeResponse	NextPDFError ketika node tidak ditemukan.	await hasilnya.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; keyword node_type, page_index, text_query, max_results=100.	Mengembalikan node dangkal yang cocok dengan filter.	SearchAstNodesResponse	NextPDFAPIError.	await hasilnya.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	Membandingkan dua dokumen berdasarkan struktur.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	await hasilnya.

Gunakan klien async sebagai context manager untuk menjalankan dua ekstraksi secara bersamaan:

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

Model

Setiap respons berupa model Pydantic. Impor kelas model dari nextpdf atau nextpdf.models.ast.

Simbol	Jenis	Bidang utama	Catatan
AstDocument	Akar dokumen	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (property).	Dikembalikan oleh get_document_ast(). Menerima alias schemaVersion, sourceHash, dan pageCount.
AstNode	Node pohon	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Node rekursif yang merepresentasikan pohon dokumen.
AstNodeMeta	Metadata respons	etag, pages_processed.	Frozen; dilampirkan pada respons node dan pencarian.
AstNodeShallow	Hasil pencarian	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Frozen; tanpa turunan yang dalam.
BoundingBox	Objek nilai	x, y, width, height (masing-masing 0.0–1.0).	Koordinat ternormalisasi di dalam satu halaman.
CitationAnchor	Objek nilai	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Catatan provenance untuk setiap blok.
CitedTextBlock	Blok teks	text, citation: CitationAnchor, node_type, chunk_index, depth.	Setiap item dalam daftar extract_cited_text().
CitedTableBlock	Blok tabel	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Frozen; satu tabel.
CitedTableCell	Sel tabel	row, col, row_span, col_span, text, bbox, confidence.	Frozen; satu sel.
NodeType	Enum	document, section, heading, paragraph, list, table, figure, dan lainnya.	Enum string untuk nilai node-type.
GetAstNodeResponse	Respons	node: AstNode, meta: AstNodeMeta.	Dikembalikan oleh get_ast_node().
SearchAstNodesResponse	Respons	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Dikembalikan oleh search_ast_nodes().
ExtractCitedTablesResponse	Respons	tables: list[CitedTableBlock], table_count, pages_processed.	Dikembalikan oleh extract_cited_tables().
AstDiffEntry	Item diff	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Satu perubahan dalam diff.
AstDiffSummary	Total diff	added_node_count, removed_node_count, changed_node_count.	Jumlah agregat.
GetAstDiffResponse	Respons	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Dikembalikan oleh get_ast_diff().

Baca jangkar kutipan dari blok teks yang diekstrak:

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

Perintah CLI

Perintah nextpdf menjalankan ekstraksi dari terminal. Berikan --base-url dan --api-key, atau atur NEXTPDF_BASE_URL dan NEXTPDF_API_KEY di environment. Setiap perintah kecuali version memerlukan pengaturan koneksi. Jika nilai PDF_PATH adalah -, byte PDF dibaca dari standard input.

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Menghasilkan blok teks terkutip sebagai JavaScript Object Notation (JSON).	Menulis ke standard output atau berkas --output.	Kode keluar 1 untuk NextPDFError apa pun.	--page memilih satu indeks halaman berbasis-0.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Menghasilkan tabel sebagai JSON.	Menulis ke standard output atau berkas --output.	Kode keluar 1 untuk NextPDFError apa pun.	--format csv menulis satu blok comma-separated values (CSV) per tabel.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Menghasilkan Semantic AST lengkap sebagai JSON.	Menulis ke standard output atau berkas --output.	Kode keluar 1 untuk NextPDFError apa pun.	Gunakan --token-budget untuk membatasi ukuran respons.
nextpdf info	PDF_PATH.	Menghasilkan metadata dokumen: jumlah halaman, versi skema, hash sumber, perkiraan token, dan ringkasan akar.	Menulis JSON ke standard output atau berkas --output.	Kode keluar 1 untuk NextPDFError apa pun.	Perintah inspeksi ringan.
nextpdf version	Tidak ada.	Mencetak versi SDK yang terpasang.	Menulis ke standard output.	Tidak diharapkan ada.	Tidak menghubungi server; tidak memerlukan kredensial.
python -m nextpdf.mcp	tidak ada (membaca NEXTPDF_BASE_URL, NEXTPDF_API_KEY).	Menjalankan server Model Context Protocol melalui standard input/output.	Proses server yang berjalan lama.	RuntimeError ketika variabel environment tidak diatur.	Memerlukan extra nextpdf[mcp].

Ekstrak tabel sebagai comma-separated values (CSV) dari sebuah rentang halaman:

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

Exception

Hierarki exception berada di nextpdf.models.errors dan diekspor ulang dari nextpdf. Tangkap kelas paling spesifik yang dapat ditangani kode Anda, lalu fallback ke kelas dasar. Server melaporkan kegagalan dengan semantik status Hypertext Transfer Protocol (HTTP) yang selaras dengan Request for Comments (RFC) 9110. Setiap exception membawa status_code asal dan, jika tersedia, sebuah error_code.

Simbol	Kelas dasar	status_code	Kapan dilempar	Catatan
NextPDFError	Exception	opsional	Kelas dasar untuk setiap error SDK.	Membawa status_code opsional. Tangkap paling akhir sebagai fallback.
NextPDFAPIError	NextPDFError	wajib	Endpoint Connect mengembalikan error HTTP.	Menambahkan error_code.
NextPDFLicenseError	NextPDFAPIError	402	Server memerlukan lisensi tingkat lebih tinggi untuk fitur tersebut.	error_code adalah license/tier-required.
QuotaExceededError	NextPDFAPIError	429	Batas laju atau kuota terlampaui.	Membawa retry_after; patuhi sebelum mencoba ulang.
AstNoStructTreeError	NextPDFAPIError	422	PDF tidak diberi tag, dan fallback heuristik tidak diaktifkan.	Aktifkan mode heuristik atau berikan PDF bertag.
AstBuildTimeoutError	NextPDFAPIError	504	Build AST melebihi batas waktu di server.	Kurangi rentang halaman dan coba ulang.

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)

Catatan pengembangan

• Klien NextPDF sinkron mendelegasikan setiap panggilan ke AsyncNextPDF. Anda dapat memanggilnya dari notebook atau thread yang sudah menjalankan event loop, karena klien ini mengirim coroutine ke worker thread saat mendeteksi loop yang berjalan.
• Utamakan bentuk context manager async async with AsyncNextPDF(...) as client: agar connection pool ditutup secara deterministik. Jika Anda membuat AsyncNextPDF secara langsung, panggil close() sendiri.
• Bearer token tidak pernah dicatat di log atau disertakan dalam pesan error, dan verifikasi Transport Layer Security (TLS) diaktifkan secara baku. Jangan menyematkan kredensial di kode sumber; baca dari environment atau secret manager.
• Semua model adalah kelas Pydantic v2; beberapa model respons bersifat frozen (tidak dapat diubah). Perlakukan blok yang diekstrak sebagai nilai read-only.
• CLI keluar dengan kode status 1 untuk NextPDFError apa pun dan mencetak pesannya ke standard error. Gunakan kode keluar tersebut dalam pipeline.

Lihat juga

• Panduan pengembang Python SDK — arsitektur, batching async, dan penanganan kegagalan.
• Python CLI — ekstraksi terminal dan streaming untuk berkas besar.
• Server Python MCP — mengekspos alat ekstraksi untuk agen artificial intelligence (AI).
• RFC 9110 (HTTP Semantics) dan RFC 9457 (Problem Details for HTTP APIs) menjelaskan semantik status dan body error yang dapat dibaca mesin yang dikembalikan endpoint Connect. Lihat indeks RFC IETF untuk teks yang otoritatif.