Python SDK: Worksheet: листы и ячейки

document.sheet(0) возвращает первый лист; выбор листа начинается с нуля, номера строк и столбцов: с единицы. Методы листа работают локально.

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

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

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

Методы

• name()
• rows()
• row_count()
• column_count()
• cell()
• row()
• column()
• range()
• non_empty_rows()
• find()
• find_header()
• merged()
• formula()
• error()
• records()
• structure()
• calculation()
• cached_value()

name

sheet.name() -> str

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

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

Имя листа в исходном файле.

result = sheet.name()

rows

sheet.rows() -> list[list[Any]]

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

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

Все строки без предположений о заголовках. Пустые строки и промежутки сохраняются. Строки и столбцы массива индексируются с нуля.

result = sheet.rows()

row_count

sheet.row_count() -> int

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

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

Количество извлечённых строк, включая пустые. Это не число записей: у файла могут быть заголовки, итоги и несколько секций.

result = sheet.row_count()

column_count

sheet.column_count() -> int

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

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

Ширина самой длинной извлечённой строки. У неполных строк недостающие ячейки остаются пустыми.

result = sheet.column_count()

cell

sheet.cell(address, resolve_merged=False) -> Any

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

Читает ячейку по адресу вроде B2. При resolve_merged=True берёт значение верхней левой ячейки объединённой области. Допустимы адреса B2 и абсолютные маркеры $B$2; они читают ту же ячейку.

result = sheet.cell('B2', True)

row

sheet.row(number) -> list[Any]

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

Строка по номеру с единицы. За пределами листа возвращает пустой массив; нулевой и отрицательный номер вызывают ошибку.

result = sheet.row(2)

column

sheet.column(column, start_row=1, end_row=None) -> list[Any]

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

Столбец по буквам или номеру с единицы. start_row и end_row включительны. Пропущенные значения сохраняются как None.

result = sheet.column('B')

range

sheet.range(value, resolve_merged=False) -> list[list[Any]]

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

Прямоугольная матрица A1:C10, включая пустоты. До 50 000 ячеек. resolve_merged=True размножает значение якоря объединения только в возвращаемом массиве. Обратные и неверные диапазоны вызывают ошибку.

result = sheet.range('A1:B5')

non_empty_rows

sheet.non_empty_rows() -> dict[int, list[Any]]

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

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

Непустые строки с исходными номерами в ключах с единицы. Значения 0 и False считаются данными, а не пустотой.

result = sheet.non_empty_rows()

find

sheet.find(text, exact=False, limit=100) -> list[dict[str, Any]]

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

Поиск по значениям без учёта регистра. exact=True требует полного совпадения. Возвращает address и value, максимум limit совпадений (1–1000). Формулы не исполняются и не участвуют в поиске вместо значений.

result = sheet.find('A-1', False, 100)

find_header

sheet.find_header(labels, max_rows=50) -> int | None

Результат: int | None.

Находит первую строку, в которой есть все перечисленные подписи. Сравнение без учёта регистра и пробелов по краям. По умолчанию проверяет первые 50 строк; max_rows от 1 до 5000. Если шапка не найдена, возвращает None. Для многоуровневой шапки используйте явные диапазоны.

result = sheet.find_header(['SKU', 'Price'], 50)

merged

sheet.merged() -> list[str]

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

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

Список объединений XLSX/XLS вида A1:C1. Значения остальных ячеек по умолчанию не дублируются. В CSV объединений нет.

result = sheet.merged()

formula

sheet.formula(address) -> str | None

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

Исходный текст формулы XLSX с ведущим = или None. Расчётное значение читается через cell(), исходное выражение через formula(). Общие формулы зависимых ячеек могут не содержать полный текст: ориентируйтесь на сохранённое значение.

result = sheet.formula('B2')

error

sheet.error(address) -> str | None

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

Сохранённая ошибка XLSX, например #DIV/0!, либо None. Не подменяет ошибку нулём.

result = sheet.error('B2')

records

sheet.records(header_row=1, start_row=None, end_row=None) -> list[dict[str, Any]]

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

Превращает выбранную секцию в записи. header_row задаёт шапку с единицы, start_row/end_row задают включительный диапазон данных. header_row=0 использует буквенные ключи A, B, C. Пустые строки пропускаются. Пустые подписи заменяются буквами, дубликаты получают суффиксы _2, _3 без потери полей. Итоги и примечания не распознаются автоматически: ограничьте диапазон явно.

result = sheet.records(1)

structure

sheet.structure() -> dict[str, Any]

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

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

Обезличенная структура для AI-плана: rows, columns, merged и sample первых 24×16 ячеек. sample содержит только e (пусто), s (строка), n (число), b (логическое). Имена листов, заголовки, значения, ссылки и формулы отсутствуют. Сам метод не вызывает модель.

result = sheet.structure()

calculation

sheet.calculation(address) -> str

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

Статус пересчёта XLSX: calculated, unsupported, external_reference, circular_reference, error или limit. not_calculated означает, что формула есть, но пересчёт не проводился; not_formula означает обычную ячейку. Неподдерживаемые формулы дают явную ошибку, не ноль и не скрытую подмену старым значением.

result = sheet.calculation('B2')

cached_value

sheet.cached_value(address) -> Any

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

Значение, которое автор XLSX сохранил в файле до пересчёта. Оно может отсутствовать или устареть. Для обычной ячейки совпадает с cell(). Используйте только как явно выбранный резерв: по умолчанию SDK возвращает пересчитанные значения.

result = sheet.cached_value('B2')

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

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