TableWidget API¶

`TableWidget(widget_id=None)` ¶

Bases: BaseWidget

Create a widget for displaying table data in emails.

This widget provides a flexible way to present structured data, whether manually constructing tables or directly importing data from pandas.DataFrame. It supports various styling options, such as striped patterns, borders, hover effects, and can apply colors and status to specific cells to enhance data readability and visual appeal.

Core features

Diverse data sources: Support for directly adding row data or importing from pandas.DataFrame.
Style customization: Can set title, headers, striped patterns, borders, hover effects, etc.
Cell styling: Allows setting colors, bold, and alignment for individual cells, and supports status coloring.
Email compatibility: Generated HTML is optimized for mainstream email clients to ensure consistent display.

Attributes:

Name	Type	Description
`title`	`Optional[str]`	Title of the table.
`headers`	`List[str]`	List of table column headers.
`rows`	`List[List[Union[str, TableCell]]]`	Table row data, each row contains strings or `TableCell` objects.
`show_index`	`bool`	Whether to display row indices.
`striped`	`bool`	Whether to enable striped pattern styling.
`bordered`	`bool`	Whether to display borders for all cells.
`hover_effect`	`bool`	Whether to enable mouse hover highlighting effect.

Examples:

Manually create a table with status cells:

Python

from email_widget.widgets import TableWidget, TableCell
from email_widget.core.enums import StatusType

project_status_table = (TableWidget()                                .set_title("Project Progress Overview")                                .set_headers(["Project Name", "Owner", "Progress", "Status"])                                .add_row(["Website Redesign", "Alice", "85%",
                                  TableCell("In Progress", status=StatusType.INFO)])                                .add_row(["Mobile App Dev", "Bob", "100%",
                                  TableCell("Completed", status=StatusType.SUCCESS)])                                .add_row(["Backend Optimization", "Charlie", "60%",
                                  TableCell("At Risk", status=StatusType.WARNING)])                                .set_striped(True)                                .set_bordered(True))

# Assuming email is an Email object
# email.add_widget(project_status_table)

Create a table from pandas.DataFrame:

Python

import pandas as pd

data = {
    'Product': ['Laptop', 'Mouse', 'Keyboard'],
    'Sales': [1200, 300, 500],
    'Region': ['North', 'South', 'East']
}
df = pd.DataFrame(data)

sales_table = (TableWidget()                       .set_dataframe(df)                       .set_title("Product Sales Data")                       .show_index(False) # Don't display index
               .set_hover_effect(True))

Initialize TableWidget instance.

Parameters:

Name	Type	Description	Default
`widget_id`	`Optional[str]`	Optional Widget ID.	`None`

Examples:

Python Console Session

>>> table = TableWidget()
>>> table_with_id = TableWidget("my-table")

Attributes¶

`dataframe` `property` ¶

Get DataFrame data.

Returns:

Type	Description
`Optional[DataFrame]`	Optional[pd.DataFrame]: DataFrame object or None.

`headers` `property` ¶

Get header list.

Returns:

Type	Description
`list[str]`	List[str]: Header list.

`rows` `property` ¶

Get row data.

Returns:

Type	Description
`list[list[str \| TableCell]]`	List[List[Union[str, TableCell]]]: Row data list.

`title` `property` ¶

Get table title.

Returns:

Type	Description
`str \| None`	Optional[str]: Title or None.

Functions¶

`add_colored_cell(value, color, bold=False, align='center')` ¶

Create colored cell.

This helper method is used to quickly create a TableCell object with custom color, font weight, and alignment.

Parameters:

Name	Type	Description	Default
`value`	`str`	Value displayed in the cell.	required
`color`	`str`	Color of the cell text (CSS color value).	required
`bold`	`bool`	Whether to bold, defaults to False.	`False`
`align`	`str`	Alignment method, defaults to "center".	`'center'`

Returns:

Name	Type	Description
`TableCell`	`TableCell`	A configured `TableCell` object.

Examples:

Python Console Session

>>> cell = table.add_colored_cell("Important", "#ff0000", bold=True)

`add_data_row(row_data)` ¶

Add data row (based on DataFrame).

This method is used to add a row of data to the table. If the table has been initialized through set_dataframe, the new row will be added to the existing DataFrame; otherwise, a new DataFrame will be created.

Parameters:

Name	Type	Description	Default
`row_data`	`list`	List containing row data. The length of the list should match the number of headers.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Raises:

Type	Description
`ImportError`	If pandas library is not installed.

Examples:

Python Console Session

>>> table = TableWidget().add_data_row(["New Project", "0%", "Started"])

`add_row(row)` ¶

Add row data.

Parameters:

Name	Type	Description	Default
`row`	`List[Union[str, TableCell]]`	Row data, can be strings or TableCell objects.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().add_row(["Project A", "80%", TableCell("In Progress", status=StatusType.INFO)])

`add_status_cell(value, status)` ¶

Create status cell.

This helper method is used to quickly create a TableCell object with a specific status (such as success, warning, error). Status cells automatically apply predefined color and background styles.

Parameters:

Name	Type	Description	Default
`value`	`str`	Value displayed in the cell.	required
`status`	`StatusType`	Status type of the cell.	required

Returns:

Name	Type	Description
`TableCell`	`TableCell`	A configured `TableCell` object.

Examples:

Python Console Session

>>> cell = table.add_status_cell("Success", StatusType.SUCCESS)

`clear_data()` ¶

Clear table data.

This method will clear all data added through set_dataframe or add_data_row, and reset the internal DataFrame and row data list.

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().clear_data()

`clear_rows()` ¶

Clear row data.

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().clear_rows()

`get_template_context()` ¶

Get template context data required for rendering

`set_border_color(color)` ¶

Set border color.

Parameters:

Name	Type	Description	Default
`color`	`str`	CSS color value.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_border_color("#ddd")

`set_bordered(bordered=True)` ¶

Set whether to display borders.

Parameters:

Name	Type	Description	Default
`bordered`	`bool`	Whether to display borders, defaults to True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_bordered(False)

`set_column_width(column, width)` ¶

Set column width

`set_dataframe(df)` ¶

Set DataFrame data.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	pandas DataFrame object.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Raises:

Type	Description
`ImportError`	If pandas library is not installed.

Examples:

Python

import pandas as pd
df = pd.DataFrame({'Name': ['Project A', 'Project B'], 'Status': ['Completed', 'In Progress']})
table = TableWidget().set_dataframe(df)

`set_header_bg_color(color)` ¶

Set header background color.

Parameters:

Name	Type	Description	Default
`color`	`str`	CSS color value.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_header_bg_color("#4CAF50")

`set_headers(headers)` ¶

Set table headers.

Parameters:

Name	Type	Description	Default
`headers`	`List[str]`	Header list.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_headers(["Project Name", "Progress", "Status"])

`set_hover_effect(hover=True)` ¶

Set whether to enable hover effect.

Parameters:

Name	Type	Description	Default
`hover`	`bool`	Whether to enable hover effect, defaults to True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_hover_effect(False)

`set_max_width(width)` ¶

Set maximum width.

Parameters:

Name	Type	Description	Default
`width`	`str`	CSS width value.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_max_width("800px")

`set_rows(rows)` ¶

Set all row data.

Parameters:

Name	Type	Description	Default
`rows`	`List[List[Union[str, TableCell]]]`	Row data list.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python

rows = [
    ["Project A", "80%", TableCell("In Progress", status=StatusType.INFO)],
    ["Project B", "100%", TableCell("Completed", status=StatusType.SUCCESS)]
]
table = TableWidget().set_rows(rows)

`set_striped(striped=True)` ¶

Set whether to use striped pattern.

Parameters:

Name	Type	Description	Default
`striped`	`bool`	Whether to use striped pattern, defaults to True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_striped(False)

`set_title(title)` ¶

Set table title.

Parameters:

Name	Type	Description	Default
`title`	`str`	Table title.	required

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().set_title("Project Progress Table")

`show_index(show=True)` ¶

Set whether to display index.

Parameters:

Name	Type	Description	Default
`show`	`bool`	Whether to display index, defaults to True.	`True`

Returns:

Name	Type	Description
`TableWidget`	`TableWidget`	Returns self to support method chaining.

Examples:

Python Console Session

>>> table = TableWidget().show_index(False)

`TableCell(value, status=None, color=None, bold=False, align='center')` ¶

Table cell class.

Used to encapsulate data and style information for individual cells in a table, supporting setting cell values, status, color, font weight, and alignment. This allows tables to display richer, more expressive data.

Attributes:

Name	Type	Description
`value`	`Any`	The actual value of the cell, can be any type, will be converted to string for display.
`status`	`Optional[StatusType]`	Status type of the cell, used to apply predefined colors and backgrounds.
`color`	`Optional[str]`	Custom color for cell text (CSS color value).
`bold`	`bool`	Whether cell text is bold.
`align`	`str`	Text alignment of the cell (e.g., "left", "center", "right").

Examples:

Python

from email_widget.widgets import TableCell
from email_widget.core.enums import StatusType

# Create a success status cell
success_cell = TableCell("Success", status=StatusType.SUCCESS, bold=True)

# Create a custom color cell
red_text_cell = TableCell("Warning", color="#FF0000", align="right")

Initialize table cell.

Parameters:

Name	Type	Description	Default
`value`	`Any`	Cell value.	required
`status`	`Optional[StatusType]`	Status type, used to apply predefined colors and backgrounds.	`None`
`color`	`Optional[str]`	Text color (CSS color value).	`None`
`bold`	`bool`	Whether to bold, defaults to False.	`False`
`align`	`str`	Alignment method, defaults to "center".	`'center'`

Examples:

Python Console Session

>>> cell = TableCell("Success", status=StatusType.SUCCESS, bold=True)

TableWidget API¶

TableWidget(widget_id=None) ¶

Attributes¶

dataframe property ¶

headers property ¶

rows property ¶

title property ¶

Functions¶

add_colored_cell(value, color, bold=False, align='center') ¶

add_data_row(row_data) ¶

add_row(row) ¶

add_status_cell(value, status) ¶

clear_data() ¶

clear_rows() ¶

get_template_context() ¶

set_border_color(color) ¶

set_bordered(bordered=True) ¶

set_column_width(column, width) ¶

set_dataframe(df) ¶

set_header_bg_color(color) ¶

set_headers(headers) ¶

set_hover_effect(hover=True) ¶

set_max_width(width) ¶

set_rows(rows) ¶

set_striped(striped=True) ¶

set_title(title) ¶

show_index(show=True) ¶

TableCell(value, status=None, color=None, bold=False, align='center') ¶

`TableWidget(widget_id=None)` ¶

`dataframe` `property` ¶

`headers` `property` ¶

`rows` `property` ¶

`title` `property` ¶

`add_colored_cell(value, color, bold=False, align='center')` ¶

`add_data_row(row_data)` ¶

`add_row(row)` ¶

`add_status_cell(value, status)` ¶

`clear_data()` ¶

`clear_rows()` ¶

`get_template_context()` ¶

`set_border_color(color)` ¶

`set_bordered(bordered=True)` ¶

`set_column_width(column, width)` ¶

`set_dataframe(df)` ¶

`set_header_bg_color(color)` ¶

`set_headers(headers)` ¶

`set_hover_effect(hover=True)` ¶

`set_max_width(width)` ¶

`set_rows(rows)` ¶

`set_striped(striped=True)` ¶

`set_title(title)` ¶

`show_index(show=True)` ¶

`TableCell(value, status=None, color=None, bold=False, align='center')` ¶