Справочник по Python API

Краткий обзор

SDK NextPDF для Python предоставляет два клиента, общее пространство имён методов абстрактного синтаксического дерева (AST) ast, модели Pydantic для каждого ответа, интерфейс командной строки (CLI) nextpdf и иерархию исключений из шести классов. Используйте эту страницу как справочник по общедоступным символам интерфейса прикладного программирования (API) для работы с документами в формате Portable Document Format (PDF).

Импортируйте общедоступные символы из пакета верхнего уровня:

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

Каждый метод извлечения принимает байты PDF (bytes) первым позиционным аргументом и возвращает типизированную модель Pydantic. Передавайте параметры как именованные аргументы. Синхронные методы NextPDF.ast.* и асинхронные методы AsyncNextPDF.ast.* имеют одинаковые сигнатуры. Асинхронные методы являются сопрограммами; вызывайте их с помощью 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.*

Каждый асинхронный метод является сопрограммой с теми же параметрами, значениями по умолчанию, типом возвращаемого значения и режимами отказа, что и синхронный аналог. Вызывайте его с помощью 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]}"

Команды CLI

Команда 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 Object Notation (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).	Запускает сервер Model Context Protocol через стандартный 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), согласованной с Request for Comments (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 никогда не записывается в журнал и не включается в сообщения об ошибках, а проверка Transport Layer Security (TLS) включена по умолчанию. Не встраивайте учётные данные в исходный код; считывайте их из окружения или менеджера секретов.
• Все модели являются классами Pydantic v2; несколько моделей ответов неизменяемы (immutable). Рассматривайте извлечённые блоки как значения только для чтения.
• CLI завершается с кодом 1 для любого NextPDFError и выводит сообщение в стандартный поток ошибок. Используйте этот код завершения в конвейерах.

См. также

• Руководство разработчика по Python SDK — архитектура, асинхронная пакетная обработка и обработка отказов.
• Python CLI — извлечение из терминала и потоковая передача больших файлов.
• Сервер Python MCP — предоставление инструментов извлечения агентам искусственного интеллекта (AI).
• RFC 9110 (HTTP Semantics) и RFC 9457 (Problem Details for HTTP APIs) описывают семантику статусов и машиночитаемые тела ошибок, которые возвращает конечная точка Connect. Авторитетный текст см. в указателе RFC организации IETF.