Python CLI

Python CLI

Taşınabilir Belge Biçimi (PDF) dosyalarından içeriği terminalden ayıklamak için nextpdf komutunu kullanın. Komutu bir NextPDF Connect uç noktasına yöneltin, bir PDF gönderin ve yapılandırılmış çıktıyı — alıntılanmış metin, tablolar, tam anlamsal Soyut Sözdizimi Ağacı (AST) veya bir meta veri özeti — standart çıktıda (stdout) ya da bir dosyada alın.

Komut yapısı

Buradaki nextpdf komutu bir Click komut grubudur. Bağlantı ve oturum seçenekleri — --base-url, --api-key, --log-level, --output/-o ve --strict — gruba aittir; bu nedenle bunları alt komuttan önce yerleştirin. --format veya --page gibi alt komutu ve seçeneklerini ise sonraya koyun:

nextpdf [GROUP OPTIONS] COMMAND [SUBCOMMAND] PDF_PATH [COMMAND OPTIONS]

Bir grup seçeneğini alt komuttan sonra koyarsanız komut başarısız olur. Örneğin nextpdf info document.pdf --base-url ... komutu Error: No such option: --base-url bildirir ve çıkış kodu 2 ile çıkar; çünkü Click, info alt komutunu ayrıştırmaya geçmişken --base-url seçeneğiyle karşılaşır ve info bu seçeneği tanımlamaz.

Sıralama tuzağından kaçınmak için kimlik bilgilerini ortam değişkenleri aracılığıyla sağlayın (bkz. Kabuk başına bir kez yapılandırma). Aşağıdaki örnekler, doğru sıranın açıkça görülmesi için önce açık bayrak kullanımını gösterir.

Hızlı başvuru

Metni JavaScript Nesne Gösterimi (JSON) olarak ayıklayın:

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" extract text document.pdf

Tabloları virgülle ayrılmış değerler (CSV) olarak ayıklayın:

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" extract tables invoice.pdf --format csv

Belgenin meta verilerini ve yapısını inceleyin:

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" info document.pdf

Tam anlamsal AST’yi alın:

nextpdf --base-url http://localhost:8080 --api-key "$NEXTPDF_API_KEY" ast document.pdf

Bir sunucuyla iletişim kurmadan kurulu yazılım geliştirme kitinin (SDK) sürümünü yazdırın:

nextpdf version

Buradaki version komutu, ne --base-url ne de --api-key gerektiren tek komuttur. Diğer her komut sunucuyla iletişim kurar ve her ikisini de gerektirir.

Her örnek, uygulama programlama arayüzü (API) anahtarını komut satırına gömmek yerine NEXTPDF_API_KEY ortam değişkeninden okur. Anahtarı gizli bilgi olarak ele alın. Komut satırına açık metin olarak yazılmış bir anahtar, kabuk geçmişinizde ve süreç listesinde (ps) ana bilgisayardaki diğer kullanıcılar tarafından görülebilir.

Komutlar ve seçenekler

Grup seçenekleri

Bunları alt komuttan önce yerleştirin. Her bağlantı seçeneği ayrıca bir ortam değişkeninden de okur; bu nedenle değişken ayarlandığında bayrağı atlayabilirsiniz.

Seçenek	Ortam değişkeni	Varsayılan	Amaç
--base-url	NEXTPDF_BASE_URL	(zorunlu)	NextPDF Connect sunucusunun URL’si.
--api-key	NEXTPDF_API_KEY	(zorunlu)	Taşıyıcı kimlik doğrulaması için API anahtarı.
--log-level	—	warning	Günlük ayrıntı düzeyi: debug, info, warning veya error. Günlükler standart hataya (stderr) gönderilir.
--output, -o	—	stdout	Komut çıktısını stdout yerine bir dosyaya yazın.
--strict	—	kapalı	Gelecekteki kullanım için ayrılmıştır. Bayrak bugün ayrıştırılır ancak davranışı değiştirmez.
--help, -h	—	—	Yardımı gösterip çıkar.

Hem --base-url hem de --api-key değerleri, version dışındaki her komut için zorunludur. Her iki değer de eksikse — bayrak da ortam değişkeni de yoksa — komut bir hata yazdırır ve çıkış kodu 1 ile çıkar.

nextpdf extract text

Alıntılanmış metin bloklarını ayıklayın. Her blok; bir düğüm tanımlayıcısı, sayfa dizini, sınırlayıcı kutu ve güven puanı içeren bir alıntı bağlantısı içerir.

nextpdf [GROUP OPTIONS] extract text PDF_PATH [--format FORMAT] [--page N] [--headings-only]

Seçenek	Değerler	Varsayılan	Amaç
--format	json, markdown, plain	json	Çıktı biçimi.
--page	tam sayı	tüm sayfalar	Yalnızca belirtilen 0 tabanlı sayfa dizinini ayıklayın.
--headings-only	bayrak	kapalı	Yalnızca başlık düğümlerini ayıklayın.

PDF_PATH bir dosya yoludur ya da PDF baytlarını standart girdiden (stdin) okumak için - değeridir.

nextpdf extract tables

Her tabloyu alıntı bağlantıları ve hücre düzeyindeki yapısıyla birlikte ayıklayın.

nextpdf [GROUP OPTIONS] extract tables PDF_PATH [--format FORMAT] [--page-start N] [--page-end N]

Seçenek	Değerler	Varsayılan	Amaç
--format	json, csv	json	Çıktı biçimi.
--page-start	tam sayı	ilk sayfa	Başlangıç sayfası dizini (0 tabanlı).
--page-end	tam sayı	son sayfa	Bitiş sayfası dizini (0 tabanlı).

PDF_PATH bir dosya yoludur ya da stdin’den okumak için - değeridir.

nextpdf ast

Tam anlamsal AST’yi JSON olarak döndürün: başlıklar, paragraflar, tablolar, listeler ve şekiller dahil düğümlerden oluşan, sınırlayıcı kutuları ve metin içeriğini de içeren hiyerarşik bir ağaç.

nextpdf [GROUP OPTIONS] ast PDF_PATH [--page-start N] [--page-end N] [--token-budget N]

Seçenek	Değerler	Varsayılan	Amaç
--page-start	tam sayı	ilk sayfa	Başlangıç sayfası dizini (0 tabanlı).
--page-end	tam sayı	son sayfa	Bitiş sayfası dizini (0 tabanlı).
--token-budget	tam sayı	sınırsız	Döndürülen AST için yaklaşık jeton sınırı.

PDF_PATH bir dosya yoludur ya da stdin’den okumak için - değeridir. ast komutu tek bir belge ağacı üretir; iki PDF’yi karşılaştırmaz. Yapısal karşılaştırma için bkz. Tarif: iki PDF düzeltmesini karşılaştırma.

nextpdf info

Tek bir belgenin kısa bir JSON özetini yazdırın: şema sürümü, kaynak özeti, sayfa sayısı, tahmini jeton sayısı, kök düğüm türü ve kök alt öğelerinin sayısı.

nextpdf [GROUP OPTIONS] info PDF_PATH

PDF_PATH bir dosya yoludur ya da stdin’den okumak için - değeridir.

nextpdf version

Kurulu SDK sürümünü, örneğin nextpdf 1.1.0, yazdırın ve çıkın. Bu komut hiçbir sunucuyla iletişim kurmaz ve hiçbir kimlik bilgisi gerektirmez.

nextpdf version

Kabuk başına bir kez yapılandırma

Bağlantı seçeneklerini ortam değişkenleri olarak bir kez ayarlayın ve yinelenen bayrakları atlayın. Bu biçim ayrıca seçenek sıralama tuzağından tamamen kaçınır; çünkü kimlik bilgileri komut satırında hiçbir zaman görünmez.

export NEXTPDF_BASE_URL=http://localhost:8080
export NEXTPDF_API_KEY=your-key
nextpdf extract text document.pdf

Windows PowerShell’de:

$env:NEXTPDF_BASE_URL = "http://localhost:8080"
$env:NEXTPDF_API_KEY = "your-key"
nextpdf extract text document.pdf

Anahtarı, sürüm denetiminin dışında tuttuğunuz bir gizli bilgi deposundan veya bir .env dosyasından yüklemeyi tercih edin. Bir üretim anahtarını paylaşılan bir terminal oturumuna veya sürüm denetimine eklediğiniz bir betiğe yapıştırmayın.

Çıktı biçimleri

Her komut için çıktı biçimini --format ile seçin. Metin ve tablo komutları birden fazla biçimi destekler; ast ve info ise her zaman JSON üretir.

Komut	Biçimler	Varsayılan
extract text	json, markdown, plain	json
extract tables	json, csv	json
ast	json	json
info	json	json

Sonraki aşamadaki bir program sayfa dizinlerine, güven puanlarına veya düğüm tanımlayıcılarına gerek duyduğunda JSON’u seçin. Tabloları bir elektronik tabloya veya tablo odaklı bir iş hattına aktarırken CSV’yi seçin. Sonucu bir kişi veya yalnızca metin işleyen bir araç okuyacaksa plain ya da markdown biçimini seçin.

JSON çıktısını ayrıştırma

Metin komutu, alıntılanmış bloklardan oluşan bir JSON dizisi üretir. Her blokta text, bir citation nesnesi (node_id, page_index, bbox, confidence) ve isteğe bağlı bir node_type bulunur. Çıktıyı --output ile bir dosyaya gönderin ya da stdout’u yönlendirin, ardından ayrıştırın.

Bu kabuk örneği, yalnızca 0. sayfadaki başlıkları korumak için jq kullanır:

nextpdf --output blocks.json extract text report.pdf --format json
jq '[.[] | select(.citation.page_index == 0 and .node_type == "heading") | .text]' blocks.json

Aynı verileri Python’da kolayca ayrıştırabilirsiniz. Komut satırı arayüzü (CLI) bir JSON dizisi yazar; bu nedenle diziyi standart kitaplıkla yükleyip ilgili alanları okuyun:

"""Parse cited text blocks emitted by `nextpdf extract text --format json`."""

import json
from pathlib import Path


def load_headings(blocks_path: Path) -> list[str]:
    """Return the text of every heading block on page 0.

    Args:
        blocks_path: Path to the JSON file written by `nextpdf extract text`.

    Returns:
        The text of each heading-type block whose citation is on page 0.
    """
    raw = blocks_path.read_text(encoding="utf-8")
    blocks: list[dict[str, object]] = json.loads(raw)
    headings: list[str] = []
    for block in blocks:
        citation = block["citation"]
        if block.get("node_type") == "heading" and citation["page_index"] == 0:
            headings.append(str(block["text"]))
    return headings


if __name__ == "__main__":
    for heading in load_headings(Path("blocks.json")):
        print(heading)

Ham sözlükler yerine doğrulanmış, tipli modellere gerek duyduğunuzda, CLI çıktısını ayrıştırmak yerine doğrudan SDK’yi çağırın. Daha fazla bilgi için Python genel bakışı sayfasına bakın: NextPDF istemcisi ve CitedTextBlock dönüş türü.

CSV çıktısını ayrıştırma

Tablo komutu, --format csv ile tablo başına bir CSV bloğu yazar. # Table N (pM) biçimindeki bir açıklama satırı her tablonun önünde yer alır ve tablonun 1 tabanlı tablo numarasını ve 0 tabanlı sayfa dizinini belirtir. Ardışık tabloları boş bir satır ayırır. CLI, hücre değerlerini Python’un csv modülüyle tırnaklayıp kaçış karakterleri ekleyerek işler; böylece virgül, tırnak veya satır sonu içeren değerler güvenli biçimde korunur.

nextpdf --output tables.csv extract tables statement.pdf --format csv

Dosya birden çok CSV bloğu içerdiğinden, her bloğu bağımsız bir tablo olarak ayrıştırmadan önce açıklama satırlarına göre ayırın:

"""Split multi-table CSV output from `nextpdf extract tables --format csv`."""

import csv
import io
from pathlib import Path


def read_tables(csv_path: Path) -> list[list[list[str]]]:
    """Parse the multi-block CSV file into a list of tables.

    Each table is a list of rows; each row is a list of cell strings.
    The leading `# Table N (pM)` comment row is dropped from every table.

    Args:
        csv_path: Path to the file written by `nextpdf extract tables`.

    Returns:
        One parsed table per `# Table` block in the file.
    """
    text = csv_path.read_text(encoding="utf-8")
    tables: list[list[list[str]]] = []
    current: list[str] = []
    for line in text.splitlines(keepends=True):
        if line.startswith("# Table ") and current:
            tables.append(_parse_block(current))
            current = []
        current.append(line)
    if current:
        tables.append(_parse_block(current))
    return tables


def _parse_block(lines: list[str]) -> list[list[str]]:
    """Parse one CSV block, discarding its leading comment row."""
    reader = csv.reader(io.StringIO("".join(lines)))
    rows = [row for row in reader if row]
    return rows[1:] if rows and rows[0] and rows[0][0].startswith("# Table ") else rows


if __name__ == "__main__":
    for index, table in enumerate(read_tables(Path("tables.csv")), start=1):
        print(f"table {index}: {len(table)} rows")

Çıkış kodları ve hata algılama

CLI üç çıkış kodu kullanır. Başarı veya hataya göre dallanmak için kabuk betiklerinde $? değerini, PowerShell’de ise $LASTEXITCODE değerini denetleyin. Tanılama iletilerini, stdout’taki verilerden ayrı kalan stderr’den okuyun.

Çıkış kodu	Anlamı	Örnekler
0	Başarı.	Komut tamamlandı; version çıktısı yazdırıldı.
1	Çalışma zamanı hatası. CLI, stderr’e Error: <message> yazdırır.	Girdi dosyası bulunamadı veya normal bir dosya değil, boş stdin, eksik veya geçersiz --base-url/--api-key, herhangi bir sunucu tarafı hatası (lisans gerekli, kota aşıldı, etiketsiz PDF, AST oluşturma zaman aşımı veya başka bir API hatası).
2	Click tarafından bildirilen kullanım hatası.	Bilinmeyen komut veya seçenek (alt komuttan sonra yerleştirilmiş bir grup seçeneği dahil), PDF_PATH gibi eksik bir zorunlu bağımsız değişken.

Her sunucu tarafı hatası, stderr’de insan tarafından okunabilir bir iletiyle 1 çıkış kodunu döndürür. SDK, tipli bir özel durum üretir — NextPDFLicenseError (Köprü Metni Aktarım Protokolü (HTTP) 402), QuotaExceededError (HTTP 429), AstNoStructTreeError (HTTP 422, etiketsiz PDF), AstBuildTimeoutError (HTTP 504) veya temel NextPDFAPIError. CLI bunların tümünü ortak NextPDFError tabanı altında yakalar, iletiyi yazdırır ve 1 ile çıkar. CLI, hata türü başına ayrı çıkış kodları açığa çıkarmaz. Örneğin bir betikte bir kota hatasını bir lisans hatasından ayırt etmek için stderr’deki ileti metnini inceleyin veya doğrudan SDK’yi çağırın (özel durum sınıfları için Python genel bakışı sayfasına bakın).

Verileri tanılama çıktısından ayırmak için bu betik yazma desenini kullanın:

#!/usr/bin/env bash
set -euo pipefail

# Credentials come from the environment, not the command line.
: "${NEXTPDF_BASE_URL:?set NEXTPDF_BASE_URL}"
: "${NEXTPDF_API_KEY:?set NEXTPDF_API_KEY}"

if nextpdf --output contract.ast.json ast contract.pdf; then
  echo "AST written to contract.ast.json"
else
  status=$?
  echo "nextpdf failed with exit code ${status}" >&2
  exit "${status}"
fi

CLI, --output ile verileri belirtilen dosyaya yazar ve stderr’e yalnızca Written to <path> onay satırını yazdırır; böylece stdout boş kalır. --output olmadan veriler stdout’a gider ve onu yönlendirebilirsiniz.

Tarifler

Aşağıdaki her tarif yalnızca doğrulanmış komutları ve bayrakları kullanır. Her durumda kimlik bilgileri ortamdan gelir.

Tarif: fatura tablolarını CSV’ye ayıklama

Bir elektronik tablo veya muhasebe iş hattı için bir fatura klasörünü belge başına bir CSV dosyasına dönüştürün:

#!/usr/bin/env bash
set -euo pipefail

: "${NEXTPDF_BASE_URL:?set NEXTPDF_BASE_URL}"
: "${NEXTPDF_API_KEY:?set NEXTPDF_API_KEY}"

mkdir -p out
for pdf in invoices/*.pdf; do
  name="$(basename "${pdf}" .pdf)"
  nextpdf --output "out/${name}.csv" extract tables "${pdf}" --format csv
done

Her out/<name>.csv, algılanan tablo başına bir CSV bloğu içerir; her bloğun önünde bir # Table N (pM) başlığı yer alır. Blokları yukarıda gösterilen CSV okuyucusuyla ayrıştırın.

Tarif: belge taslağı oluşturma

Okuyabileceğiniz veya notlara yapıştırabileceğiniz hızlı bir taslak üretmek için --headings-only seçeneğini markdown biçimiyle birleştirin:

nextpdf --output outline.md extract text whitepaper.pdf --headings-only --format markdown

Tarif: iki PDF düzeltmesini karşılaştırma

CLI ast komutu tek bir belgenin ağacını döndürür; bir diff alt komutu yoktur. Yapısal karşılaştırma SDK’de client.ast.get_ast_diff(...) olarak, Model Context Protocol (MCP) sunucusunda ise nextpdf_diff aracı olarak bulunur. Karşılaştırmayı SDK aracılığıyla çalıştırın:

"""Compare two PDF revisions structurally with the NextPDF SDK.

The API key is read from the environment, never hard-coded.
"""

import os
from pathlib import Path

from nextpdf import NextPDF


def diff_revisions(original: Path, modified: Path) -> None:
    """Print a structural diff summary between two PDF revisions.

    Args:
        original: Path to the earlier PDF revision.
        modified: Path to the later PDF revision.
    """
    base_url = os.environ["NEXTPDF_BASE_URL"]
    api_key = os.environ["NEXTPDF_API_KEY"]

    client = NextPDF(base_url=base_url, api_key=api_key)
    result = client.ast.get_ast_diff(
        original.read_bytes(),
        modified.read_bytes(),
    )

    summary = result.summary
    print(f"added:   {summary.added_node_count}")
    print(f"removed: {summary.removed_node_count}")
    print(f"changed: {summary.changed_node_count}")
    for entry in result.diff:
        preview = entry.text_preview or ""
        print(f"  {entry.type:<8} {entry.node_type:<12} p{entry.page_index} {preview}")


if __name__ == "__main__":
    diff_revisions(Path("contract-v1.pdf"), Path("contract-v2.pdf"))

Aynı karşılaştırmayı bir betik yerine bir yapay zeka (AI) aracısından çalıştırmak için MCP sunucusunu kaydedin ve nextpdf_diff aracını çağırın. Python MCP sunucusu sayfasına bakın.

Tarif: başka bir araçtan PDF akışı sağlama

PDF baytlarını - ile stdin’den okuyarak nextpdf komutunu, stdout’unda PDF üreten başka bir aracın arkasına zincirleyin:

curl --silent https://example.com/report.pdf | nextpdf info -

Buradaki - bağımsız değişkeni komuta belgeyi stdin’den okumasını söyler. Hiç bayt gelmezse komut bir hata bildirir ve 1 ile çıkar.

Performans notları

CLI, her yanıtı bellekte oluşturur ve bir kez yazar. Çıktıyı yönlendirmek veya iletmek kolaydır ancak çıktı kademeli olarak üretilmez. Büyük bir AST veya tablo kümesi, ilk bayt stdout’a veya --output dosyasına ulaşmadan önce tümüyle ara belleğe alınır. Bellek ve gecikme planlamasını akışa göre değil, belgenin tamamına ait yanıtlara göre yapın.

Her nextpdf çağrısı yeni bir istemci ve HTTP bağlantısı oluşturur; bu nedenle çok sayıda dosyada çalışan bir döngü, dosya başına bir bağlantı açar ve kapatır. Bağlantı maliyeti, sunucu tarafı ayıklama süresinin yanında genellikle küçüktür ancak ölçek büyüdükçe gerçek bir ek yüke dönüşür.

• Tek bir uç noktayı yeniden kullanın. Sunucunun ısınmış önbellekleri ve bağlantı havuzlarını yeniden kullanabilmesi için her çağrıyı aynı NextPDF Connect dağıtımına yöneltin. Bilinçli olarak yük dengelemesi yapmıyorsanız bir grubu birden fazla uç noktaya yaymaktan kaçının.
• Çağrı başına işi sınırlayın. Yalnızca gerek duyduğunuz sayfaları işlemek için --page, --page-start/--page-end veya --token-budget kullanın. Daha küçük sayfa aralıkları hem sunucu süresini hem de yanıt boyutunu azaltır; --token-budget, aracınızın okuması gereken AST’yi sınırlar.
• Büyük işler için tek bir süreçte toplu işleyin. Yüksek hacimli toplu işler için, yinelenen CLI çağrıları yerine Python SDK’sini tercih edin. Tek, uzun ömürlü bir NextPDF veya AsyncNextPDF istemcisi, her belge için tek bir havuzlanmış HTTP bağlantısını yeniden kullanır; bu da bir CLI döngüsünün her seferinde ödediği süreç başına başlatma ve bağlantı kurma maliyetini ortadan kaldırır. Python genel bakışı sayfası istemci yaşam döngüsünü gösterir ve AsyncNextPDF, çok sayıda PDF üzerinde eş zamanlı ayıklamayı destekler.
• Günlükleri veri yolundan uzak tutun. Toplu çalıştırmalar için --log-level seçeneğini varsayılan değerinde bırakın. Tanılama günlükleri stderr’e gider ve stdout verilerini bozmaz ancak düzeyi debug düzeyine yükseltmek gürültü ve küçük bir ek yük getirir.