Skip to content

StatusWidget API

StatusWidget(widget_id=None)

Bases: BaseWidget

Create a list for displaying key-value pair status information.

This widget is very suitable for displaying system monitoring metrics, service status, configuration parameters, and other structured data. Each item consists of a label and a value, and can display different colors based on status (such as success, warning, error).

Core features
  • Key-value pair list: Display multiple status items in a clear list format.
  • Layout switching: Support both vertical (default) and horizontal layout modes.
  • Status coloring: Can set different colors for each status item value to visually reflect its status.
  • Dynamic management: Support adding, updating, or removing status items at runtime.

Attributes:

Name Type Description
items List[StatusItem]

List containing all status items.
title Optional[str]

Title of the entire status list.
layout LayoutType

Layout mode of the list (vertical or horizontal).

Examples:

Create a vertical layout system monitoring status list:

Python
from email_widget.widgets import StatusWidget
from email_widget.core.enums import StatusType, LayoutType

system_monitor = (StatusWidget()                          .set_title("System Health Check")                          .set_layout(LayoutType.VERTICAL)                          .add_status_item("CPU Usage", "15%", StatusType.SUCCESS)                          .add_status_item("Memory Usage", "78%", StatusType.WARNING)                          .add_status_item("Disk Space", "95%", StatusType.ERROR)                          .add_status_item("Uptime", "32 days"))

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

Create a horizontal layout service status list:

Python
service_status = (StatusWidget()                          .set_title("Microservice Status")                          .set_layout(LayoutType.HORIZONTAL)                          .add_status_item("Authentication Service", "Online", StatusType.SUCCESS)                          .add_status_item("Payment Service", "Offline", StatusType.ERROR))

Initialize StatusWidget.

Parameters:

Name Type Description Default
widget_id Optional[str]

Optional Widget ID.

 None

Functions

add_status_item(label, value, status=None)

Add a status item to the list.

Parameters:

Name Type Description Default
label str

Descriptive label for the status item.

 required
value str

Actual value of the status item.

 required
status Optional[StatusType]

Type of the status item, used to determine the color of the value.

 None

Returns:

Name Type Description
StatusWidget StatusWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> widget = StatusWidget().add_status_item("Service Status", "Running", StatusType.SUCCESS)
clear_items()

Clear all status items.

Returns:

Name Type Description
StatusWidget StatusWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> widget = StatusWidget().clear_items()
get_item_count()

Get the count of current status items.

Returns:

Name Type Description
int int

Number of status items.

Examples:

Python Console Session
>>> count = StatusWidget().add_status_item("A", "1").get_item_count()
>>> print(count) # Output: 1
get_template_context()

Get template context data required for rendering

remove_item(label)

Remove specified status item by label.

Parameters:

Name Type Description Default
label str

Label of the status item to remove.

 required

Returns:

Name Type Description
StatusWidget StatusWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> widget = StatusWidget().remove_item("CPU Usage")
set_layout(layout)

Set the layout mode of status items.

Parameters:

Name Type Description Default
layout LayoutType

Layout type, can be LayoutType.VERTICAL or LayoutType.HORIZONTAL.

 required

Returns:

Name Type Description
StatusWidget StatusWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> widget = StatusWidget().set_layout(LayoutType.HORIZONTAL)
set_title(title)

Set the title of the status list.

Parameters:

Name Type Description Default
title str

Title text.

 required

Returns:

Name Type Description
StatusWidget StatusWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> widget = StatusWidget().set_title("Server Health Status")
update_item(label, value, status=None)

Update value and status of the status item with specified label.

If a matching label is found, update its value and status; otherwise, do nothing.

Parameters:

Name Type Description Default
label str

Label of the status item to update.

 required
value str

New value.

 required
status StatusType

Optional new status type.

 None

Returns:

Name Type Description
StatusWidget StatusWidget

Returns self to support method chaining.

Examples:

Python Console Session
>>> widget = StatusWidget().update_item("CPU Usage", "20%", StatusType.WARNING)

Status Item (StatusItem)

StatusItem(label, value, status=None)

Data structure representing a single status item.

Each status item contains a label (description), a value, and an optional status type, used for display in StatusWidget.

Attributes:

Name Type Description
label str

Descriptive label for the status item.
value str

Actual value of the status item.
status Optional[StatusType]

Type of the status item, used to determine the color of the value.

Examples:

Python
from email_widget.widgets import StatusItem
from email_widget.core.enums import StatusType

# Create a success status CPU usage item
cpu_status = StatusItem("CPU Usage", "15%", StatusType.SUCCESS)

# Create a regular info item
uptime_info = StatusItem("System Uptime", "30 days")

Initialize StatusItem.

Parameters:

Name Type Description Default
label str

Descriptive label for the status item.

 required
value str

Actual value of the status item.

 required
status Optional[StatusType]

Type of the status item, used to determine the color of the value.

 None