ErisPulse.Core.master 模块
模块概述
框架主人管理系统
提供统一的用户主人身份识别能力,供命令系统(master 参数)
及业务层(master.is_master())使用。
主人配置位于 ErisPulse.master.users,支持两种格式:
- dict(按平台指定):
{"yunhu": ["123"], "telegram": ["456"]} - list(全局主人,所有平台生效):
["123", "456"]
除内置身份源(配置 + 运行时增删)外,还支持通过
master.provider 注册自定义身份源,实现可插拔的身份判定
(如对接适配器管理员接口、数据库角色等)。
提示
- 通过
from ErisPulse.Core import master导入单例master.is_master(event)或master.is_master(platform, user_id)检查身份- 支持运行时
master.add()/master.remove()动态增删(不持久化到配置文件)@master.provider注册自定义身份源,任一 provider 放行即认定为主人; 注销用fn.unregister()
类列表
class MasterManager
框架主人管理器(单例)
从配置读取主人列表,并支持运行时增删。
主人检查同时考虑配置中的主人、运行时添加的主人,
以及通过 :meth:provider 注册的自定义身份源(provider 链)。
提示
- 默认身份源:
ErisPulse.master.users配置 + 运行时add()记录@master.provider可注册自定义身份源,fn(platform, user_id) -> bool,任一 provider 放行即认定为主人- provider 异常会被捕获并跳过(不阻断身份判定链)
方法列表
_load_config_masters() -> tuple[dict[str, set[str]], set[str]]
从配置加载主人列表
返回值: (platform_masters, global_masters)
- platform_masters: {platform: {user_id, ...}}
- global_masters: {user_id, ...}
is_master(platform_or_event: str | _EventLike, user_id: str | None = None) -> bool
检查是否为框架主人
支持两种调用方式:
master.is_master(event)— 从事件对象提取 platform 和 user_idmaster.is_master(platform, user_id)— 显式指定
检查范围:配置中的主人 + 运行时添加的主人 + 已注册的 provider 链。 全局主人(配置为 list 或运行时添加为 None 平台)对所有平台生效。
- platform_or_event: 平台名称 或 事件对象
- user_id: 用户 ID(当第一个参数为平台名时使用)
返回值: 是否为框架主人
示例:
from ErisPulse.Core import master
# 从事件检查
if master.is_master(event):
await event.reply("主人你好")
# 显式检查
if master.is_master("yunhu", "123456"):
print("是主人")
_check_providers(platform: str, user_id: str) -> bool
内部方法 依次尝试 provider 链,任一放行即认定为主人
provider 异常被捕获并跳过(记录 warning),不阻断后续判定。
- platform: 平台名称
- user_id: 用户 ID
返回值: 是否有 provider 认定该用户为主人
provider(fn: MasterProvider) -> MasterProvider
注册自定义身份源 provider(装饰器 / 函数调用两用)
签名:fn(platform: str, user_id: str) -> bool,返回 True 表示
认定该用户为主人。所有 provider 在内置身份源(配置 + 运行时记录)
未命中时依次尝试,任一放行即认定为主人。
注册后原函数会挂上 fn.unregister(),调用即可撤销该 provider。
provider 归属自动记录:若在模块 owner 上下文(如模块 on_load)
内注册,模块卸载时会被框架自动注销(无需手动 unregister);
模块级装饰器用法(非加载上下文)为常驻身份源,仅显式注销。
fn: 身份源检查函数(普通函数 / 模块级函数皆可挂
unregister;绑定实例方法请用模块级函数或在注册后自行保存注销句柄)
返回值: 原函数(已注册,并尽可能挂载 unregister 方法)
示例:
from ErisPulse.Core import master
# 装饰器用法(常驻身份源,推荐)
@master.provider
def admin_provider(platform, user_id):
return user_id in {"999"} # 自定义判定逻辑
master.is_master("yunhu", "999") # True
admin_provider.unregister() # 不再需要时注销
# 函数式用法(模块加载期注册、卸载期注销)
fn = master.provider(admin_provider)
fn.unregister()
_drop_provider(fn: MasterProvider) -> None
内部方法 从 provider 链移除指定函数(幂等)
- fn: 已注册的 provider 函数
unregister_by_owner(owner: str) -> int
注销指定 owner(模块)注册的全部 provider
模块在加载上下文(on_load)内注册的 provider 会由框架在卸载时 自动调用本方法,实现作用域清理——模块开发者无需在 on_unload 手动注销。
- owner: 模块名(owner)
返回值: 注销的 provider 数量
list() -> dict[str, list[str]]
获取所有主人列表
返回值: 字典,{"global": [...], "<platform>": [...]}
global 键包含对所有平台生效的主人
add(platform: str | None, user_id: str, persist: bool = True) -> None
添加主人
platform: 平台名称,None 表示全局主人
user_id: 用户 ID
persist: 是否持久化到配置文件 (默认: True)
为 True 时写入 ``ErisPulse.master.users`` 配置,重启后仍然生效; 为 False 时仅运行时生效,重启后失效。
示例:
from ErisPulse.Core import master
master.add("yunhu", "123456") # 持久化到配置
master.add("yunhu", "999", persist=False) # 仅本次运行有效
master.add(None, "888") # 全局主人
remove(platform: str | None, user_id: str, persist: bool = True) -> bool
移除主人
platform: 平台名称,None 表示全局
user_id: 用户 ID
persist: 是否持久化移除 (默认: True)
为 True 时同时从配置文件中移除; 为 False 时仅移除运行时记录。
返回值: 是否成功移除(不存在则返回 False)
示例:
from ErisPulse.Core import master
master.remove("yunhu", "123456") # 持久化
master.remove("yunhu", "999", persist=False) # 仅运行时
reset() -> None
清空所有运行时主人与已注册的 provider(用于测试或软重启)
注意:不影响配置文件中的主人。 软重启时模块会被重新加载,provider 持有的旧引用一并清空, 由模块在新生命周期中重新注册。