客户错误处理

本模块提供自定义日志记录、错误和警告处理功能，允许用户记录消息、清理日志文件以及向UI发送错误和警告信号。

日志管理

记录日志消息

log_message(message, logger='default', include_timestamp=False)

Log a message to a user log file.

Log files are automatically named with timestamp: {logger}_{YYYYMMDD_HHMMSS}.log

Parameters:

message (str) – The message to log
logger (str) – Logger name (used as filename base), defaults to “default”
include_timestamp (bool) – Whether to include timestamp in log content, defaults to False

Returns:

True if logging succeeded

Return type:

bool

Examples:

log_message("Task started")
log_message("Processing item 1", "process_log", True)

清理日志文件

clear_log(logger_name='', log_dir='/root/data/daystar_api/user_logs/')

Clear user log files.

This function works independently and doesn’t require initialization.

Parameters:

logger_name (str) – Optional logger name. If provided, only delete logs for this logger. If empty (default), delete all log files.
log_dir (str) – Optional log directory. Defaults to /root/data/daystar_api/user_logs/

Returns:

Number of log files deleted

Return type:

int

Examples:

# Delete all log files
deleted = clear_log()
print(f"Deleted {deleted} log files")

# Delete only 'my_task' logs
deleted = clear_log("my_task")
print(f"Deleted {deleted} my_task log files")

错误和警告处理

触发错误信号

raise_error(message, name='', code=0)

上报一个结构化错误信号到 /sdk/task/raise_error（供 UI 显示）。

注意：本底层函数仅推送 UI 通知并返回 response，不抛异常、不改变任务状态。若需”上报并使任务失败退出”，请使用 Python 层一体化入口 daystar_api.errors.raise_error(message, name=..., code=..., fatal=True)。

Parameters:

message (str) – 错误消息
name (str) – 错误名（如 “NAV_ESTOP_RESUME_FAILED”），默认空
code (int) – 错误码（系统保留 1-99999，客户自定义 >=100000），默认 0

Returns:

响应

state: State 对象（code/describe）
response.success: bool，True 表示已被服务端接收
response.message: str，服务端回执

Return type:

RaiseErrorResponse

Examples:

resp = raise_error("传感器连接失败", name="SENSOR_CONN_FAILED", code=30001)
if resp.response.success:
    print("已上报")

Note

服务：/sdk/task/raise_error（api_msgs/srv/RaiseError）
任务状态由脚本退出码决定，本函数不触发失败

触发警告信号

raise_warn(message, name='', code=0)

上报一个结构化警告信号到 /sdk/task/raise_warn（供 UI 显示）。

Parameters:

message (str) – 警告消息
name (str) – 警告名，默认空
code (int) – 警告码，默认 0

Returns:

响应

state: State 对象（code/describe）
response.success: bool，True 表示已被服务端接收
response.message: str，服务端回执

Return type:

RaiseWarnResponse

Examples:

resp = raise_warn("电量偏低", name="BATTERY_LOW", code=90001)
if resp.response.success:
    print("已上报")

Note

服务：/sdk/task/raise_warn（api_msgs/srv/RaiseWarn）
警告不影响任务状态