Table

class exceltablekit.table.table.Table(worksheet, first_column, first_row, last_column, last_row)[source]

Represents a rectangular range of cells in an Excel worksheet. The range is modelled as two lists of Cell objects: header cells and body cells.

Table objects are created internally by ExcelManager when you call set_table(). You rarely need to instantiate this class directly.

Parameters:

worksheet (openpyxl.worksheet.worksheet.Worksheet) – The openpyxl Worksheet that owns this table.
first_column (str) – Top-left column letter(s) (e.g. "A").
first_row (int) – Top-left row number.
last_column (str) – Bottom-right column letter(s) (e.g. "D").
last_row (int) – Bottom-right row number.

Raises:

InvalidColumnValueError – If a column letter is invalid or exceeds XFD.
InvalidRowValueError – If a row number is ≤ 0 or exceeds 1 048 576.

On construction, all Cell objects for the range are created and stored in _body. Column iteration is inner (A → D), row iteration is outer (1 → N).

Example:

from openpyxl import Workbook
from exceltablekit import Table

wb = Workbook()
ws = wb.active

table = Table(ws, "A", 1, "D", 3)  # 4 cols × 3 rows = 12 cells
print(len(table.get_body()))        # 12

Header setup

set_header(total_row_header)[source]

Split the cell range into header and body sections.

The first total_row_header rows of the current body list are moved into the header list. The remaining rows form the new body list.

Parameters:: total_row_header (int) – Number of rows to designate as headers.

Example:

table.set_header(1)
print(len(table.get_header()))  # 4  (row 1, columns A–D)
print(len(table.get_body()))    # 8  (rows 2–3)

Style application

set_style_header(property, value)[source]

Apply a style property to all header cells.

Parameters:

property (str) – Cell attribute name (e.g. "fill", "font").
value – The openpyxl style object to assign.

set_style_body(property, value)[source]

Apply a style property to all body cells.

Parameters:

property (str) – Cell attribute name.
value – The openpyxl style object to assign.

Accessors

get_body()[source]

Return the list of body cells.

Returns:: All non-header cells in the table.
Return type:: list[Cell]

get_header()[source]

Return the list of header cells.

Returns:: Header cells, or an empty list if set_header() has not been called.
Return type:: list[Cell]

get_first_column()[source]

Return the first column letter.

Returns:: Top-left column string (e.g. "A").
Return type:: str

get_first_row()[source]

Return the first row number.

Returns:: Top-left row integer.
Return type:: int

get_total_row_headers()[source]

Return the number of header rows.

Returns:: 0 if set_header() has not been called.
Return type:: int

get_cells_by_row(num_row)[source]

Return all body cells in a given row number.

Parameters:: num_row (int) – The absolute row number to look up (1-based).
Returns:: All body cells whose row equals num_row.
Return type:: list[Cell]
Raises:: ValueError – If num_row exceeds the table’s last row.

Note

Only body cells are searched. After set_header(), header cells are no longer in the body list and will not be returned.

Example:

table = Table(ws, "A", 1, "D", 3)
table.set_header(1)
cells = table.get_cells_by_row(2)
# Returns [Cell("A",2), Cell("B",2), Cell("C",2), Cell("D",2)]

Display

display_cells()[source]

Print a tabulate grid of all cells (header + body) to standard output, organised by row. Useful for debugging.

Example output for a 4 × 3 table with 1 header row:

┌──────┬──────┬──────┬──────┐
│ A1   │ B1   │ C1   │ D1   │
├──────┼──────┼──────┼──────┤
│ A2   │ B2   │ C2   │ D2   │
│ A3   │ B3   │ C3   │ D3   │
└──────┴──────┴──────┴──────┘