LogWidget API¶

`LogWidget(widget_id=None)` ¶

Bases: BaseWidget

Create a code block for elegantly displaying log information in emails.

This widget is particularly suitable for displaying program runtime logs, error reports, or any information that needs to be presented in chronological order and by severity level. It can automatically parse loguru format log strings and highlight them in different colors based on log level (such as INFO, WARNING, ERROR), making the content clear and readable.

Core features

Loguru format parsing: Automatically parses log lines containing timestamps, levels, sources, and messages.
Level highlighting: Applies different colors for different log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL).
Content filtering: Can set a minimum log level to only display logs at that level and above.
Display control: Can selectively show or hide timestamps, log levels, and source information.
Scrollbar: Automatically displays a scrollbar when log content exceeds the preset maximum height.

Examples:

Receive a list of loguru format logs and display them:

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)) # Only show WARNING and ERROR

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

Add logs one by one using the add_log_entry method:

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"))

Initialize LogWidget.

Parameters:

Name	Type	Description	Default
`widget_id`	`Optional[str]`	Optional 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
`str \| None`	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)` ¶

Append a single log string.

The log string will be automatically parsed as a LogEntry object and added to the log list.

Parameters:

Name	Type	Description	Default
`log`	`str`	Single log string.	required

Returns:

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

Examples:

Python Console Session

>>> widget = LogWidget().append_log("2024-07-07 10:00:00 | INFO | app:main - Application started")

`clear()` ¶

Clear all logs.

Returns:

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

Examples:

Python Console Session

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

`filter_by_level(level)` ¶

Filter display by log level.

Only log entries with level equal to or higher than the specified level will be displayed.

Parameters:

Name	Type	Description	Default
`level`	`LogLevel`	Minimum log level for filtering.	required

Returns:

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

Examples:

Python Console Session

>>> widget = LogWidget().filter_by_level(LogLevel.ERROR) # Only show ERROR and CRITICAL logs

`get_template_context()` ¶

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

`set_log_level(level)` ¶

Set log filter level.

Only logs at or above this level will be displayed.

Parameters:

Name	Type	Description	Default
`level`	`LogLevel`	Minimum log level.	required

Returns:

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

Examples:

Python Console Session

>>> widget = LogWidget().set_log_level(LogLevel.WARNING) # Only show WARNING and above logs

`set_logs(logs)` ¶

Set log list.

This method will clear existing logs and parse the new log string list.

Parameters:

Name	Type	Description	Default
`logs`	`List[str]`	Log string list.	required

Returns:

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

Examples:

Python Console Session

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

`set_max_height(height)` ¶

Set maximum height of the log display area.

When log content exceeds this height, a scrollbar will appear.

Parameters:

Name	Type	Description	Default
`height`	`str`	CSS height value, such as "400px", "50vh".	required

Returns:

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

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)` ¶

Set whether to display timestamps for log entries.

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) # 隐藏时间戳

Log Entry (LogEntry)¶

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

Data structure representing a single log entry.

This class is used to encapsulate log information parsed from log strings or manually created, including message content, log level, timestamp, and source (module, function, line number).

Attributes:

Name	Type	Description
`message`	`str`	Log message content.
`level`	`LogLevel`	Log level, defaults to `LogLevel.INFO`.
`timestamp`	`datetime`	Timestamp of the log record, defaults to current time.
`module`	`Optional[str]`	Name of the module that recorded the log.
`function`	`Optional[str]`	Name of the function that recorded the log.
`line_number`	`Optional[int]`	Line number where the log was recorded.

Examples:

Python

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

# Create an info-level log entry
info_log = LogEntry("User login successful", level=LogLevel.INFO, timestamp=datetime.now())

# Create an error-level log entry with source information
error_log = LogEntry("Database connection failed", level=LogLevel.ERROR,
                     module="db_connector", function="connect", line_number=123)

Initialize LogEntry.

Parameters:

Name	Type	Description	Default
`message`	`str`	Log message content.	required
`level`	`LogLevel`	Log level, defaults to `LogLevel.INFO`.	`INFO`
`timestamp`	`Optional[datetime]`	Timestamp of the log record, defaults to current time.	`None`
`module`	`Optional[str]`	Name of the module that recorded the log.	`None`
`function`	`Optional[str]`	Name of the function that recorded the log.	`None`
`line_number`	`Optional[int]`	Line number where the log was recorded.	`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) ¶

Log Entry (LogEntry)¶

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

`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)` ¶