Tab

class Tab

Extends gspread’s Worksheet with async helpers.

Obtain a Tab via get_tab() or tabs().

Reading

async Tab.values(**kwargs) → list[Row]

Returns every row in the sheet as a list of Row objects.

rows = await tab.values()
for row in rows:
    print(row)
async Tab.get_row(serial_no) → Row

Returns the row at the given 1-based index.

Parameters:

serial_no (int) – 1-based row index.

Returns:

The requested row.

Return type:

Row

first_row = await tab.get_row(1)
async Tab.get_cell(cell_name, render_option='formatted') → Cell

Fetches a single cell by its A1 address. Both single-letter (B3) and multi-letter (AA10) column labels are supported.

Parameters:

  • cell_name (str) – A1-notation address, e.g. "B3" or "AA10".

  • render_option (str) – "formatted" (default), "unformatted", or "formula".

Returns:

The requested cell.

Return type:

Cell

cell    = await tab.get_cell("B2")
formula = await tab.get_cell("C1", render_option="formula")

Writing

async Tab.append(data, get_row=False) → Row | None

Appends a new row at the bottom of the sheet.

Parameters:

  • data (list) – A flat list of values to write.

  • get_row (bool) – When True, returns the appended Row.

Returns:

The appended row when get_row=True, otherwise None.

Return type:

Row | None

await tab.append(["Alice", "30", "Engineer"])

# Get the appended row back
row = await tab.append(["Bob", "25"], get_row=True)
async Tab.del_row(start, end=None)

Deletes one or more rows by their 1-based indices.

Parameters:

  • start (int) – 1-based index of the first row to delete.

  • end (int | None) – 1-based index of the last row to delete (inclusive). Defaults to start.

await tab.del_row(3)           # delete row 3
await tab.del_row(3, end=5)    # delete rows 3, 4, and 5
async Tab.del_cell(start, end=None, shift='up')

Deletes a cell or a rectangular range, shifting the remaining cells.

Parameters:

  • start (str) – Top-left cell address, e.g. "B2".

  • end (str | None) – Bottom-right cell address for a range. Defaults to start.

  • shift (str) – "up" (default) shifts rows up; "left" shifts columns left.

await tab.del_cell("B2")                # single cell, shift up
await tab.del_cell("B2", shift="left")  # single cell, shift left
await tab.del_cell("A1", "C3")          # delete a 3×3 range