Python SDK: Document: текст и таблицы

Document содержит результат разбора файла. Перед обработкой всех данных проверьте complete() и warnings(). Методы ниже работают локально.

Примеры являются фрагментами тела def run(ctx):. Все методы SDK синхронны, await не нужен.

Как получить объект

document = ctx.documents().from_bytes('sku,price\nA-1,1250', 'report.csv')

Методы

• text()
• format()
• tables()
• rows()
• pages()
• links()
• complete()
• warnings()
• sheet_names()
• sheet()
• page()
• matches()
• chunks()
• blocks()

text

document.text() -> str

Аргументы не нужны.

Результат: str.

Текст документа, включая доступные колонтитулы и примечания Office. В PDF сохраняется разбиение текста по страницам. Структура и форматирование DOCX дополнительно доступны через blocks().

result = document.text()

format

document.format() -> str

Аргументы не нужны.

Результат: str.

Определённый формат: например xlsx, docx, pdf или csv.

result = document.format()

tables

document.tables() -> list[dict[str, Any]]

Аргументы не нужны.

Результат: list[dict[str, Any]].

Листы Excel или таблицы Word: массив объектов name, rows. Числа Excel остаются числами. Поддерживаемые формулы XLSX пересчитываются локально через xlcalculator. Внешние ссылки и макросы не выполняются. rows() и cell() возвращают результат, formula() исходное выражение, cached_value() сохранённое автором значение. Ошибки доступны через error()/calculation().

result = document.tables()

rows

document.rows(sheet=0) -> list[list[Any]]

Результат: list[list[Any]].

Возвращает строки выбранного листа по индексу или имени. Если листа нет, возвращает пустой массив. Для PDF читайте pages() или text().

result = document.rows()

pages

document.pages() -> list[dict[str, Any]]

Аргументы не нужны.

Результат: list[dict[str, Any]].

Страницы PDF: number, text, ocr. Сканированные страницы распознаются локально на русском и английском. Не более пяти страниц с изображениями и 100 текстовых страниц за один разбор.

result = document.pages()

links

document.links() -> list[str]

Аргументы не нужны.

Результат: list[str].

Найденные ссылки. Обработчик не переходит по ним и не загружает внешние изображения. При необходимости выберите допустимую ссылку явно через сетевой SDK.

result = document.links()

complete

document.complete() -> bool

Аргументы не нужны.

Результат: bool.

False, если достигнут предел извлечения. Перед сохранением полного отчёта проверьте этот признак. Предел таблиц: 20 листов/таблиц, 5000 строк, 100 столбцов, 50 000 ячеек суммарно; текст до 1 MiB.

result = document.complete()

warnings

document.warnings() -> list[str]

Аргументы не нужны.

Результат: list[str].

Коды особенностей разбора: сохранённые значения формул, старый формат Office, изображения внутри Word/Excel, предел OCR. Для старых DOC/XLS доступно ограниченное извлечение, встроенные объекты не исполняются.

result = document.warnings()

sheet_names

document.sheet_names() -> list[str]

Аргументы не нужны.

Результат: list[str].

Названия извлечённых листов/таблиц в исходном порядке. Для PDF и изображений список пустой.

result = document.sheet_names()

sheet

document.sheet(sheet=0) -> Worksheet

Результат: Worksheet. Объект SDK: используйте его методы, не передавайте целиком в emit.

Лист по индексу с нуля или точному имени. Возвращает Worksheet. При отсутствии листа вызывает понятную ошибку; rows() сохраняет прежнее поведение с пустым массивом. Методы листа работают локально без повторного чтения файла.

result = document.sheet()

page

document.page(number) -> str

Результат: str.

Текст страницы PDF или растрового изображения по номеру с единицы. Отсутствующая страница даёт пустую строку, неправильный номер вызывает ошибку. Для Word используйте text().

result = document.page(2)

matches

document.matches(expression, limit=100) -> list[list[str]]

Результат: list[list[str]].

Ищет совпадения регулярного выражения Python в тексте документа. Возвращает массив совпадений с захваченными группами; не использует синтаксис PCRE.

result = document.matches(r'(\d+)', 100)

chunks

document.chunks(characters=4000, overlap=200) -> list[str]

Результат: list[str].

Фрагменты текста в символах Unicode. characters от 100 до 16000, overlap от 0 до characters−1. Метод не отправляет фрагменты во внешние сервисы. Нельзя передавать приватные фрагменты в analyze/transform без отдельной политики обработки.

result = document.chunks()

blocks

document.blocks() -> list[dict[str, Any]]

Аргументы не нужны.

Результат: list[dict[str, Any]].

Абзацы и ссылки на таблицы DOCX в порядке исходного документа. Абзац содержит kind=paragraph, level заголовка, align, indent, before, after, marker, depth и runs. У каждого фрагмента runs есть text, bold, italic, underline, size в пунктах. Блок kind=table содержит индекс table в tables(). Для остальных форматов возвращает пустой массив. Значения не отправляются во внешнюю модель.

result = document.blocks()

Ошибки и контекст выполнения

Все вызовы синхронны. Неверный аргумент или формат данных может вызвать ValueError/TypeError; отказ платформы или недоступность сервиса вызывает RuntimeError. Отсутствие элемента/значения даёт None либо пустой список только там, где это явно описано. Не превращайте любое исключение в пустой успешный результат. Методы внешних сервисов недоступны в преобразовании выгрузки; см. ограничения преобразований и среду.