melobot.session

会话层部件

class melobot.session.Session

基类：object

会话

变量:

• store (SessionStore) -- 当前会话上下文的会话存储

• rule (Rule) -- 当前会话上下文的会话规则

stop_keep() → None

停止会话保持

当进入会话时，启用了 keep=True， 需要在会话不需要保持后，手动调用此方法标识会话可以销毁

返回类型:

None

release(*events: Event) → None

释放对会话中事件的控制。允许它们参与“传播评估”。

事件是否可以向更低优先级传播，需要在同级的所有处理流完成后进行评估。同级所有处理流完成后， 如果事件为“不可传播”状态（event.spread = False），则不会向更低优先级传播。

而会话必须存在于一个正在运行的处理流程中。对于会话中的事件，存在两种情况：

1. 事件在会话挂起后，实际上就不再被需要（会话期待一个新的事件来继续处理流程）。 那么挂起后，事件就应该允许参与传播评估。 2. 事件在会话挂起后，仍然可能被需要（会话在下一阶段，仍然需要这个事件的信息）。 那么挂起后，事件还不应该参与传播评估。

melobot 将第一种情景视为默认情况（即使用 enter_session() 时，auto_release=True）， 此时每次挂起后，自动调用此方法释放对于事件的控制，允许它们参与传播评估。值得注意的是，此方法意为“释放”， 传播评估**需要在当前事件的处理流程结束之后才会进行**。

如果设置了 auto_release=False，则在挂起后保留对于事件的控制，需要手动调用此方法。 而设置了 keep=True 时，无论 auto_release 如何设置，都需要手动调用此方法。

总结：一般情况下无需使用此方法。但如果启用了会话，且需要更精准地控制事件的传播时机，可以考虑使用此方法。

参数:

events (Event) -- 事件对象。如果不提供，则释放会话历史中所有未释放的事件

返回类型:

None

class melobot.session.SessionStore

基类：dict[Hashable, Any]

会话存储，生命周期伴随会话对象

set(key: Hashable, value: Any) → None

参数:

• key (Hashable)

• value (Any)

返回类型:

None

class melobot.session.Rule

基类：BetterABC, Generic[EventT]

会话规则

对于更复杂的情况，可以继承此类，在子类中结合状态信息实现更动态的会话判断

static new(meth: Callable[[EventT, EventT], bool]) → Rule[EventT]

从可调用对象创建一个新的会话规则对象

参数:

meth (Callable[[EventT, EventT], bool]) -- 用于会话判断的可调用对象

返回:

会话规则

返回类型:

Rule[EventT]

async compare(e1: EventT, e2: EventT) → bool

会话判断的方法

抽象方法，和 compare_with() 二选一实现

参数:

• e1 (EventT) -- 某一已存在的会话中的事件

• e2 (EventT) -- 待判断的事件

返回:

为 True 则在一个会话中，反之亦然

返回类型:

bool

async compare_with(info: CompareInfo[EventT]) → bool

会话判断的方法

抽象方法，和 compare() 二选一实现

参数:

info (CompareInfo[EventT]) -- 用于会话判断的信息

返回:

为 True 则在一个会话中，反之亦然

返回类型:

bool

class melobot.session.CompareInfo

基类：Generic[EventT]

用于会话判断的信息

session: Session

old_event: EventT

new_event: EventT

class melobot.session.DefaultRule

基类：Rule[Event]

传统的会话规则

判断事件的 scope 是否相同

melobot.session.enter_session(rule: Rule, wait: bool = True, nowait_cb: SyncOrAsyncCallable[(), None] | None = None, keep: bool = False, auto_release: bool = True) → _AsyncGeneratorContextManager[Session]

上下文管理器，提供一个会话上下文，在此上下文中可使用会话的高级特性

参数:

• rule (Rule) -- 会话规则

• wait (bool) -- 当出现会话冲突时，是否需要等待

• nowait_cb (SyncOrAsyncCallable[(), None] | None) -- 指定了 wait=False 后，会话冲突时执行的回调

• keep (bool) -- 会话在退出会话上下文后是否继续保持

• auto_release (bool) -- 当前会话挂起后，事件是否自动释放。其他有关细节参考 Session.release()

Yield:

会话对象

返回类型:

_AsyncGeneratorContextManager[Session]

会话状态

async melobot.session.suspend(timeout: float | None = None, auto_stop: bool = False) → bool

挂起当前会话

参数:

• timeout (float | None) -- 挂起后再唤醒的超时时间, 为空则永不超时

• auto_stop (bool) -- 如果挂起超时，是否自动停止当前事件的处理流

返回:

如果为 False 则表明唤醒超时

返回类型:

bool

melobot.session.get_session() → Session

获取当前上下文中的会话

返回:

会话

返回类型:

Session

melobot.session.get_rule() → Rule

获取当前上下文中的会话规则

返回:

会话规则

返回类型:

Rule

melobot.session.get_session_store() → SessionStore

获取当前上下文中的会话存储

返回:

会话存储

返回类型:

SessionStore

依赖注入项

melobot.session.get_session_arg(arg_idx: Hashable) → Any

获取会话存储中的值

参数:

arg_idx (Hashable) -- 键索引

返回:

对应的依赖项

返回类型:

Any

上下文动态变量

melobot.session.session

当前上下文中的会话，类型为 Session

melobot.session.s_store

当前上下文中的会话存储，类型为 SessionStore

melobot.session.rule

当前上下文中的规则，类型为 Rule