Documentation

Python SDK: SheetCoordinates: cell addresses

ctx.documents().coordinates() converts spreadsheet addresses and numeric indices. These methods run locally.

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

Methods

column_name()
column_number()
position()
bounds()

column_name

ctx.documents().coordinates().column_name(number) -> str

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

Result: str.

Convert a positive column number to letters: 1 → A, 27 → AA.

result = ctx.documents().coordinates().column_name(27)

column_number

ctx.documents().coordinates().column_number(name) -> int

Argument	Type	Required	Purpose
`name`	`str`	Yes	Field, header, file, credential, or metric name, depending on the method.

Result: int.

Convert column letters to a one-based number. Pass only Latin column letters, such as B or AA.

result = ctx.documents().coordinates().column_number('AA')

position

ctx.documents().coordinates().position(address) -> tuple[int, int]

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

Result: tuple[int, int].

Converts an address such as B2 to [2, 2]. Absolute $ markers are accepted: $B$2 resolves to the same position.

result = ctx.documents().coordinates().position('B2')

bounds

ctx.documents().coordinates().bounds(value) -> list[int]

Argument	Type	Required	Purpose
`value`	`Any`	Yes	Method-specific value; see its result description.

Result: list[int].

Returns a flat list [start_row, start_column, end_row, end_column]. A1:B3 gives [1, 1, 3, 2]. A single cell is a valid range; reversed bounds raise ValueError.

result = ctx.documents().coordinates().bounds('A1:B3')

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.