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): ...

bind_owner(fn: Callable[_P, _T]) -> Callable[_P, _T]

将函数绑定到创建时的 owner 上下文("谁创建谁运行")

装饰/包装瞬间捕获 current_owner,此后无论谁、从哪个线程或事件循环 调用返回的包装函数,都以原 owner 身份执行(进入时 set、退出时 reset)。

用于回调与线程入口:新线程默认空上下文,Timer 线程 / watcher 线程等 无上下文的触发路径 current_owner 为 None,其内创建的任务不进 归属表、模块卸载时不取消(跨 loop 残留的来源之一)——经本函数包装后 归属随身携带,不再流失。owner_scope 作用于代码块,本函数把上下文 "缝进"函数本身。

async 函数保持 async,且 owner 跨全部 await 生效;普通函数 仅在调用同步执行期间生效(返回 awaitable 但非 coroutine function 的 函数,其 awaitable 执行阶段不携带 owner)。

  • fn: 待绑定的同步/异步函数

返回值: 同签名包装函数(调用期间 current_owner = 包装时捕获值)

示例:

# 回调交给无线程上下文的调度器 / 线程池前,先把归属缝进函数:
scheduler.submit(bind_owner(self._poll))

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_event_account() -> str

获取当前事件处理链路的触发账户标识

在事件分发 / handler 执行期间可读取,Send / Api 链路未显式指定账户时 据此兜底绑定;不在事件处理上下文内(如后台定时任务)返回空字符串。

返回值: 当前触发账户标识或空字符串

示例:

account = get_current_event_account()

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