Email 主类¶

`Email(title='邮件报告')` ¶

邮件主类，负责管理和渲染邮件内容.

这个类是 EmailWidget 库的核心，用于创建和管理HTML邮件报告. 它作为一个功能强大的容器，可以添加、管理和编排各种“微件”（Widget），最终将它们渲染成一个美观、专业的HTML邮件.

核心功能

微件管理: 轻松添加、移除、查找和迭代处理各种内容组件（如文本、表格、图表等）.
邮件属性配置: 自定义邮件的标题、副标题和页脚.
快捷方法: 提供一系列 add_* 方法，用于快速创建和添加常用微件，简化代码.
内容导出: 支持将邮件导出为独立的 HTML 文件或获取其 HTML 字符串内容.
样式配置: 通过 EmailConfig 对象，可以自定义邮件的主题颜色、字体和布局宽度.

Attributes:

Name	Type	Description
`title`	`str`	邮件的主标题.
`subtitle`	`Optional[str]`	邮件的副标题，显示在主标题下方.
`footer_text`	`Optional[str]`	邮件的页脚文本.
`widgets`	`List[BaseWidget]`	存储所有已添加微件的列表.
`config`	`EmailConfig`	邮件的配置对象，用于控制样式和行为.

Examples:

一个基本的邮件创建和导出流程：

Python

from email_widget import Email
from email_widget.core.enums import TextType, AlertType

# 1. 创建一个邮件对象
email = Email("季度销售报告")

# 2. 设置邮件的元数据
email.set_subtitle("2024年第一季度")
email.set_footer("本报告由销售部分析团队生成")

# 3. 使用快捷方法添加内容
email.add_text("核心摘要", text_type=TextType.TITLE_LARGE)
email.add_text("本季度总销售额达到 1,234,567 元，同比增长 15%.")
email.add_alert("注意：数据仍在初步核算中.", alert_type=AlertType.WARNING)
email.add_progress(85, label="季度KPI完成率", theme="success")

# 4. 导出为HTML文件
# 将在默认输出目录（通常是 ./output）下生成 "quarterly_report.html"
file_path = email.export_html("quarterly_report.html")

print(f"报告已成功生成于: {file_path}")

# 你也可以直接获取HTML字符串
html_content = email.export_str()
# print(html_content)

初始化Email对象.

Parameters:

Name	Type	Description	Default
`title`	`str`	邮件标题，默认为"邮件报告"	`'邮件报告'`

Functions¶

`len()` ¶

支持len()函数获取Widget数量.

Returns:

Type	Description
`int`	Widget数量

Examples:

Python Console Session

>>> email = Email()
>>> email.add_widget(TextWidget())
>>> print(len(email))  # 输出: 1

`str()` ¶

返回邮件对象的字符串表示.

Returns:

Type	Description
`str`	包含标题和Widget数量的字符串

Examples:

Python Console Session

>>> email = Email("测试邮件")
>>> print(str(email))  # 输出: Email(title='测试邮件', widgets=0)

`add_alert(content, alert_type=None, title=None)` ¶

快速添加警告框Widget.

Parameters:

Name	Type	Description	Default
`content`	`str`	警告内容	required
`alert_type`	`AlertType`	警告类型，默认为NOTE	`None`
`title`	`str \| None`	自定义标题，可选	`None`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.add_alert("任务执行成功！", AlertType.TIP)
>>> email.add_alert("注意检查数据", AlertType.WARNING, "重要提醒")

`add_card(title, content, icon=None, metadata=None)` ¶

快速添加卡片Widget.

Parameters:

Name	Type	Description	Default
`title`	`str`	卡片标题	required
`content`	`str`	卡片内容	required
`icon`	`str \| None`	图标，可选	`None`
`metadata`	`dict[str, str] \| None`	元数据字典，可选	`None`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.add_card("系统状态", "所有服务运行正常", "✅")
>>> # 带元数据的卡片
>>> metadata = {"CPU": "15%", "内存": "60%"}
>>> email.add_card("服务器监控", "资源使用情况", "🖥️", metadata)

`add_chart_from_plt(title=None, description=None, data_summary=None)` ¶

快速添加matplotlib图表Widget.

Parameters:

Name	Type	Description	Default
`title`	`str \| None`	图表标题，可选	`None`
`description`	`str \| None`	图表描述，可选	`None`
`data_summary`	`str \| None`	数据摘要，可选	`None`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> import matplotlib.pyplot as plt
>>> plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
>>> plt.title("销售趋势")
>>>
>>> email = Email()
>>> email.add_chart_from_plt("月度销售", "显示销售趋势变化")

`add_circular_progress(value, max_value=100.0, label=None, theme=None, size='100px')` ¶

快速添加圆形进度条Widget.

Parameters:

Name	Type	Description	Default
`value`	`float`	当前进度值	required
`max_value`	`float`	最大值，默认100	`100.0`
`label`	`str \| None`	进度条标签，可选	`None`
`theme`	`ProgressTheme`	主题，默认为PRIMARY	`None`
`size`	`str`	圆形大小，默认"100px"	`'100px'`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.add_circular_progress(85, label="整体完成度")
>>> email.add_circular_progress(100, theme=ProgressTheme.SUCCESS, size="120px")

`add_log(logs, title=None, show_timestamp=True, show_level=True, filter_level=None, max_height='400px')` ¶

快速添加日志Widget.

Parameters:

Name	Type	Description	Default
`logs`	`list[str]`	日志列表	required
`title`	`str \| None`	日志标题，可选	`None`
`show_timestamp`	`bool`	是否显示时间戳	`True`
`show_level`	`bool`	是否显示日志级别	`True`
`filter_level`	`LogLevel`	过滤级别，可选	`None`
`max_height`	`str`	最大高度，默认"400px"	`'400px'`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> logs = [
...     "2024-01-01 10:00:00.000 | INFO | main:process:10 - 任务开始",
...     "2024-01-01 10:00:01.000 | WARNING | main:check:20 - 发现异常数据",
...     "2024-01-01 10:00:02.000 | INFO | main:finish:30 - 任务完成"
... ]
>>> email.add_log(logs, "执行日志")

`add_progress(value, label=None, max_value=100.0, theme=None, show_percentage=True)` ¶

快速添加进度条Widget.

Parameters:

Name	Type	Description	Default
`value`	`float`	当前进度值	required
`label`	`str \| None`	进度条标签，可选	`None`
`max_value`	`float`	最大值，默认100	`100.0`
`theme`	`ProgressTheme`	主题，默认为PRIMARY	`None`
`show_percentage`	`bool`	是否显示百分比	`True`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.add_progress(75, "任务完成度")
>>> email.add_progress(100, "下载进度", theme=ProgressTheme.SUCCESS)

`add_quote(content, author=None, source=None, quote_type=None)` ¶

快速添加引用Widget.

Parameters:

Name	Type	Description	Default
`content`	`str`	引用内容	required
`author`	`str \| None`	作者，可选	`None`
`source`	`str \| None`	来源，可选	`None`
`quote_type`	`StatusType`	引用类型，默认为INFO	`None`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.add_quote("成功不是终点，失败不是致命的", "丘吉尔")
>>> email.add_quote("数据是新时代的石油", source="《经济学人》")

`add_status_items(items, title=None, layout=None)` ¶

快速添加状态信息Widget.

Parameters:

Name	Type	Description	Default
`items`	`list[dict[str, str]]`	状态项列表，每项包含 label, value, status(可选)	required
`title`	`str \| None`	状态组标题，可选	`None`
`layout`	`LayoutType`	布局类型，默认为VERTICAL	`None`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> items = [
...     {"label": "CPU使用率", "value": "15%"},
...     {"label": "内存使用率", "value": "60%"},
...     {"label": "磁盘空间", "value": "80%"}
... ]
>>> email = Email()
>>> email.add_status_items(items, "系统监控")

`add_table_from_data(data, headers=None, title=None, show_index=False, striped=True, bordered=True, hoverable=True)` ¶

快速添加表格Widget.

Parameters:

Name	Type	Description	Default
`data`	`list[list[str]]`	表格数据，二维列表	required
`headers`	`list[str] \| None`	表头列表，可选	`None`
`title`	`str \| None`	表格标题，可选	`None`
`show_index`	`bool`	是否显示行索引	`False`
`striped`	`bool`	是否使用条纹样式	`True`
`bordered`	`bool`	是否显示边框	`True`
`hoverable`	`bool`	是否支持悬停效果	`True`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> data = [["张三", "100", "优秀"], ["李四", "95", "良好"]]
>>> headers = ["姓名", "分数", "等级"]
>>> email.add_table_from_data(data, headers, "成绩单")

`add_table_from_df(df, title=None, show_index=False, striped=True, bordered=True, hoverable=True)` ¶

快速添加来自DataFrame的表格Widget.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	pandas DataFrame对象	required
`title`	`str \| None`	表格标题，可选	`None`
`show_index`	`bool`	是否显示行索引	`False`
`striped`	`bool`	是否使用条纹样式	`True`
`bordered`	`bool`	是否显示边框	`True`
`hoverable`	`bool`	是否支持悬停效果	`True`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> import pandas as pd
>>> df = pd.DataFrame({"姓名": ["张三", "李四"], "分数": [100, 95]})
>>> email = Email()
>>> email.add_table_from_df(df, "成绩统计")

`add_text(content, text_type=None, color=None, font_size=None, align=None, font_weight=None)` ¶

快速添加文本Widget.

Parameters:

Name	Type	Description	Default
`content`	`str`	文本内容	required
`text_type`	`TextType`	文本类型，默认为TextType.BODY	`None`
`color`	`str \| None`	文本颜色，如"#ff0000"	`None`
`font_size`	`str \| None`	字体大小，如"18px"	`None`
`align`	`TextAlign`	文本对齐方式	`None`
`font_weight`	`str \| None`	字体粗细，如"bold"	`None`

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> # 普通正文
>>> email.add_text("这是一段普通文本")
>>> # 大标题
>>> email.add_text("重要标题", TextType.TITLE_LARGE)
>>> # 带样式的文本
>>> email.add_text("重要提示", color="#ff0000", font_size="18px")

`add_widget(widget)` ¶

添加单个Widget到邮件中.

Parameters:

Name	Type	Description	Default
`widget`	`BaseWidget`	要添加的Widget对象	required

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> text_widget = TextWidget().set_content("Hello")
>>> email.add_widget(text_widget)

`add_widgets(widgets)` ¶

批量添加多个Widget到邮件中.

Parameters:

Name	Type	Description	Default
`widgets`	`list[BaseWidget]`	Widget对象列表	required

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> widgets = [TextWidget(), TableWidget(), ChartWidget()]
>>> email.add_widgets(widgets)

`clear_widgets()` ¶

清空所有Widget.

Returns:

Type	Description
`Email`	返回self以支持链式调用

`export_html(filename=None, output_dir=None)` ¶

导出邮件为HTML文件.

Parameters:

Name	Type	Description	Default
`filename`	`str \| None`	可选的文件名，如果不提供则自动生成	`None`
`output_dir`	`str \| None`	可选的输出目录，如果不提供则使用配置中的默认目录	`None`

Returns:

Type	Description
`Path`	导出文件的完整路径

Examples:

Python Console Session

>>> email = Email("报告")
>>> # 使用默认文件名
>>> path = email.export_html()
>>>
>>> # 指定文件名和目录
>>> path = email.export_html("my_report.html", "./reports")

`export_str()` ¶

导出邮件为HTML文本.

Returns:

Type	Description
`str`	完整的HTML邮件字符串

Examples:

Python Console Session

>>> email = Email("预览测试")
>>> html = email.export_str()
>>> print(html[:100])  # 打印前100个字符

`get_widget(widget_id)` ¶

根据ID获取指定的Widget.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	Widget的ID	required

Returns:

Type	Description
`BaseWidget \| None`	找到的Widget对象，如果不存在则返回None

Examples:

Python Console Session

>>> email = Email()
>>> widget = TextWidget().set_widget_id("my_text")
>>> email.add_widget(widget)
>>> found_widget = email.get_widget("my_text")

`get_widget_count()` ¶

获取当前邮件中Widget的数量.

Returns:

Type	Description
`int`	Widget数量

Examples:

Python Console Session

>>> email = Email()
>>> email.add_widget(TextWidget())
>>> email.add_widget(TableWidget())
>>> print(email.get_widget_count())  # 输出: 2

`remove_widget(widget_id)` ¶

根据ID移除指定的Widget.

Parameters:

Name	Type	Description	Default
`widget_id`	`str`	要移除的Widget的ID	required

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> widget = TextWidget().set_widget_id("my_text")
>>> email.add_widget(widget)
>>> email.remove_widget("my_text")

`set_footer(footer_text)` ¶

设置邮件脚注.

Parameters:

Name	Type	Description	Default
`footer_text`	`str \| None`	脚注文本，如果为None则使用默认文本	required

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.set_footer("本报告由数据团队自动生成")

`set_subtitle(subtitle)` ¶

设置邮件副标题.

Parameters:

Name	Type	Description	Default
`subtitle`	`str \| None`	副标题文本，如果为None则使用默认的时间戳	required

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.set_subtitle("数据统计报告")

`set_title(title)` ¶

设置邮件标题.

Parameters:

Name	Type	Description	Default
`title`	`str`	新的邮件标题	required

Returns:

Type	Description
`Email`	返回self以支持链式调用

Examples:

Python Console Session

>>> email = Email()
>>> email.set_title("每日数据报告 - 2024-01-01")

Email 主类¶

Email(title='邮件报告') ¶

Functions¶

__len__() ¶

__str__() ¶

add_alert(content, alert_type=None, title=None) ¶

add_card(title, content, icon=None, metadata=None) ¶

add_chart_from_plt(title=None, description=None, data_summary=None) ¶

add_circular_progress(value, max_value=100.0, label=None, theme=None, size='100px') ¶

add_log(logs, title=None, show_timestamp=True, show_level=True, filter_level=None, max_height='400px') ¶

add_progress(value, label=None, max_value=100.0, theme=None, show_percentage=True) ¶

add_quote(content, author=None, source=None, quote_type=None) ¶

add_status_items(items, title=None, layout=None) ¶

add_table_from_data(data, headers=None, title=None, show_index=False, striped=True, bordered=True, hoverable=True) ¶

add_table_from_df(df, title=None, show_index=False, striped=True, bordered=True, hoverable=True) ¶

add_text(content, text_type=None, color=None, font_size=None, align=None, font_weight=None) ¶

add_widget(widget) ¶

add_widgets(widgets) ¶

clear_widgets() ¶

export_html(filename=None, output_dir=None) ¶

export_str() ¶

get_widget(widget_id) ¶

get_widget_count() ¶

remove_widget(widget_id) ¶

set_footer(footer_text) ¶

set_subtitle(subtitle) ¶

set_title(title) ¶

`Email(title='邮件报告')` ¶

`len()` ¶

`str()` ¶

`add_alert(content, alert_type=None, title=None)` ¶

`add_card(title, content, icon=None, metadata=None)` ¶

`add_chart_from_plt(title=None, description=None, data_summary=None)` ¶

`add_circular_progress(value, max_value=100.0, label=None, theme=None, size='100px')` ¶

`add_log(logs, title=None, show_timestamp=True, show_level=True, filter_level=None, max_height='400px')` ¶

`add_progress(value, label=None, max_value=100.0, theme=None, show_percentage=True)` ¶

`add_quote(content, author=None, source=None, quote_type=None)` ¶

`add_status_items(items, title=None, layout=None)` ¶

`add_table_from_data(data, headers=None, title=None, show_index=False, striped=True, bordered=True, hoverable=True)` ¶

`add_table_from_df(df, title=None, show_index=False, striped=True, bordered=True, hoverable=True)` ¶

`add_text(content, text_type=None, color=None, font_size=None, align=None, font_weight=None)` ¶

`add_widget(widget)` ¶

`add_widgets(widgets)` ¶

`clear_widgets()` ¶

`export_html(filename=None, output_dir=None)` ¶

`export_str()` ¶

`get_widget(widget_id)` ¶

`get_widget_count()` ¶

`remove_widget(widget_id)` ¶

`set_footer(footer_text)` ¶

`set_subtitle(subtitle)` ¶

`set_title(title)` ¶