CircularProgressWidget API

CircularProgressWidget(widget_id=None)

Bases: BaseWidget

Create a circular progress indicator.

Circular progress bars display task completion, resource utilization, or any quantifiable percentage data in a compact and intuitive way. They are perfect for dashboards or reports where space is limited.

Core features

• Dynamic updates: Supports setting, increasing, decreasing, resetting, or directly completing progress.
• Theming: Provides multiple preset themes (such as success, warning, error) to intuitively reflect status through colors.
• Custom appearance: Can freely adjust the size and line thickness of the progress ring.

Attributes:

Name	Type	Description
value	float	Current progress value.
max_value	float	Maximum progress value, defaults to 100.
label	Optional[str]	Descriptive text displayed below the progress ring.
theme	ProgressTheme	Color theme of the progress ring.

Examples:

Create a circular progress bar showing task completion:

Python

from email_widget.widgets import CircularProgressWidget
from email_widget.core.enums import ProgressTheme

# Create a progress ring representing "success" status
task_progress = (CircularProgressWidget()
                 .set_value(85)
                 .set_label("Data Processing Progress")
                 .set_theme(ProgressTheme.SUCCESS)
                 .set_size("120px")
                 .set_stroke_width("10px"))

# Create a resource monitoring ring representing "warning" status
disk_usage = (CircularProgressWidget()
              .set_value(92)
              .set_label("Disk Usage")
              .set_theme(ProgressTheme.WARNING)
              .set_size("90px"))

Initialize CircularProgressWidget.

Parameters:

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

Functions

complete()

Set progress to maximum value (100%).

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().complete() # Progress becomes 100%

decrement(amount=1.0)

Decrease progress value.

Parameters:

Name	Type	Description	Default
amount	float	Amount to decrease, defaults to 1.0.	1.0

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(50).decrement(5) # Progress becomes 45

get_template_context()

Get template context data required for rendering

increment(amount=1.0)

Increase progress value.

Parameters:

Name	Type	Description	Default
amount	float	Amount to increase, defaults to 1.0.	1.0

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(50).increment(10) # Progress becomes 60

reset()

Reset progress to 0.

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(75).reset() # Progress becomes 0

set_label(label)

Set descriptive label displayed below the progress ring.

Parameters:

Name	Type	Description	Default
label	str	Label text.	required

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_label("Task Completion")

set_max_value(max_val)

Set maximum value for progress.

Parameters:

Name	Type	Description	Default
max_val	float	Maximum value for progress.	required

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_max_value(200)

set_size(size)

Set overall size of the circular progress bar.

Parameters:

Name	Type	Description	Default
size	str	CSS size value, such as "100px", "5em".	required

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Raises:

Type	Description
ValueError	When size format is invalid.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_size("120px")

set_stroke_width(width)

Set line thickness of the circular progress bar.

Parameters:

Name	Type	Description	Default
width	str	CSS width value, such as "8px", "0.5em".	required

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_stroke_width("12px")

set_theme(theme)

Set color theme for the progress ring.

Parameters:

Name	Type	Description	Default
theme	ProgressTheme	Progress ring theme enum value.	required

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_theme(ProgressTheme.SUCCESS)

set_value(value)

Set current progress value.

Parameters:

Name	Type	Description	Default
value	float	Progress value, should be between 0 and max_value.	required

Returns:

Name	Type	Description
CircularProgressWidget	CircularProgressWidget	Returns self to support method chaining.

Raises:

Type	Description
ValueError	When value is out of valid range.

Examples:

Python Console Session

>>> widget = CircularProgressWidget().set_value(75)