Python SDK geliştirici kılavuzu

Bir bakışta

NextPDF Python yazılım geliştirme kiti (SDK), bir NextPDF Connect uç noktası için hafif ve tür güvenli bir istemcidir. Taşınabilir Belge Biçimi (PDF) girdisini doğrulamak, kimlik bilgilerini yönetmek ve eşzamanlılık ilkesini uygulamak uygulamanızın sorumluluğundadır. İstekleri oluşturmak, aktarımı yürütmek ve yanıtları tiplemek ise SDK’nın sorumluluğundadır. Bu sınırı net tutun: PDF’yi güvenli biçimde okuyun, bir istemci seçin, ihtiyaç duyduğunuz ast yöntemini çağırın ve ilgili hatayı işleyin.

SDK’yı temel alan çıkarma hizmetleri, asyncio toplu işleri, yapay zekâ (AI) aracılarına yönelik araçlar veya komut satırı iş akışları oluştururken bu kılavuzu kullanın. Bu kılavuz, genel bakış ve hızlı başlangıç sayfalarını okuduğunuzu ve Python 3.10 veya daha yeni bir sürümün yanı sıra bir NextPDF Connect uç noktasına sahip olduğunuzu varsayar.

Mimari sınır

Katman	Sahibi	Sorumluluk	Buraya koymayın
Girdi kaynağı	Uygulama	Çağrıyı yapanı yetkilendirin, PDF kaynağını doğrulayın ve çıkarma ilkesini seçin.	Uç nokta URL’si veya kimlik bilgisi sabitleri.
İstemci oluşturma	Uygulama	Ortamdan veya bir gizli anahtar yöneticisinden base_url ve api_key değerlerini okuyun.	Koda gömülü gizli anahtarlar.
NextPDF / AsyncNextPDF	SDK	İsteği oluşturur, Connect’i çağırır ve türü belirlenmiş Pydantic modelleri döndürür.	Etki alanı mantığı veya depolama ilkesi.
ast yöntem ad alanı	SDK	Bir yöntem çağrısını bir Connect uç noktasına eşler ve yanıtı ayrıştırır.	Yapılandırdığınız kapsamın ötesinde yeniden deneme veya geri çekilme ilkesi.
NextPDF Connect uç noktası	dağıtım	Çıkarma işlemini çalıştırır ve kimlik doğrulamayı, kotaları ve lisanslamayı uygular.	Uygulama yetkilendirmesi.

SDK, optik karakter tanıma (OCR) işlemini hiçbir zaman yapmaz. Bir PDF taranmışsa veya yalnızca görüntüden oluşuyorsa, çıkarma işleminden önce OCR çalıştırın. Bu adımı, sınırın dışında kalan bir uygulama sorumluluğu olarak ele alın.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
İstemci oluşturma	base_url ve api_key doğrulanır; bunlardan biri boşsa ValueError oluşturulur.	Her ikisini de ortamdan okuyun; bunları asla koda sabit yazmayın.
Arka uç oluşturma	Uzak bir arka uç, Connect’e havuzlanmış bir bağlantı açar.	İstek başına yeni bir istemci oluşturmak yerine tek bir istemciyi çağrılar arasında yeniden kullanın.
Yöntem çağrısı	İlgili ast yöntemi, isteği serileştirir, PDF baytlarını gönderir ve yanıtı bir Pydantic modeline ayrıştırır.	Önceden doğrulanmış bytes değerini geçirin.
Hata eşleme	SDK, başarısız bir köprü metni aktarım protokolü (HTTP) durumunu belirli bir özel durum alt sınıfına eşler.	Önce en özgül sınıfı yakalayın.
Kapatma	AsyncNextPDF.close() bağlantı havuzunu serbest bırakır; asenkron bağlam yöneticisi bunu sizin için çağırır.	Ya async with kullanın ya da close() yöntemini bir finally bloğunda çağırın.

Önerilen uygulama yapısı

Yol	Amaç
app/pdf/clients.py	Yapılandırılmış bir NextPDF veya AsyncNextPDF oluşturun ve önbelleğe alın.
app/pdf/extraction.py	İlgili ast yöntemi çağrıları etrafındaki uygulama sarmalayıcısı.
app/pdf/validation.py	PDF kaynağı doğrulaması, boyut sınırları ve içerik denetimleri.
tests/pdf/	Çıkarma, hata modu ve asenkron toplu işleme testleri.

PDF doğrulamasını çıkarma işleminden ayrı tutun. Çıkarma katmanına yalnızca yetkilendirilmiş ve boyutu denetlenmiş baytları geçirin; derinlemesine savunma için uç noktanın denetimlerine de güvenin.

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)

Senkron istemci deseni

Komut dosyaları, toplu işler ve not defterleri için senkron NextPDF istemcisini kullanın. SDK’yı çağırmadan önce girdiyi doğrulayın ve çağrının üretebileceği özgül hataları işleyin.

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

Bir sonuç öğesinin yapısı şöyledir:

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

Asenkron ve toplu işleme deseni

Asenkron AsyncNextPDF istemcisini FastAPI gibi asyncio çalışma zamanlarında kullanın. Tek bir istemciyi asenkron bağlam yöneticisi olarak oluşturup eşzamanlı çağrılar arasında paylaşın; her belge için ayrı istemci açmayın. Uç noktanın kotasına uymak için eşzamanlılığı bir semaforla sınırlayın.

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

Hiçbir zaman boş bir except yazmayın. Hatayı işleyin, tanımlı bir sonuca dönüştürün veya yeniden yükseltin.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıt
AsyncNextPDF(backend=...)	Testlerde özel veya yerel bir arka uç ekleyin.	Arka uç, PdfBackend protokolünü karşılamalıdır.
api_version bağımsız değişkeni	Bir Connect uygulama programlama arabirimi (API) sürümünü sabitleyin.	Varsayılan değer v1’dir; yalnızca uç nokta hedef sürümü desteklediğinde değiştirin.
Ortam yapılandırması	Komut satırı arabirimine (CLI) ve Model Context Protocol (MCP) sunucusuna NEXTPDF_BASE_URL ve NEXTPDF_API_KEY değerlerini sağlayın.	Anahtarı, kapsamı iş yüküyle sınırlı bir gizli anahtar olarak değerlendirin.
MCP sunucusu (python -m nextpdf.mcp)	Çıkarma araçlarını MCP özellikli aracılara sunun.	Bu, nextpdf[mcp] ekini ve denetimli bir uç noktayı gerektirir.

Geliştirme iş akışı

1. SDK’yı pip install nextpdf ile kurun veya aracı sunucusu için pip install nextpdf[mcp] komutunu kullanın.
2. Ortamdan NEXTPDF_BASE_URL ve NEXTPDF_API_KEY değerlerini okuyun; böylece hiçbir gizli anahtar kaynak denetimine girmesin.
3. Her PDF kaynağını, SDK’yı çağırmadan önce varlık, boyut ve %PDF- sihirli baytları açısından doğrulayın.
4. İşlem başına tek bir istemci oluşturun ve onu yeniden kullanın; asyncio için onu async with ile açık tutun.
5. Görev için en dar kapsamlı ast yöntemini çağırın: düz metin için extract_cited_text(), tablolar için extract_cited_tables(), yalnızca tam ağaca ihtiyacınız olduğunda ise get_document_ast().
6. İşleyebileceğiniz en özgül özel durumu yakalayın, ardından NextPDFError sınıfını son seçenek olarak kullanın.
7. 100 MiB üzerindeki belgeler için, her bloğu bellekte gerçeklemek yerine CLI akış yolunu kullanın.
8. mypy’yi katı modda çalıştırın ve işlediğiniz her özel durum için bir hata modu testi ekleyin.

Hata yönetimi

Hata	Özel durum	Önerilen yanıt
Etiketlenmemiş PDF, sezgisel yöntemler kapalı	AstNoStructTreeError (HTTP 422)	Uç noktada sezgisel modu açın veya etiketlenmiş bir PDF sağlayın.
Sunucu tarafı oluşturma zaman aşımı	AstBuildTimeoutError (HTTP 504)	Sayfa aralığını azaltın ve yeniden deneyin.
Lisans katmanı gerekli	NextPDFLicenseError (HTTP 402)	Sunucu lisansını yükseltin veya izin verilen bir özelliğe geri dönün.
Hız sınırı veya kota	QuotaExceededError (HTTP 429)	Önce retry_after saniye kadar bekleyin, ardından geri çekilme stratejisiyle yeniden deneyin.
Diğer HTTP hatası	NextPDFAPIError	Önce status_code ve error_code değerlerini inceleyin; günlüğe kaydedin ve tanımlı bir hata sunun.
Herhangi bir SDK hatası	NextPDFError	Son çare; bunun işlenmemiş bir özel durum olarak dışarı çıkmasına asla izin vermeyin.

Uç nokta, hataları yorum isteği (RFC) 9110 ile uyumlu HTTP durum semantiğiyle ve RFC 9457 ile uyumlu, makine tarafından okunabilir hata gövdeleriyle bildirir. Her özel durum, kaynak status_code değerini korur. Bu hataları, taşıma ayrıntılarını çağrıyı yapanlara sızdırmak yerine kendi hata yanıtlarınıza eşleyin.

Güvenli varsayılanlar

Konu	Varsayılan	Ne zaman geçersiz kılınmalı
API sürümü	v1.	Yalnızca uç nokta daha yeni bir sürümü desteklediğinde değiştirin.
Aktarım Katmanı Güvenliği (TLS) doğrulaması	Etkin; güvensiz bir seçenek sunulmaz.	Üretim trafiği için asla devre dışı bırakmayın.
Kimlik bilgileri	Ortamdan okunur; asla koda gömülmez.	Üretimde bir gizli anahtar yöneticisi kullanın.
Bellek içi boyut sınırı	İstemci yolunda 100 MiB üzerindeki PDF’leri reddedin.	Çok kiracılı hizmetler için düşürün; daha büyük dosyalar için CLI’yi kullanın.
Eşzamanlılık	Asenkron toplu işlemlerde bir semaforla sınırlanır.	Ana makinenin çekirdek sayısına göre değil, uç noktanın kotasına göre ayarlayın.
Günlük kaydı	Dosya adını, boyutu, durumu ve süreyi günlüğe kaydedin.	PDF baytlarını veya API anahtarını asla günlüğe kaydetmeyin.

Test denetim listesi

• Oluşturma testleri, boş bir base_url veya api_key değerinin ValueError oluşturduğunu doğrular.
• Doğrulama testleri eksik, boş, aşırı büyük ve PDF olmayan girdileri kapsar.
• Çıkarma testleri, döndürülen model türlerini ve her blokta bir CitationAnchor bulunduğunu doğrular.
• Hata modu testleri AstNoStructTreeError, AstBuildTimeoutError, NextPDFLicenseError, QuotaExceededError ve NextPDFAPIError durumlarını kapsar.
• Asenkron testler, istemcinin bir async with bağlam yöneticisi olarak çalıştığını ve eşzamanlılığın semafor sınırı içinde kaldığını doğrular.
• Yaşam döngüsü testleri, close() yönteminin aktarımı serbest bıraktığını ve tek başına çağrılabildiğini doğrular.
• Testlerin canlı bir uç nokta olmadan çalışması için AsyncNextPDF(backend=...) ile sahte bir arka uç ekleyin.

Ayrıca bkz.

• Python API başvurusu — her istemci yöntemi, modeli ve özel durumu.
• Python CLI — büyük belgeler için akışlı çıkarma.
• Python MCP sunucusu — AI aracıları için çıkarma araçları.
• Python SDK genel bakışı — arka uç seçimleri ve sınırlamalar.