ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

ErisPulse.runtime.context 模块


模块概述

ErisPulse 运行时上下文

提供 contextvars 基础设施,用于追踪事件处理器、路由等资源的归属者。 在模块/适配器加载期间设置当前 owner,使资源注册能自动标记来源, 从而支持按模块精确清理(热禁用、热重载)。

提示 使用方式:

from ErisPulse.runtime.context import owner_scope, get_current_owner
# 或通过 SDK:sdk.context.owner_scope(...) / sdk.context.get_current_owner()

# 在指定 owner 上下文下执行代码块(自动复位)
with owner_scope("Dashboard"):
    # 注册的 handler 会自动打上 owner="Dashboard"
    pass

# 读取当前 owner
owner = get_current_owner()  # 返回 "Dashboard" 或 None

函数列表

owner_scope(owner: str | None)

在指定 owner 上下文下执行代码块(退出时自动复位 current_owner)

模块/适配器在非加载场景下注册资源(命令/事件处理器/路由/生命周期钩子)时, 可用本上下文管理器让资源自动归属到指定 owner,从而被作用域过滤与按 owner 清理识别。 比手写 token = current_owner.set(...); try/finally: reset 更简洁安全。

  • owner: 资源归属者(模块名或适配器平台名),None 表示清除当前 owner

示例:

with owner_scope("MyModule"):
    @command("hello")
    async def hello(event): ...

get_current_owner() -> str | None

获取当前资源归属者(模块名或适配器平台名)

在事件处理器 / 命令 / 钩子执行期间,框架已注入对应模块或适配器的 owner, 可用于日志归因、权限判断等。

返回值: 当前 owner,不在任何加载/执行上下文时返回 None

示例:

owner = get_current_owner()

get_current_caller() -> str | None

获取当前跨模块调用的调用方身份(模块名或适配器平台名)

经 sdk.module.call() 被调用期间,current_owner 已归因到目标 模块(自己的代码归属自己),而调用方身份保留在本上下文中——被调方 可据此识别"谁在调用我"。直接属性访问(sdk.Cron.once(...))不经 此上下文,此时调用方身份即 get_current_owner()。

返回值: 调用方身份,非 module.call 调用链或框架层调用时返回 None

示例:

caller = get_current_caller()  # "OrderModule" 或 None

get_handler_waits() -> list[dict[str, Any]] | None

获取当前 handler 的 wait_reply 调用记录(slow-log 归因用)

返回值: 记录列表或 None(不在 handler / Task 上下文内)


get_current_trace_id() -> str | None

获取当前事件处理链路的追踪 ID(trace-id)

在事件分发 / handler 执行 / 出站发送期间可读取,用于跨模块日志关联; 不在事件处理上下文内(如后台定时任务)返回 None。

返回值: 当前 trace-id 或 None

示例:

trace_id = get_current_trace_id()

get_send_receipts() -> list[dict[str, str]] | None

获取当前消息事务的回执账本

仅在 Event.message_tx() 事务内返回非 None; 可用于查看本次事务已发送了哪些消息。

返回值: 回执记录列表或 None(不在事务内)

示例:

receipts = get_send_receipts()