Documentation

Python SDK: Worksheet: sheets and cells

document.sheet(0) returns the first sheet. Sheet indices are zero based, while row and column numbers start at one. Worksheet methods run locally.

Examples are fragments inside def run(ctx):. All SDK methods are synchronous; do not add await.

Obtaining the SDK object

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

Methods

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

No arguments.

Result: str.

The sheet's name in the original file.

result = sheet.name()

rows

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

No arguments.

Result: list[list[Any]].

All rows, without assuming where headers are. Empty rows and gaps are preserved. Array rows and columns use zero-based indexes.

result = sheet.rows()

row_count

sheet.row_count() -> int

No arguments.

Result: int.

The number of extracted rows, including empty ones. This is not a record count: a file can have headers, totals, and multiple sections.

result = sheet.row_count()

column_count

sheet.column_count() -> int

No arguments.

Result: int.

The width of the longest extracted row. Missing cells in shorter rows remain empty.

result = sheet.column_count()

cell

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

Argument	Type	Required	Purpose
`address`	`str`	Yes	Cell address, such as B2.
`resolve_merged`	`bool`	No, see the signature default	Read the merged-region anchor value.

Result: Any.

Reads a cell such as B2. With resolve_merged=True, it reads the top-left cell of a merged range. Use an address without $ markers.

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

row

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

Argument	Type	Required	Purpose
`number`	`int`	Yes	One-based row/page number.

Result: list[Any].

Read a row by its one-based number. Rows outside the sheet return an empty array; zero or negative numbers raise an error.

result = sheet.row(2)

column

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

Argument	Type	Required	Purpose
`column`	`int \| str`	Yes	Column letters or one-based number.
`start_row`	`int \| None`	No, see the signature default	First data row, one-based and inclusive.
`end_row`	`int \| None`	No, see the signature default	Last data row, one-based and inclusive.

Result: list[Any].

Read a column by letters or one-based number. start_row and end_row are inclusive. Missing values stay None.

result = sheet.column('B')

range

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

Argument	Type	Required	Purpose
`value`	`Any`	Yes	Method-specific value; see its result description.
`resolve_merged`	`bool`	No, see the signature default	Read the merged-region anchor value.

Result: list[list[Any]].

Read a rectangular matrix such as A1:C10, including empty cells. The limit is 50,000 cells. resolve_merged=True repeats the merged area's anchor value only in the returned matrix. Reversed or invalid ranges raise an error.

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

non_empty_rows

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

No arguments.

Result: dict[int, list[Any]].

Non-empty rows keyed by their original one-based row numbers. Values 0 and False count as data.

result = sheet.non_empty_rows()

find

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

Argument	Type	Required	Purpose
`text`	`str`	Yes	Text to parse, search, or type.
`exact`	`bool`	No, see the signature default	Require an exact match.
`limit`	`int`	No, see the signature default	Maximum match count, 1–1000.

Result: list[dict[str, Any]].

Search values without regard to case. exact=True requires a whole-value match. Returns address and value, at most limit matches (1–1000). Formula expressions are not executed or searched in place of their values.

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

find_header

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

Argument	Type	Required	Purpose
`labels`	`list[str]`	Yes	Expected column labels.
`max_rows`	`int`	No, see the signature default	Header search depth, 1–5000 rows.

Result: int | None.

Find the first row containing all requested labels. Comparison ignores case and surrounding spaces. The first 50 rows are checked by default; max_rows can be 1–5,000. Returns None if no header is found. Use explicit ranges for a multi-level header.

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

merged

sheet.merged() -> list[str]

No arguments.

Result: list[str].

Merged XLSX/XLS ranges, such as A1:C1. Values in other cells are not duplicated by default. CSV files have no merged cells.

result = sheet.merged()

formula

sheet.formula(address) -> str | None

Argument	Type	Required	Purpose
`address`	`str`	Yes	Cell address, such as B2.

Result: str | None.

The original XLSX formula with a leading =, or None. Read the calculated value with cell() and the expression with formula(). Shared formulas in dependent cells may not contain the full expression; consult the cached value when needed.

result = sheet.formula('B2')

error

sheet.error(address) -> str | None

Argument	Type	Required	Purpose
`address`	`str`	Yes	Cell address, such as B2.

Result: str | None.

The stored XLSX error, such as #DIV/0!, or None. Errors are not silently replaced with zero.

result = sheet.error('B2')

records

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

Argument	Type	Required	Purpose
`header_row`	`int`	No, see the signature default	One-based header row; 0 uses column letters.
`start_row`	`int \| None`	No, see the signature default	First data row, one-based and inclusive.
`end_row`	`int \| None`	No, see the signature default	Last data row, one-based and inclusive.

Result: list[dict[str, Any]].

Turn a selected section into records. header_row is the one-based header row; start_row and end_row set an inclusive data range. header_row=0 uses column letters A, B, C as keys. Empty rows are skipped. Blank labels become column letters, and duplicate labels get _2, _3, and so on without losing fields. Totals and notes are not detected automatically; set the range explicitly.

result = sheet.records(1)

structure

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

No arguments.

Result: dict[str, Any].

An anonymized layout for AI planning: rows, columns, merged, and a sample of the first 24×16 cells. The sample contains only e (empty), s (string), n (number), and b (Boolean). Sheet names, headers, values, links, and formulas are omitted. This method does not call a model.

result = sheet.structure()

calculation

sheet.calculation(address) -> str

Argument	Type	Required	Purpose
`address`	`str`	Yes	Cell address, such as B2.

Result: str.

XLSX calculation status: calculated, unsupported, external_reference, circular_reference, error, or limit. not_calculated means a formula exists but was not recalculated; not_formula means this is a regular cell. Unsupported formulas give an explicit error, not zero or an undisclosed fallback to an old value.

result = sheet.calculation('B2')

cached_value

sheet.cached_value(address) -> Any

Argument	Type	Required	Purpose
`address`	`str`	Yes	Cell address, such as B2.

Result: Any.

The value saved in an XLSX file by its author before recalculation. It may be missing or stale. For a regular cell it matches cell(). Use it only as an explicit fallback; the SDK returns recalculated values by default.

result = sheet.cached_value('B2')

Errors and execution context

All calls are synchronous. Invalid arguments or malformed source data can raise ValueError/TypeError; a platform refusal or unavailable service raises RuntimeError. Missing elements/values return None or an empty collection only where explicitly documented. Do not convert every exception into an empty successful result. External-service methods are unavailable in export transformations; see transformation limits and environment.