melobot.session

会话层部件

class melobot.session.Session

基类：object

会话

变量:

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

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

stop_keep() → None

停止会话保持

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

返回类型:

None

set_completed(event: Event | None = None) → None

标志会话中的事件为完成状态

event 参数为空，自动标志会话历史中所有事件为完成状态

事件被标志为完成状态后，事件才可能向更低优先级传播。但具体是否可以， 还和其他处理流的操作有关

举例来说，假设一个事件触发了一批处理流，如果这批处理流都没有启用会话， 处理流结束后，将会自动标志事件“完成”。事件是否可以传播， 将在所有处理流完成后评估

但如果这批处理流中有启用会话的，由于会话是可以挂起的， 这意味着非常长的处理周期，因此需要会话来标志事件“完成”， 这样后续的传播评估才能在合适的时机进行

使用 enter_session() 进入会话时，设置 auto_complete=True， 会话将在每次挂起后，自动标志当前事件为完成状态，这样事件就不会被会话“囚禁”， 而迟迟无法传播到下一优先级。而设置为 False，则需要手动调用此方法来标志“完成”

参数:

event (Event | None) -- 事件

返回类型:

None

get_incompletions() → list[tuple[Event, Future]]

获取会话历史中所有未完成的事件组

返回:

元组 (事件, 事件“完成”的信号) 组成的列表

返回类型:

list[tuple[Event, Future]]

class melobot.session.SessionStore

基类：dict[str, Any]

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

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

参数:

• key (str)

• 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_complete: bool = True) → _AsyncGeneratorContextManager[Session]

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

参数:

• rule (Rule) -- 会话规则

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

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

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

• auto_complete (bool) -- 当前会话挂起后，事件是否自动标记为“完成”状态。其他有关细节参考 Session.set_completed()

Yield:

会话对象

返回类型:

_AsyncGeneratorContextManager[Session]

会话状态

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

挂起当前会话

参数:

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

返回:

如果为 False 则表明唤醒超时

返回类型:

bool

melobot.session.get_session() → Session

获取当前上下文中的会话

返回:

会话

返回类型:

Session

melobot.session.get_rule() → Rule

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

返回:

会话规则

返回类型:

Rule

melobot.session.get_session_store() → SessionStore

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

返回:

会话存储

返回类型:

SessionStore

上下文动态变量

melobot.session.session

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

melobot.session.s_store

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

melobot.session.rule

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