LogWidget API¶

`LogWidget(widget_id=None)` ¶

Bases: BaseWidget

创建一个用于在邮件中优雅地显示日志信息的代码块。

该微件特别适合展示程序运行日志、错误报告或任何需要按时间顺序和严重性级别呈现的信息。它能够自动解析 loguru 格式的日志字符串，并根据日志级别（如 INFO, WARNING, ERROR）以不同的颜色高亮显示，使其内容清晰易读。

核心功能

Loguru 格式解析: 自动解析包含时间戳、级别、来源和消息的日志行。
级别高亮: 为不同的日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）应用不同的颜色。
内容过滤: 可以设置一个最低日志级别，只显示该级别及以上的日志。
显示控制: 可以选择性地显示或隐藏时间戳、日志级别和来源信息。
滚动条: 当日志内容超出预设的最大高度时，会自动显示滚动条。

Examples:

接收一个 loguru 格式的日志列表并显示：

Python

from email_widget.widgets import LogWidget
from email_widget.core.enums import LogLevel

log_messages = [
    "2024-07-07 10:30:00.123 | INFO     | my_app.main:run:45 - Application started successfully.",
    "2024-07-07 10:31:15.456 | WARNING  | my_app.database:connect:88 - Connection is slow.",
    "2024-07-07 10:32:05.789 | ERROR    | my_app.api:request:152 - Failed to fetch data from API."
]

log_viewer = (LogWidget()
              .set_title("Application Run Log")
              .set_logs(log_messages)
              .set_max_height("300px")
              .filter_by_level(LogLevel.WARNING)) # 只显示 WARNING 和 ERROR

# 假设 email 是一个 Email 对象
# email.add_widget(log_viewer)

通过 add_log_entry 方法逐条添加日志：

Python

manual_log = (LogWidget()
              .set_title("Manual Log Entries")
              .add_log_entry("User logged in.", level=LogLevel.INFO, module="auth")
              .add_log_entry("Invalid password attempt.", level=LogLevel.WARNING, module="auth"))

初始化LogWidget。

Parameters:

Name	Type	Description	Default
`widget_id`	`Optional[str]`	可选的Widget ID。	`None`

Attributes¶

`logs` `property` ¶

获取过滤后的日志列表。

如果设置了 filter_level，则只返回符合过滤条件的日志。

Returns:

Type	Description
`list[LogEntry]`	List[LogEntry]: 过滤后的日志条目列表。

`max_height` `property` ¶

获取日志显示区域的最大高度。

Returns:

Name	Type	Description
`str`	`str`	最大高度的CSS值。

`title` `property` ¶

获取日志组件的标题。

Returns:

Type	Description
`Optional[str]`	Optional[str]: 标题文本或None。

Functions¶

`add_log_entry(message, level=LogLevel.INFO, timestamp=None, module=None, function=None, line_number=None)` ¶

手动添加一个日志条目。

此方法允许直接创建 LogEntry 对象并添加到日志列表中，适用于非Loguru格式的日志或需要自定义日志内容的情况。

Parameters:

Name	Type	Description	Default
`message`	`str`	日志消息内容。	required
`level`	`LogLevel`	日志级别，默认为 `LogLevel.INFO`。	`INFO`
`timestamp`	`Optional[datetime]`	日志记录的时间戳，默认为当前时间。	`None`
`module`	`Optional[str]`	记录日志的模块名称。	`None`
`function`	`Optional[str]`	记录日志的函数名称。	`None`
`line_number`	`Optional[int]`	记录日志的代码行号。	`None`

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().add_log_entry("自定义消息", level=LogLevel.DEBUG)

`add_log_parser(log_parser)` ¶

添加自定义日志解析器到解析器链中。

新添加的解析器会插入到PlainTextParser之前，确保PlainTextParser始终作为兜底解析器。

Parameters:

Name	Type	Description	Default
`log_parser`	`LogParser`	要添加的日志解析器实例。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> custom_parser = MyCustomLogParser()
>>> widget = LogWidget().add_log_parser(custom_parser)

`append_log(log)` ¶

追加单条日志字符串。

日志字符串会被自动解析为 LogEntry 对象并添加到日志列表中。

Parameters:

Name	Type	Description	Default
`log`	`str`	单条日志字符串。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().append_log("2024-07-07 10:00:00 | INFO | app:main - 应用启动")

`clear()` ¶

清空所有日志。

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().clear()

`filter_by_level(level)` ¶

按日志级别过滤显示。

只有级别等于或高于指定 level 的日志条目才会被显示。

Parameters:

Name	Type	Description	Default
`level`	`LogLevel`	过滤的最低日志级别。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().filter_by_level(LogLevel.ERROR) # 只显示ERROR和CRITICAL日志

`get_template_context()` ¶

获取模板渲染所需的上下文数据

`set_log_level(level)` ¶

设置日志过滤级别。

只有达到或高于此级别的日志才会被显示。

Parameters:

Name	Type	Description	Default
`level`	`LogLevel`	最低日志级别。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().set_log_level(LogLevel.WARNING) # 只显示WARNING及以上日志

`set_logs(logs)` ¶

设置日志列表。

此方法会清空现有日志，并解析新的日志字符串列表。

Parameters:

Name	Type	Description	Default
`logs`	`List[str]`	日志字符串列表。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> logs = ["INFO: App started", "ERROR: Failed to connect"]
>>> widget = LogWidget().set_logs(logs)

`set_max_height(height)` ¶

设置日志显示区域的最大高度。

当日志内容超出此高度时，将出现滚动条。

Parameters:

Name	Type	Description	Default
`height`	`str`	CSS高度值，如 "400px", "50vh"。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().set_max_height("300px")

`set_title(title)` ¶

设置日志组件的标题。

Parameters:

Name	Type	Description	Default
`title`	`str`	标题文本。	required

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().set_title("系统运行日志")

`show_level(show=True)` ¶

设置是否显示日志条目的级别。

Parameters:

Name	Type	Description	Default
`show`	`bool`	是否显示级别，默认为True。	`True`

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().show_level(False) # 隐藏级别

`show_source(show=True)` ¶

设置是否显示日志条目的来源信息（模块、函数、行号）。

Parameters:

Name	Type	Description	Default
`show`	`bool`	是否显示来源信息，默认为True。	`True`

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().show_source(False) # 隐藏来源信息

`show_timestamp(show=True)` ¶

设置是否显示日志条目的时间戳。

Parameters:

Name	Type	Description	Default
`show`	`bool`	是否显示时间戳，默认为True。	`True`

Returns:

Name	Type	Description
`LogWidget`	`LogWidget`	返回self以支持链式调用。

Examples:

Python Console Session

>>> widget = LogWidget().show_timestamp(False) # 隐藏时间戳

日志条目 (LogEntry)¶

`LogEntry(message, level=LogLevel.INFO, timestamp=None, module=None, function=None, line_number=None)` ¶

表示单个日志条目的数据结构。

这个类用于封装从日志字符串中解析出来或手动创建的日志信息，包括消息内容、日志级别、时间戳以及来源（模块、函数、行号）。

Attributes:

Name	Type	Description
`message`	`str`	日志消息内容。
`level`	`LogLevel`	日志级别，默认为 `LogLevel.INFO`。
`timestamp`	`datetime`	日志记录的时间戳，默认为当前时间。
`module`	`Optional[str]`	记录日志的模块名称。
`function`	`Optional[str]`	记录日志的函数名称。
`line_number`	`Optional[int]`	记录日志的代码行号。

Examples:

Python

from datetime import datetime
from email_widget.core.enums import LogLevel

# 创建一个信息级别的日志条目
info_log = LogEntry("用户登录成功", level=LogLevel.INFO, timestamp=datetime.now())

# 创建一个错误级别的日志条目，包含来源信息
error_log = LogEntry("数据库连接失败", level=LogLevel.ERROR,
                     module="db_connector", function="connect", line_number=123)

初始化LogEntry。

Parameters:

Name	Type	Description	Default
`message`	`str`	日志消息内容。	required
`level`	`LogLevel`	日志级别，默认为 `LogLevel.INFO`。	`INFO`
`timestamp`	`Optional[datetime]`	日志记录的时间戳，默认为当前时间。	`None`
`module`	`Optional[str]`	记录日志的模块名称。	`None`
`function`	`Optional[str]`	记录日志的函数名称。	`None`
`line_number`	`Optional[int]`	记录日志的代码行号。	`None`

LogWidget API¶

LogWidget(widget_id=None) ¶

Attributes¶

logs property ¶

max_height property ¶

title property ¶

Functions¶

add_log_entry(message, level=LogLevel.INFO, timestamp=None, module=None, function=None, line_number=None) ¶

add_log_parser(log_parser) ¶

append_log(log) ¶

clear() ¶

filter_by_level(level) ¶

get_template_context() ¶

set_log_level(level) ¶

set_logs(logs) ¶

set_max_height(height) ¶

set_title(title) ¶

show_level(show=True) ¶

show_source(show=True) ¶

show_timestamp(show=True) ¶

日志条目 (LogEntry)¶

LogEntry(message, level=LogLevel.INFO, timestamp=None, module=None, function=None, line_number=None) ¶

Functions¶

`LogWidget(widget_id=None)` ¶

`logs` `property` ¶

`max_height` `property` ¶

`title` `property` ¶

`add_log_entry(message, level=LogLevel.INFO, timestamp=None, module=None, function=None, line_number=None)` ¶

`add_log_parser(log_parser)` ¶

`append_log(log)` ¶

`clear()` ¶

`filter_by_level(level)` ¶

`get_template_context()` ¶

`set_log_level(level)` ¶

`set_logs(logs)` ¶

`set_max_height(height)` ¶

`set_title(title)` ¶

`show_level(show=True)` ¶

`show_source(show=True)` ¶

`show_timestamp(show=True)` ¶

`LogEntry(message, level=LogLevel.INFO, timestamp=None, module=None, function=None, line_number=None)` ¶