مرجع واجهة برمجة التطبيقات بلغة Python

لمحة سريعة

يوفِّر طقم تطوير البرامج (⁨SDK⁩) بلغة ⁨Python⁩ من ⁨NextPDF⁩ عميلَين، ومساحة أسماء مشتركة واحدة لدوال شجرة البنية المجردة (⁨AST⁩) باسم ast، ونماذج ⁨Pydantic⁩ لكل استجابة، وواجهة سطر أوامر (⁨CLI⁩) باسم nextpdf، وتسلسلًا هرميًا للاستثناءات يتألف من ست فئات. استخدم هذه الصفحة مرجعًا لرموز واجهة برمجة التطبيقات (⁨API⁩) العامة التي تتعامل مع مستندات تنسيق المستندات المحمولة (⁨PDF⁩).

استورد الرموز العامة من الحزمة ذات المستوى الأعلى:

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

تتلقى كل دالة استخراج بايتات ⁨PDF⁩ الخام (bytes) بوصفها الوسيط الموضعي الأول، وتُعيد نموذج ⁨Pydantic⁩ مُحدَّد النوع. مرِّر الخيارات كوسائط مفتاحية فقط. تتشارك دوال NextPDF.ast.* المتزامنة ودوال AsyncNextPDF.ast.* غير المتزامنة التواقيع نفسها. الدوال غير المتزامنة إجراءات مشتركة (⁨coroutines⁩)؛ استدعِها بـ await.

العميل

عميل NextPDF المتزامن يغلِّف العميل غير المتزامن ويُشغِّل كل إجراء مشترك حتى يكتمل. AsyncNextPDF عميل غير متزامن ومدير سياق غير متزامن في آنٍ واحد. استخدم صيغة مدير السياق كي تُغلَق طبقة النقل الأساسية بصورة حتمية.

البواني

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
NextPDF(*, base_url, api_key, api_version='v1')	عنوان ⁨URL⁩ الأساسي ومفتاح ⁨API⁩ كوسائط مفتاحية فقط، مع إصدار ⁨API⁩ اختياري.	ينشئ عميلًا متزامنًا يعتمد على خدمة بعيدة.	NextPDF	ValueError عندما يكون base_url أو api_key فارغًا.	يُشغِّل العمل غير المتزامن بصورة متزامنة؛ ويكون آمنًا داخل الدفاتر التفاعلية ومع حلقة أحداث قيد التشغيل.
AsyncNextPDF(*, base_url='', api_key='', api_version='v1', backend=None)	عنوان ⁨URL⁩ الأساسي ومفتاح ⁨API⁩ كوسائط مفتاحية فقط، مع إصدار ⁨API⁩ اختياري وخلفية مُحقَّنة اختيارية.	ينشئ عميلًا غير متزامن يعتمد على خدمة بعيدة عندما لا تُحقَن أي خلفية.	AsyncNextPDF	ValueError عندما يكون base_url أو api_key فارغًا ولم تُمرَّر أي backend.	مرِّر backend= لحقن خلفية مخصَّصة أو محلية في الاختبارات.
AsyncNextPDF.__aenter__()	لا شيء.	يدخل السياق غير المتزامن ويُعيد العميل.	AsyncNextPDF	لا يُتوقَّع شيء.	استخدم async with AsyncNextPDF(...) as client:.
AsyncNextPDF.__aexit__(*_)	وسائط الاستثناء غير المستخدمة.	يستدعي close() عند الخروج من السياق.	None	لا يُتوقَّع شيء.	يحرِّر النقل حتى إذا رمى متن السياق استثناءً.
AsyncNextPDF.close()	لا شيء.	يُغلق الخلفية البعيدة المملوكة ويحرِّر تجمُّع الاتصالات.	None	لا يُتوقَّع شيء.	يمكن استدعاؤها أكثر من مرة بأمان؛ ولا تُغلَق الخلفيات المُحقَّنة.

لا تُبقِ مفتاح ⁨API⁩ داخل شيفرة المصدر. اقرأ base_url وapi_key من البيئة (NEXTPDF_BASE_URL، NEXTPDF_API_KEY) أو من مدير أسرار.

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

دوال ⁨AST⁩ المتزامنة — NextPDF.ast.*

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
NextPDF.ast.get_document_ast()	pdf_data: bytes؛ الوسائط المفتاحية page_range_start، page_range_end، token_budget.	يبني شجرة ⁨AST⁩ الدلالية الكاملة لكل صفحة.	AstDocument	AstNoStructTreeError، AstBuildTimeoutError، NextPDFLicenseError، QuotaExceededError.	قلِّص نطاق الصفحات عند انتهاء مهلة البناء.
NextPDF.ast.extract_cited_text()	pdf_data: bytes؛ الوسائط المفتاحية page_index، headings_only.	يستخرج جميع كتل النص مع مراسي الاستشهاد.	list[CitedTextBlock]	NextPDFAPIError، QuotaExceededError.	اضبط headings_only=True لاسترجاع عُقد العناوين فقط.
NextPDF.ast.extract_cited_tables()	pdf_data: bytes؛ الوسيطة المفتاحية page_range (dict يحتوي start وend).	يستخرج جميع الجداول مع مراسي استشهاد على مستوى الخلية.	ExtractCitedTablesResponse	NextPDFAPIError، QuotaExceededError.	احذف page_range لمسح المستند بأكمله.
NextPDF.ast.get_ast_node()	pdf_data: bytes، node_id: str.	يسترجع عُقدة واحدة باستخدام مُعرِّفها.	GetAstNodeResponse	NextPDFError عندما يتعذَّر العثور على العُقدة.	node_id صيغته ast:{hash6}:{pageIdx}:{seq}.
NextPDF.ast.search_ast_nodes()	pdf_data: bytes؛ الوسائط المفتاحية node_type، page_index، text_query، max_results=100.	يُعيد العُقد السطحية المطابِقة للمرشِّحات.	SearchAstNodesResponse	NextPDFAPIError.	text_query مطابقة لسلسلة فرعية غير حسَّاسة لحالة الأحرف.
NextPDF.ast.get_ast_diff()	original_pdf_data: bytes، modified_pdf_data: bytes.	يقارن مستندَين بحسب البنية.	GetAstDiffResponse	NextPDFAPIError، QuotaExceededError.	يُبلِّغ عن العُقد المُضافة والمحذوفة والمُغيَّرة.

دوال ⁨AST⁩ غير المتزامنة — AsyncNextPDF.ast.*

كل دالة غير متزامنة إجراء مشترك (⁨coroutine⁩)، ولها المعاملات والقيم الافتراضية ونوع الإعادة وأنماط الفشل نفسها مثل نظيرتها المتزامنة. استدعِها بـ await داخل بيئة تشغيل ⁨asyncio.⁩

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
AsyncNextPDF.ast.get_document_ast()	pdf_data: bytes؛ الوسائط المفتاحية page_range_start، page_range_end، token_budget.	يبني شجرة ⁨AST⁩ الدلالية الكاملة لكل صفحة.	AstDocument	AstNoStructTreeError، AstBuildTimeoutError، NextPDFLicenseError، QuotaExceededError.	await النتيجة.
AsyncNextPDF.ast.extract_cited_text()	pdf_data: bytes؛ الوسائط المفتاحية page_index، headings_only.	يستخرج جميع كتل النص مع مراسي الاستشهاد.	list[CitedTextBlock]	NextPDFAPIError، QuotaExceededError.	await النتيجة.
AsyncNextPDF.ast.extract_cited_tables()	pdf_data: bytes؛ الوسيطة المفتاحية page_range.	يستخرج جميع الجداول مع مراسي استشهاد على مستوى الخلية.	ExtractCitedTablesResponse	NextPDFAPIError، QuotaExceededError.	await النتيجة.
AsyncNextPDF.ast.get_ast_node()	pdf_data: bytes، node_id: str.	يسترجع عُقدة واحدة باستخدام مُعرِّفها.	GetAstNodeResponse	NextPDFError عندما يتعذَّر العثور على العُقدة.	await النتيجة.
AsyncNextPDF.ast.search_ast_nodes()	pdf_data: bytes؛ الوسائط المفتاحية node_type، page_index، text_query، max_results=100.	يُعيد العُقد السطحية المطابِقة للمرشِّحات.	SearchAstNodesResponse	NextPDFAPIError.	await النتيجة.
AsyncNextPDF.ast.get_ast_diff()	original_pdf_data: bytes، modified_pdf_data: bytes.	يقارن مستندَين بحسب البنية.	GetAstDiffResponse	NextPDFAPIError، QuotaExceededError.	await النتيجة.

استخدم العميل غير المتزامن مديرَ سياق لتشغيل عمليتَي استخراج في وقت واحد:

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

النماذج

كل استجابة نموذج ⁨Pydantic.⁩ استورد فئات النماذج من nextpdf أو nextpdf.models.ast.

الرمز	النوع	الحقول الرئيسية	ملاحظات
AstDocument	جذر المستند	schema_version، source_hash، page_count، root: AstNode، estimated_tokens (خاصية).	تُعيدها get_document_ast(). تقبل الأسماء البديلة schemaVersion، sourceHash، وpageCount.
AstNode	عُقدة شجرة	id، type: NodeType، page_index، bbox، text_content، attributes، children: list[AstNode]، pdf_object_number، mcid.	عُقدة عوديّة تمثل شجرة المستند.
AstNodeMeta	بيانات وصفية للاستجابة	etag، pages_processed.	مُجمَّدة؛ مُرفقة باستجابات العُقدة والبحث.
AstNodeShallow	نتيجة بحث	id، type: NodeType، page_index، bbox، text_content، attributes، children_count.	مُجمَّدة؛ بلا أبناء عميقين.
BoundingBox	كائن قيمة	x، y، width، height (تتراوح كل منها بين 0.0–1.0).	إحداثيات مُسوَّاة داخل الصفحة.
CitationAnchor	كائن قيمة	node_id، page_index، bbox: BoundingBox، confidence، content_hash.	سجل مصدر لكل كتلة.
CitedTextBlock	كتلة نص	text، citation: CitationAnchor، node_type، chunk_index، depth.	كل عنصر في قائمة extract_cited_text().
CitedTableBlock	كتلة جدول	table_node_id، page_index، citation_anchor، row_count، col_count، rows.	مُجمَّدة؛ جدول واحد.
CitedTableCell	خلية جدول	row، col، row_span، col_span، text، bbox، confidence.	مُجمَّدة؛ خلية واحدة.
NodeType	تعداد	document، section، heading، paragraph، list، table، figure، وغيرها.	تعداد نصي لقيم نوع العُقدة.
GetAstNodeResponse	استجابة	node: AstNode، meta: AstNodeMeta.	تُعيدها get_ast_node().
SearchAstNodesResponse	استجابة	nodes: list[AstNodeShallow]، total_matches، truncated، meta.	تُعيدها search_ast_nodes().
ExtractCitedTablesResponse	استجابة	tables: list[CitedTableBlock]، table_count، pages_processed.	تُعيدها extract_cited_tables().
AstDiffEntry	عنصر فرق	type (added/removed/changed)، node_id، node_type، page_index، text_preview.	تغيير واحد ضمن الفرق.
AstDiffSummary	إجماليات الفرق	added_node_count، removed_node_count، changed_node_count.	أعداد مُجمَّعة.
GetAstDiffResponse	استجابة	original_page_count، modified_page_count، summary: AstDiffSummary، diff: list[AstDiffEntry]، pages_processed.	تُعيدها get_ast_diff().

اقرأ مرساة الاستشهاد من كتلة نص مُستخرَجة:

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

أوامر واجهة سطر الأوامر

nextpdf هو أمر الاستخراج من الطرفية. مرِّر --base-url و--api-key، أو اضبط NEXTPDF_BASE_URL وNEXTPDF_API_KEY في البيئة. يتطلَّب كل أمر عدا version إعدادات الاتصال. عندما تكون قيمة PDF_PATH هي -، تُقرأ بايتات ⁨PDF⁩ من الإدخال القياسي.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
nextpdf extract text	PDF_PATH؛ --format {json,markdown,plain}، --page، --headings-only.	يُصدِر كتل النص المُستشهَد بها بتنسيق ترميز كائنات ⁨JavaScript⁩ (⁨JSON⁩).	يكتب إلى الإخراج القياسي أو إلى ملف --output.	رمز خروج 1 لأي NextPDFError.	--page يختار فهرس صفحة واحدًا يبدأ من 0.
nextpdf extract tables	PDF_PATH؛ --format {json,csv}، --page-start، --page-end.	يُصدِر الجداول بترميز ⁨JSON.⁩	يكتب إلى الإخراج القياسي أو إلى ملف --output.	رمز خروج 1 لأي NextPDFError.	--format csv يكتب كتلة واحدة من قيم مفصولة بفواصل (⁨CSV⁩) لكل جدول.
nextpdf ast	PDF_PATH؛ --page-start، --page-end، --token-budget.	يُصدِر شجرة ⁨AST⁩ الدلالية الكاملة بترميز ⁨JSON.⁩	يكتب إلى الإخراج القياسي أو إلى ملف --output.	رمز خروج 1 لأي NextPDFError.	استخدم --token-budget لتقييد حجم الاستجابة.
nextpdf info	PDF_PATH.	يُصدِر البيانات الوصفية للمستند: عدد الصفحات، وإصدار المخطَّط، وبصمة المصدر، والرموز المُقدَّرة، وملخَّص الجذر.	يكتب ⁨JSON⁩ إلى الإخراج القياسي أو إلى ملف --output.	رمز خروج 1 لأي NextPDFError.	أمر فحص خفيف.
nextpdf version	لا شيء.	يطبع إصدار ⁨SDK⁩ المُثبَّت.	يكتب إلى الإخراج القياسي.	لا يُتوقَّع شيء.	لا يتصل بأي خادم؛ ولا يحتاج إلى بيانات اعتماد.
python -m nextpdf.mcp	لا شيء (يقرأ NEXTPDF_BASE_URL، NEXTPDF_API_KEY).	يُشغِّل خادم بروتوكول سياق النموذج (⁨MCP⁩) عبر الإدخال/الإخراج القياسي — ⁨input/output.⁩	عملية خادم طويلة التشغيل.	RuntimeError عندما تكون متغيرات البيئة غير مضبوطة.	يتطلَّب الإضافة nextpdf[mcp].

استخرج الجداول كقيم مفصولة بفواصل (⁨CSV⁩) من نطاق صفحات:

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

الاستثناءات

يوجد التسلسل الهرمي للاستثناءات في nextpdf.models.errors ويُعاد تصديره من nextpdf. التقط أكثر الفئات تحديدًا التي يمكن لشيفرتك معالجتها، ثم تراجَع إلى الفئة الأساسية. يُبلِّغ الخادم عن الفشل وفق دلالات حالة بروتوكول نقل النص التشعبي (⁨HTTP⁩) المتوافقة مع طلب التعليقات (⁨RFC⁩) 9110. يحمل كل استثناء قيمة status_code الأصلية وerror_code.

الرمز	الفئة الأساسية	status_code	متى يُرمى	ملاحظات
NextPDFError	Exception	اختياري	الفئة الأساسية لكل أخطاء ⁨SDK.⁩	يحمل قيمة status_code. التقطه أخيرًا كحلٍّ احتياطي.
NextPDFAPIError	NextPDFError	مطلوب	أعادت نقطة نهاية ⁨Connect⁩ خطأ ⁨HTTP.⁩	يضيف error_code.
NextPDFLicenseError	NextPDFAPIError	402	يتطلَّب الخادم ترخيصًا من فئة أعلى لهذه الميزة.	error_code هو license/tier-required.
QuotaExceededError	NextPDFAPIError	429	تجاوز الطلب حد المعدل أو الحصة.	يحمل retry_after؛ التزم به قبل إعادة المحاولة.
AstNoStructTreeError	NextPDFAPIError	422	ملف ⁨PDF⁩ غير موسوم، والحل الاحتياطي الاستدلالي غير مُمكَّن.	مكِّن الوضع الاستدلالي أو وفِّر ملف ⁨PDF⁩ موسومًا.
AstBuildTimeoutError	NextPDFAPIError	504	انتهت مهلة بناء ⁨AST⁩ على الخادم.	قلِّص نطاق الصفحات وأعد المحاولة.

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)

ملاحظات التطوير

• عميل NextPDF المتزامن يفوِّض كل استدعاء إلى AsyncNextPDF. يمكنك استدعاؤه من دفتر تفاعلي أو من خيط يُشغِّل بالفعل حلقة أحداث، لأنه يرسل الإجراء المشترك إلى خيط عامل عند اكتشاف حلقة قيد التشغيل.
• استخدم صيغة مدير السياق غير المتزامن async with AsyncNextPDF(...) as client: كي يُغلَق تجمُّع الاتصالات بصورة حتمية. عندما تُنشئ AsyncNextPDF مباشرةً، فاستدعِ close() بنفسك.
• لا يُسجَّل رمز الحامل (⁨bearer⁩) أبدًا ولا يُدرَج في رسائل الأخطاء، ويكون التحقق من أمان طبقة النقل (⁨TLS⁩) مُمكَّنًا افتراضيًا. لا تُضمِّن بيانات الاعتماد في المصدر؛ بل اقرأها من البيئة أو من مدير أسرار.
• جميع النماذج فئات ⁨Pydantic v2⁩؛ وعدة نماذج استجابة مُجمَّدة (غير قابلة للتغيير). تعامَل مع الكتل المُستخرَجة كقيم للقراءة فقط.
• تنهي واجهة سطر الأوامر التنفيذ برمز الحالة 1 لأي NextPDFError وتطبع الرسالة إلى الخطأ القياسي. راعِ رمز الخروج هذا في خطوط الأنابيب.

انظر أيضًا

• دليل مطوِّر طقم تطوير البرامج (⁨SDK⁩) في ⁨Python⁩ — البنية، والتجميع غير المتزامن، ومعالجة الفشل.
• واجهة سطر الأوامر في ⁨Python⁩ — الاستخراج من الطرفية وبث الملفات الكبيرة.
• خادم ⁨MCP⁩ في ⁨Python⁩ — إتاحة أدوات الاستخراج لعملاء الذكاء الاصطناعي (⁨AI⁩).
• ⁨RFC 9110⁩ (دلالات ⁨HTTP⁩) و⁨RFC 9457⁩ (تفاصيل المشكلات لواجهات ⁨HTTP⁩) يصفان دلالات الحالة وأجسام الأخطاء القابلة للقراءة آليًا التي تُعيدها نقطة نهاية ⁨Connect.⁩ راجع فهرس ⁨RFC⁩ الصادر عن ⁨IETF⁩ للنص المعتمد.