ExcelStyle

ExcelStyle is the high-level styling façade of ExcelTableKit. It wraps openpyxl style objects (PatternFill, Border, Side, Font, Alignment) so you never have to construct them yourself.

Every method in ExcelStyle accepts plain Python values (hex strings, booleans, floats) and internally converts them to the correct openpyxl objects before delegating to ExcelManager.

Creating an ExcelStyle instance

ExcelStyle wraps an existing ExcelManager:

from exceltablekit import ExcelManager, ExcelStyle

excel = ExcelManager("output.xlsx")
excel.set_table("A1", "D10")
excel.define_header(rows=1)

style = ExcelStyle(excel)

Important

Call set_table (and optionally define_header) on the manager before creating the style instance, or before calling any style method. The style object does not keep its own copy of the table — it reads through the manager on every call.

Body styling

The following methods apply styles to the body rows of the table (all rows that are not headers).

set_background

Applies a solid background fill colour to all body cells.

style.set_background("E8F4FD")   # light blue
style.set_background("FFFACD")   # lemon chiffon
style.set_background("FFFFFF")   # white

Parameter	Type	Description
hex_color	str	6-character RGB hex string without the leading # (e.g. "E8F4FD").

set_font

Applies a font style to all body cells.

style.set_font(
    type="Calibri",
    size=11.0,
    bold=False,
    italic=False,
    hex_color="000000",
)

Parameter	Type	Default	Description
type	str	"Time New Roman"	Font family name.
size	float	10.0	Font size in points.
bold	bool	False	Bold text.
italic	bool	False	Italic text.
hex_color	str	"FFFF0000"	6- or 8-character ARGB hex string for the font colour. The leading FF is the alpha channel (fully opaque).

Note

openpyxl uses ARGB colour values for fonts (8 hex digits). If you supply a 6-digit value, omit the alpha prefix — openpyxl will apply it as-is. Use "FF000000" for opaque black or just "000000" depending on the openpyxl version in use.

set_alignment

Applies cell text alignment to all body cells.

style.set_alignment(
    horizontal="center",
    vertical="center",
    wrap_text=True,
)

Parameter	Type	Default	Description
horizontal	str	"left"	Horizontal alignment. One of: "left", "center", "right", "fill", "justify", "centerContinuous", "distributed".
vertical	str	"center"	Vertical alignment. One of: "top", "center", "bottom", "justify", "distributed".
wrap_text	bool	False	Wrap long text within the cell.

set_border

Applies a border to all body cells. Each of the four edges (left, right, top, bottom) can be enabled or disabled independently and given its own border style.

# All four edges, thin black border (defaults)
style.set_border()

# Custom: only left and right edges, medium style, grey colour
style.set_border(
    left=True, left_style="medium",
    right=True, right_style="medium",
    top=False,
    bottom=False,
    hex_color="888888",
)

Parameter	Type	Default	Description
left	bool	True	Enable left edge border.
left_style	BorderStyle	"thin"	Style for the left edge.
right	bool	True	Enable right edge border.
right_style	BorderStyle	"thin"	Style for the right edge.
top	bool	True	Enable top edge border.
top_style	BorderStyle	"thin"	Style for the top edge.
bottom	bool	True	Enable bottom edge border.
bottom_style	BorderStyle	"thin"	Style for the bottom edge.
hex_color	str	"000000"	Border colour as a 6-character hex string.

See Available border styles for the full list of accepted BorderStyle values.

Header styling

Every body method has a set_header_* counterpart that targets header rows only. Their signatures are identical to their body equivalents.

define_header must have been called on the manager before these methods are used, otherwise HeaderTableNotDefinedError is raised.

set_header_background

style.set_header_background("1F4E79")   # dark blue
style.set_header_background("2E75B6")   # medium blue

set_header_font

style.set_header_font(
    type="Calibri",
    size=12.0,
    bold=True,
    hex_color="FFFFFF",   # white text
)

set_header_alignment

style.set_header_alignment(
    horizontal="center",
    vertical="center",
)

set_header_border

style.set_header_border(bottom_style="medium")   # emphasise the header bottom

freeze_header

Freezes the worksheet pane immediately below the last header row.

excel.set_table("A1", "D20")
excel.define_header(rows=2)

style = ExcelStyle(excel)
style.freeze_header()
# Freeze pane is set at A3

The freeze cell is {first_column}{first_row + total_header_rows}. For a table starting at B3 with 1 header row the freeze pane is B4.

Column auto-fit

auto_fit_columns

Adjusts each column’s width to fit the longest cell value in that column (plus 2 characters of padding).

style.auto_fit_columns()

This iterates over all cells (header + body) so even header text influences the final width.

Available border styles

The BorderStyle type is a Literal union of the following 13 values:

Value	Visual result
"thin"	Thin solid line (default)
"medium"	Medium-weight solid line
"thick"	Thick solid line
"double"	Double solid line
"hair"	Hairline (thinnest possible)
"dashed"	Short dashes
"dotted"	Dots
"dashDot"	Alternating dash–dot
"dashDotDot"	Alternating dash–dot–dot
"mediumDashed"	Medium-weight dashes
"mediumDashDot"	Medium-weight dash–dot
"mediumDashDotDot"	Medium-weight dash–dot–dot
"slantDashDot"	Slanted dash–dot

Error handling

Error	When it is raised
TableNotDefinedError	set_table was not called before a body or table style method
HeaderTableNotDefinedError	define_header was not called before a header style method
TableBackgroundError	Background fill failed on the body
TableFontError	Font style failed on the body
TableAlignmentError	Alignment failed on the body
TableBorderError	Border failed on the body
HeaderTableBackgroundError	Background fill failed on the header
HeaderTableFontError	Font style failed on the header
HeaderTableAlignmentError	Alignment failed on the header
HeaderTableBorderError	Border failed on the header
HeaderTableFreezeError	Freeze panes failed
TableColumnWidthError	Auto-fit column widths failed