|
|
import logging
|
|
|
|
|
|
# wr创建当前模块的日志记录器，用于记录钩子系统的运行日志（如注册、执行、错误等）
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
# wr私有字典，用于存储所有注册的钩子：
|
|
|
# wr键为钩子名称（str），值为该钩子对应的回调函数列表（list[callable]）
|
|
|
_hooks = {}
|
|
|
|
|
|
|
|
|
def register(hook_name: str, callback: callable):
|
|
|
"""
|
|
|
wr注册一个回调函数到指定钩子。
|
|
|
一个钩子可以注册多个回调函数，执行时会按注册顺序依次调用。
|
|
|
|
|
|
Args:
|
|
|
hook_name: 钩子名称（需与后续执行/过滤时的钩子名称对应）
|
|
|
callback: 回调函数（当钩子触发时需要执行的函数）
|
|
|
"""
|
|
|
#wr 如果钩子名称不在_hooks中，先初始化一个空列表用于存储回调
|
|
|
if hook_name not in _hooks:
|
|
|
_hooks[hook_name] = []
|
|
|
#wr 将回调函数添加到该钩子的回调列表中
|
|
|
_hooks[hook_name].append(callback)
|
|
|
#wr 记录调试日志，说明已注册钩子及对应的回调函数名
|
|
|
logger.debug(f"Registered hook '{hook_name}' with callback '{callback.__name__}'")
|
|
|
|
|
|
|
|
|
def run_action(hook_name: str, *args, **kwargs):
|
|
|
"""
|
|
|
wr执行指定的"动作钩子（Action Hook）"。
|
|
|
动作钩子用于触发一系列操作（无返回值），会按注册顺序执行所有绑定的回调函数。
|
|
|
|
|
|
Args:
|
|
|
hook_name: 要执行的钩子名称
|
|
|
*args: 传递给回调函数的位置参数
|
|
|
**kwargs: 传递给回调函数的关键字参数
|
|
|
"""
|
|
|
# wr检查该钩子是否有已注册的回调函数
|
|
|
if hook_name in _hooks:
|
|
|
logger.debug(f"Running action hook '{hook_name}'")
|
|
|
# wr遍历该钩子的所有回调函数并执行
|
|
|
for callback in _hooks[hook_name]:
|
|
|
try:
|
|
|
#wr 传递参数调用回调函数
|
|
|
callback(*args, **kwargs)
|
|
|
except Exception as e:
|
|
|
# wr捕获回调执行中的异常，记录错误日志（包含异常详情）
|
|
|
logger.error(
|
|
|
f"Error running action hook '{hook_name}' callback '{callback.__name__}': {e}",
|
|
|
exc_info=True #wr 记录完整的异常堆栈信息
|
|
|
)
|
|
|
|
|
|
|
|
|
def apply_filters(hook_name: str, value, *args, **kwargs):
|
|
|
"""
|
|
|
wr执行指定的"过滤钩子（Filter Hook）"。
|
|
|
过滤钩子用于对一个值进行链式处理（有输入有输出），会将初始值依次传递给所有绑定的回调函数，
|
|
|
每个回调的返回值作为下一个回调的输入，最终返回经过所有处理后的结果。
|
|
|
|
|
|
Args:
|
|
|
hook_name: 要执行的钩子名称
|
|
|
value: 初始值（需要被过滤/处理的值）
|
|
|
*args: 传递给回调函数的位置参数
|
|
|
**kwargs: 传递给回调函数的关键字参数
|
|
|
|
|
|
Returns:
|
|
|
经过所有回调函数处理后的最终值
|
|
|
"""
|
|
|
#wr 检查该钩子是否有已注册的回调函数
|
|
|
if hook_name in _hooks:
|
|
|
logger.debug(f"Applying filter hook '{hook_name}'")
|
|
|
# wr遍历该钩子的所有回调函数，对值进行链式处理
|
|
|
for callback in _hooks[hook_name]:
|
|
|
try:
|
|
|
# wr调用回调函数处理当前值，将返回值作为新值继续处理
|
|
|
value = callback(value, *args, **kwargs)
|
|
|
except Exception as e:
|
|
|
#wr 捕获回调执行中的异常，记录错误日志（包含异常详情）
|
|
|
logger.error(
|
|
|
f"Error applying filter hook '{hook_name}' callback '{callback.__name__}': {e}",
|
|
|
exc_info=True #wr 记录完整的异常堆栈信息
|
|
|
)
|
|
|
#wr 返回最终处理后的值（若没有回调，直接返回初始值）
|
|
|
return value |
