Tables, Cells, and Ranges

This page explains the internal data model that ExcelTableKit uses to represent an Excel cell range, and shows how to interact with it directly.

Overview

ExcelTableKit models a styled region of an Excel worksheet as a Table object that owns two lists of Cell objects:

Header cells — created when define_header(rows=N) is called.
Body cells — all remaining cells in the range.

Most users never need to create Table or Cell objects directly; ExcelManager does that automatically. The classes are documented here for advanced use cases and for developers who want to extend the library.

Cell

A Cell represents a single Excel cell identified by a column letter (or letters) and a row number.

from exceltablekit import Cell

cell = Cell(column="B", row=3)
print(cell.get_cell())    # "B3"
print(cell.get_column())  # "B"
print(cell.get_row())     # 3

Constructor

Parameter	Type	Description
`column`	`str`	Excel column letter(s), case-insensitive (e.g. `"A"`, `"AA"`, `"XFD"`). Validated against the maximum column of 16 384.
`row`	`int`	1-based row number. Must be between 1 and 1 048 576 inclusive.

Raises InvalidColumnValueError or InvalidRowValueError if the values are out of range.

Applying a style to a single cell

from openpyxl import Workbook
from openpyxl.styles import PatternFill
from exceltablekit import Cell

wb = Workbook()
ws = wb.active

cell = Cell("C", 5)
fill = PatternFill(fill_type="solid", fgColor="FF0000")
cell.set_property(ws, "fill", fill)

wb.save("output.xlsx")

Table

A Table represents a rectangular range of cells. It is created with the four boundary values of the range and automatically instantiates all Cell objects inside it.

from openpyxl import Workbook
from exceltablekit import Table

wb = Workbook()
ws = wb.active

# Table from A1 to D3 — 4 columns × 3 rows = 12 cells
table = Table(
    worksheet=ws,
    first_column="A",
    first_row=1,
    last_column="D",
    last_row=3,
)

Constructor parameters

Parameter	Type	Description
`worksheet`	`Worksheet`	An openpyxl `Worksheet` object.
`first_column`	`str`	Top-left column letter(s).
`first_row`	`int`	Top-left row number.
`last_column`	`str`	Bottom-right column letter(s).
`last_row`	`int`	Bottom-right row number.

Defining headers

After creating the table, call set_header to split the body into header and body sections:

table.set_header(total_row_header=1)

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

Warning

Calling set_header a second time resets the split. The previous header cells are discarded and the table is rebuilt from scratch.

Applying styles

from openpyxl.styles import Font

bold_font = Font(bold=True, color="FFFFFF")

table.set_style_header("font", bold_font)  # header rows
table.set_style_body("font", Font(size=10))  # body rows

Retrieving cells by row

# Get all body cells in row 2
row_cells = table.get_cells_by_row(num_row=2)
for cell in row_cells:
    print(cell.get_cell())   # "A2", "B2", "C2", "D2"

Note

get_cells_by_row searches only body cells. After set_header, header cells are no longer in the body list and will not be returned.

Visualising the table in the terminal

Use display_cells() to print a grid of all cells (header + body) to standard output. This is useful for debugging:

table.display_cells()

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

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

Column and row limits

Excel imposes hard limits on the grid size. ExcelTableKit enforces the same limits on all cell and table construction:

Limit	Value	Notes
Maximum column	16 384 (`XFD`)	Enforced via `ColumnOutOfBoundsError`
Maximum row	1 048 576	Enforced via `InvalidRowValueError`

Column letter ↔ number conversion

The Alphabet utility class converts between Excel column letters and 1-based column numbers:

from exceltablekit.alphabet.alphabet import Alphabet

Alphabet.get_string_column_by_number(1)     # "A"
Alphabet.get_string_column_by_number(27)    # "AA"
Alphabet.get_string_column_by_number(16384) # "XFD"

Alphabet.get_number_column_by_string("A")   # 1
Alphabet.get_number_column_by_string("AA")  # 27
Alphabet.get_number_column_by_string("XFD") # 16384