Python API başvurusu

Bir bakışta

NextPDF Python Software Development Kit (SDK), iki istemci, ast adlı paylaşılan bir Abstract Syntax Tree (AST) yöntem ad alanı, her yanıt için Pydantic modelleri, bir nextpdf command-line interface (CLI)‘si ve altı sınıftan oluşan bir istisna hiyerarşisi sunar. Portable Document Format (PDF) belgeleriyle çalışan herkese açık application programming interface (API) sembolleri için bu sayfayı başvuru kaynağı olarak kullanın.

Herkese açık sembolleri üst düzey paketten içe aktarın:

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

Her ayıklama yöntemi, ilk konumsal bağımsız değişken olarak ham PDF baytlarını (bytes) alır ve türlendirilmiş bir Pydantic modeli döndürür. Seçenekleri yalnızca anahtar sözcük bağımsız değişkenleri olarak verin. Eşzamanlı NextPDF.ast.* yöntemleri ile eşzamansız AsyncNextPDF.ast.* yöntemlerinin imzaları aynıdır. Eşzamansız yöntemler eşgüdüm (coroutine) olarak çalışır; bunları await ile çağırın.

İstemci

Eşzamanlı NextPDF istemcisi, eşzamansız istemciyi sarmalar ve her eşgüdümü tamamlanana kadar çalıştırır. AsyncNextPDF, hem eşzamansız bir istemci hem de eşzamansız bir bağlam yöneticisidir. Alttaki taşımanın belirlenimci biçimde kapanması için bağlam yöneticisi kullanımını tercih edin.

Yapıcılar

Sembol	Parametreler	Varsayılan davranış	Döndürür	Hata veya başarısızlık	Notlar
NextPDF(*, base_url, api_key, api_version='v1')	Yalnızca anahtar sözcükle verilen temel URL, API anahtarı ve isteğe bağlı API sürümü.	Uzak arka uç destekli eşzamanlı bir istemci oluşturur.	NextPDF	ValueError; base_url veya api_key boş olduğunda oluşur.	Eşzamansız işi eşzamanlı olarak çalıştırır; not defterlerinde ve çalışan bir olay döngüsü içinde güvenlidir.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	Yalnızca anahtar sözcükle verilen temel URL, API anahtarı, isteğe bağlı API sürümü ve isteğe bağlı enjekte edilmiş arka uç.	Hiçbir arka uç enjekte edilmediğinde uzak arka uç destekli eşzamansız bir istemci oluşturur.	AsyncNextPDF	ValueError; base_url veya api_key boş olduğunda ve hiçbir backend sağlanmadığında oluşur.	Testlerde özel veya yerel bir arka uç enjekte etmek için backend= verin.
AsyncNextPDF.__aenter__()	Yok.	Eşzamansız bağlamı açar ve istemciyi döndürür.	AsyncNextPDF	Beklenen yok.	Şu biçimi kullanın: async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	Bastırılacak istisna bağımsız değişkenleri.	Bağlamdan çıkarken close() çağırır.	None	Beklenen yok.	Gövde bir istisna tetiklediğinde bile taşımanın serbest bırakılmasını sağlar.
AsyncNextPDF.close()	Yok.	Sahip olunan uzak arka ucu kapatır ve bağlantı havuzunu serbest bırakır.	None	Beklenen yok.	Yinelenen çağrılarda güvenlidir (idempotent); enjekte edilmiş arka uçlar kapatılmaz.

API anahtarını kaynak kodunda tutmayın. base_url ve api_key değerlerini ortamdan (NEXTPDF_BASE_URL, NEXTPDF_API_KEY) veya bir gizli dizi yöneticisinden okuyun.

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

Eşzamanlı AST yöntemleri — NextPDF.ast.*

Sembol	Parametreler	Varsayılan davranış	Döndürür	Hata veya başarısızlık	Notlar
NextPDF.ast.get_document_ast()	pdf_data: bytes; anahtar sözcük page_range_start, page_range_end, token_budget.	Her sayfa için tam Semantic AST yapısını oluşturur.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	Derleme zaman aşımına uğrarsa sayfa aralığını daraltın.
NextPDF.ast.extract_cited_text()	pdf_data: bytes; anahtar sözcük page_index, headings_only.	Tüm metin bloklarını alıntı bağlantı noktalarıyla birlikte ayıklar.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	Yalnızca başlık düğümlerini almak için headings_only=True olarak ayarlayın.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes; anahtar sözcük page_range (dict; start ve end içerir).	Tüm tabloları hücre düzeyinde alıntı bağlantı noktalarıyla birlikte ayıklar.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	Belgenin tamamını taramak için page_range değerini atlayın.
NextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Bir düğümü tanımlayıcısına göre alır.	GetAstNodeResponse	NextPDFError; düğüm bulunamadığında oluşur.	node_id biçimi ast:{hash6}:{pageIdx}:{seq} şeklindedir.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes; anahtar sözcük node_type, page_index, text_query, max_results=100.	Filtrelerle eşleşen sığ düğümleri döndürür.	SearchAstNodesResponse	NextPDFAPIError.	text_query büyük/küçük harfe duyarlı olmayan bir alt dize eşleşmesidir.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	İki belgeyi yapıya göre karşılaştırır.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	Eklenen, kaldırılan ve değişen düğümleri bildirir.

Eşzamansız AST yöntemleri — AsyncNextPDF.ast.*

Her eşzamansız yöntem, eşzamanlı karşılığıyla aynı parametrelere, varsayılanlara, dönüş türüne ve hata kiplerine sahip bir eşgüdümdür. Bir asyncio çalışma zamanı içinde await ile çağırın.

Sembol	Parametreler	Varsayılan davranış	Döndürür	Hata veya başarısızlık	Notlar
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes; anahtar sözcük page_range_start, page_range_end, token_budget.	Her sayfa için tam Semantic AST yapısını oluşturur.	AstDocument	AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError.	await ile sonucu bekleyin.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes; anahtar sözcük page_index, headings_only.	Tüm metin bloklarını alıntı bağlantı noktalarıyla birlikte ayıklar.	list[CitedTextBlock]	NextPDFAPIError, QuotaExceededError.	await ile sonucu bekleyin.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes; anahtar sözcük page_range.	Tüm tabloları hücre düzeyinde alıntı bağlantı noktalarıyla birlikte ayıklar.	ExtractCitedTablesResponse	NextPDFAPIError, QuotaExceededError.	await ile sonucu bekleyin.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes, node_id: str.	Bir düğümü tanımlayıcısına göre alır.	GetAstNodeResponse	NextPDFError; düğüm bulunamadığında oluşur.	await ile sonucu bekleyin.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes; anahtar sözcük node_type, page_index, text_query, max_results=100.	Filtrelerle eşleşen sığ düğümleri döndürür.	SearchAstNodesResponse	NextPDFAPIError.	await ile sonucu bekleyin.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes, modified_pdf_data: bytes.	İki belgeyi yapıya göre karşılaştırır.	GetAstDiffResponse	NextPDFAPIError, QuotaExceededError.	await ile sonucu bekleyin.

İki ayıklamayı eşzamanlı çalıştırmak için eşzamansız istemciyi bağlam yöneticisi olarak kullanın:

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

Modeller

Her yanıt bir Pydantic modelidir. Model sınıflarını nextpdf veya nextpdf.models.ast üzerinden içe aktarın.

Sembol	Tür	Anahtar alanlar	Notlar
AstDocument	Belge kökü	schema_version, source_hash, page_count, root: AstNode, estimated_tokens (özellik).	Şunun tarafından döndürülür: get_document_ast(). schemaVersion, sourceHash ve pageCount diğer adlarını kabul eder.
AstNode	Ağaç düğümü	id, type: NodeType, page_index, bbox, text_content, attributes, children: list[AstNode], pdf_object_number, mcid.	Belge ağacını taşıyan özyinelemeli düğüm.
AstNodeMeta	Yanıt meta verileri	etag, pages_processed.	Dondurulmuş; düğüm ve arama yanıtlarına eklenir.
AstNodeShallow	Arama isabeti	id, type: NodeType, page_index, bbox, text_content, attributes, children_count.	Dondurulmuş; derin alt öğe yok.
BoundingBox	Değer nesnesi	x, y, width, height (her biri 0.0–1.0).	Bir sayfa içinde normalleştirilmiş koordinatlar.
CitationAnchor	Değer nesnesi	node_id, page_index, bbox: BoundingBox, confidence, content_hash.	Her blok için köken kaydı.
CitedTextBlock	Metin bloğu	text, citation: CitationAnchor, node_type, chunk_index, depth.	Şunun döndürdüğü listedeki her öğe: extract_cited_text().
CitedTableBlock	Tablo bloğu	table_node_id, page_index, citation_anchor, row_count, col_count, rows.	Dondurulmuş; bir tablo.
CitedTableCell	Tablo hücresi	row, col, row_span, col_span, text, bbox, confidence.	Dondurulmuş; bir hücre.
NodeType	Numaralandırma (enum)	document, section, heading, paragraph, list, table, figure ve diğerleri.	Düğüm türü değerleri için dize numaralandırması.
GetAstNodeResponse	Yanıt	node: AstNode, meta: AstNodeMeta.	Şunun tarafından döndürülür: get_ast_node().
SearchAstNodesResponse	Yanıt	nodes: list[AstNodeShallow], total_matches, truncated, meta.	Şunun tarafından döndürülür: search_ast_nodes().
ExtractCitedTablesResponse	Yanıt	tables: list[CitedTableBlock], table_count, pages_processed.	Şunun tarafından döndürülür: extract_cited_tables().
AstDiffEntry	Fark öğesi	type (added/removed/changed), node_id, node_type, page_index, text_preview.	Bir farktaki tek değişiklik.
AstDiffSummary	Fark toplamları	added_node_count, removed_node_count, changed_node_count.	Toplu sayılar.
GetAstDiffResponse	Yanıt	original_page_count, modified_page_count, summary: AstDiffSummary, diff: list[AstDiffEntry], pages_processed.	Şunun tarafından döndürülür: get_ast_diff().

Ayıklanmış bir metin bloğundan alıntı bağlantı noktasını okuyun:

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 komutları

Bu nextpdf komutu, ayıklamayı uçbirimden çalıştırır. --base-url ve --api-key değerlerini verin veya ortamda NEXTPDF_BASE_URL ve NEXTPDF_API_KEY değerlerini ayarlayın. version dışındaki her komut bağlantı ayarları gerektirir. PDF_PATH değeri - ise, PDF baytlarını standart girişten okur.

Sembol	Parametreler	Varsayılan davranış	Döndürür	Hata veya başarısızlık	Notlar
nextpdf extract text	PDF_PATH; --format {json,markdown,plain}, --page, --headings-only.	Alıntılanan metin bloklarını JavaScript Object Notation (JSON) çıktısı olarak verir.	Standart çıktıya veya bir --output dosyasına yazar.	Herhangi bir NextPDFError durumunda çıkış kodu 1.	--page, 0 tabanlı tek bir sayfa dizinini seçer.
nextpdf extract tables	PDF_PATH; --format {json,csv}, --page-start, --page-end.	Tabloları JSON çıktısı olarak verir.	Standart çıktıya veya bir --output dosyasına yazar.	Herhangi bir NextPDFError durumunda çıkış kodu 1.	--format csv, tablo başına bir comma-separated values (CSV) bloğu yazar.
nextpdf ast	PDF_PATH; --page-start, --page-end, --token-budget.	Tam Semantic AST yapısını JSON çıktısı olarak verir.	Standart çıktıya veya bir --output dosyasına yazar.	Herhangi bir NextPDFError durumunda çıkış kodu 1.	Yanıt boyutunu sınırlamak için --token-budget kullanın.
nextpdf info	PDF_PATH.	Belge meta verilerini çıktı olarak verir: sayfa sayısı, şema sürümü, kaynak karması, tahmini belirteçler ve kök özeti.	JSON’ı standart çıktıya veya bir --output dosyasına yazar.	Herhangi bir NextPDFError durumunda çıkış kodu 1.	Hafif inceleme komutu.
nextpdf version	Yok.	Yüklü SDK sürümünü yazdırır.	Standart çıktıya yazar.	Beklenen yok.	Bir sunucuya bağlanmaz; kimlik bilgisi gerektirmez.
python -m nextpdf.mcp	Yok (NEXTPDF_BASE_URL, NEXTPDF_API_KEY değerlerini okur).	Model Context Protocol sunucusunu standart input/output üzerinden çalıştırır.	Uzun süre çalışan bir sunucu süreci.	RuntimeError; ortam değişkenleri ayarlanmadığında oluşur.	Şu ekstra paketi gerektirir: nextpdf[mcp].

Bir sayfa aralığından tabloları comma-separated values (CSV) olarak ayıklayın:

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

İstisnalar

İstisna hiyerarşisi nextpdf.models.errors içinde bulunur ve nextpdf üzerinden yeniden dışa aktarılır. Kodunuzun işleyebileceği en özgül sınıfı yakalayın, ardından temel sınıfa geri dönün. Sunucu, hatayı Request for Comments (RFC) 9110 ile uyumlu Hypertext Transfer Protocol (HTTP) durum anlamlarıyla bildirir. Her istisna, kaynak status_code değerini ve varsa error_code değerini taşır.

Sembol	Temel sınıf	status_code	Ne zaman tetiklenir	Notlar
NextPDFError	Exception	isteğe bağlı	Her SDK hatası için temel sınıf.	İsteğe bağlı bir status_code taşır. Son çare olarak en sonda yakalayın.
NextPDFAPIError	NextPDFError	zorunlu	Connect uç noktası bir HTTP hatası döndürdüğünde.	Şunu ekler: error_code.
NextPDFLicenseError	NextPDFAPIError	402	Sunucu, özellik için daha üst kademe bir lisans gerektirdiğinde.	error_code değeri license/tier-required şeklindedir.
QuotaExceededError	NextPDFAPIError	429	Bir hız sınırı veya kota aşıldığında.	Şunu taşır: retry_after; yeniden denemeden önce buna uyun.
AstNoStructTreeError	NextPDFAPIError	422	PDF etiketlenmemiş olduğunda ve sezgisel geri dönüş etkinleştirilmediğinde.	Sezgisel kipi etkinleştirin veya etiketlenmiş bir PDF sağlayın.
AstBuildTimeoutError	NextPDFAPIError	504	AST derlemesi sunucuda zaman aşımına uğradığında.	Sayfa aralığını daraltın ve yeniden deneyin.

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)

Geliştirme notları

• Eşzamanlı NextPDF istemcisi, her çağrıyı AsyncNextPDF nesnesine devreder. Bunu bir not defterinden veya halihazırda bir olay döngüsü çalıştıran bir iş parçacığından çağırabilirsiniz; çünkü çalışan bir döngü algıladığında eşgüdümü bir çalışan iş parçacığına gönderir.
• Bağlantı havuzunun belirlenimci biçimde kapanması için eşzamansız bağlam yöneticisi biçimi olan async with AsyncNextPDF(...) as client: kullanımını tercih edin. AsyncNextPDF nesnesini doğrudan oluşturduğunuzda, close() yöntemini kendiniz çağırın.
• Taşıyıcı belirteç hiçbir zaman günlüğe kaydedilmez veya hata mesajlarına dahil edilmez ve Transport Layer Security (TLS) doğrulaması varsayılan olarak etkindir. Kimlik bilgilerini kaynak koda gömmeyin; bunları ortamdan veya bir gizli dizi yöneticisinden okuyun.
• Tüm modeller Pydantic v2 sınıflarıdır; birkaç yanıt modeli donmuştur (değişmez). Ayıklanmış blokları salt okunur değerler olarak ele alın.
• CLI, herhangi bir NextPDFError için çıkış kodu 1 ile sonlanır ve mesajı standart hataya yazdırır. Bu çıkış kodunu işlem hatlarında kullanın.

Ayrıca bakınız

• Python SDK geliştirici kılavuzu — mimari, eşzamansız gruplama ve hata işleme.
• Python CLI — büyük dosyalar için uçbirimden ayıklama ve akış.
• Python MCP sunucusu — ayıklama araçlarını artificial intelligence (AI) aracılarına sunar.
• RFC 9110 (HTTP Semantics) ve RFC 9457 (Problem Details for HTTP APIs), Connect uç noktasının döndürdüğü durum anlamlarını ve makine tarafından okunabilen hata gövdelerini açıklar. Yetkili metin için IETF RFC dizinine bakın.