后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载nonebot.typing是 NoneBot2 框架中承载共享类型的公共模块它集中定义了事件处理状态、各类钩子函数Bot 连接、API 调用、事件预处理等、规则/权限检查器、会话更新器以及依赖缓存的类型别名与底层类型工具函数。本文以 2.4.4 版本文档typing.md为主线结合当前仓库源码nonebot/typing.py及其调用方实现逐项讲解每个类型与函数的作用、签名、依赖参数与底层调用链帮助你在编写插件、自定义钩子或适配器时正确使用这些类型。模块定位为框架各模块共享的类型立规矩nonebot.typing模块的定位非常纯粹定义 NoneBot 各模块之间共享的类型。它不包含业务逻辑而是为整个框架提供统一的类型词汇表让事件响应器Matcher、规则Rule、权限Permission、钩子系统、依赖注入等模块在相互协作时有一致的类型契约。从源码可见nonebot/typing.py该模块完全遵循 Python 官方类型标准使用 PEP 484类型注解、PEP 526变量注解语法并基于标准库typing构建。多数类型别名通过TypeAlias声明并辅以丰富的 docstring 说明其允许的依赖参数。模块内定义的实体大致可分为四类类别成员用途底层类型工具函数overrides、type_has_args、origin_is_union、origin_is_literal、all_literal_values、origin_is_annotated、is_none_type、is_type_alias_type、evaluate_forwardref供框架内部解析类型注解事件处理状态StateFlag、T_State会话/事件处理中的状态字典类型钩子与处理器类型T_BotConnectionHook、T_BotDisconnectionHook、T_CallingAPIHook、T_CalledAPIHook、T_EventPreProcessor、T_EventPostProcessor、T_RunPreProcessor、T_RunPostProcessor、T_RuleChecker、T_PermissionChecker、T_Handler、T_TypeUpdater、T_PermissionUpdater各生命周期回调的签名契约依赖缓存T_DependencyCache依赖注入结果缓存底层类型工具函数框架解析类型注解的工具箱nonebot.typing提供的这一组纯函数用于在运行时判断、解析各种 PEP 484/526 类型构造它们是框架内部实现依赖注入、参数解析的基础设施普通插件开发者一般不会直接调用但理解它们有助于把握 NoneBot 的参数注入机制。overrides(InterfaceClass)说明标记一个方法为父类 interface 的 implement。参数InterfaceClass(object)返回untyped需要注意当前源码中该函数已进入弃用流程调用时会发出DeprecationWarning提示改用typing_extensions.override对应 PEP 698参见 nonebot/typing.py。在框架内部如 nonebot/internal/params.py各参数注入类重写_check_param时已直接使用typing_extensions.override。type_has_args(type_)参数type_(type[Any])返回bool判断一个类型对象是否携带类型参数即泛型实例实现为检查isinstance(type_, (t._GenericAlias, types.GenericAlias, types.UnionType))nonebot/typing.py。例如list[int]、dict[str, Any]均携带参数而裸的list不携带。origin_is_union(origin)参数origin(type[Any] | None)返回bool判断某个类型的 origin 是否为 Union 类型同时兼容typing.Union与types.UnionType即 Python 3.10 的X | Y语法nonebot/typing.py。这保证了框架同时支持旧式Union[A, B]与新式A | B两种写法。origin_is_literal(origin)与all_literal_values(type_)说明origin_is_literal判断是否是Literal类型all_literal_values获取Literal类型包含的所有值。参数origin(type[Any] | None)type_(type[Any])返回boollist[Any]origin_is_literal同时兼容typing.Literal与typing_extensions.Literalnonebot/typing.py。all_literal_values则递归展开Literal的所有取值如果类型不是Literal直接返回[type_]否则对其每个类型参数递归收集nonebot/typing.py从而支持Literal[1, 2, Literal[3]]这类嵌套写法。origin_is_annotated(origin)说明判断是否是Annotated类型。参数origin(type[Any] | None)返回bool实现对typing_extensions.Annotated的 origin 判断nonebot/typing.py。Annotated在 NoneBot 中有特殊用途T_State正是借助Annotated携带一个标记对象供参数注入识别详见下文T_State一节。is_none_type(type_)说明判断是否是None类型。参数type_(type[Any])返回bool实现为成员判断type_ in NONE_TYPES其中NONE_TYPES覆盖了None、type(None)、Literal[None]typing 与 typing_extensions 两个版本以及types.NoneTypenonebot/typing.py保证各写法下都能正确识别。is_type_alias_type(type_)参数type_(type[Any])返回bool判断是否为TypeAliasType类型。实现针对 Python 版本做了分支3.12 之前仅检查typing_extensions.TypeAliasType3.12 同时检查标准库typing.TypeAliasTypenonebot/typing.py。evaluate_forwardref(ref, globalns, localns)参数ref(ForwardRef)globalns(dict[str, Any])localns(dict[str, Any])返回Any求值一个前向引用ForwardRef。源码中特别说明Python 3.13 / 3.12.4 将recursive_guard变为关键字参数因此显式以recursive_guardfrozenset()命名调用ref._evaluate(globalns, localns, recursive_guardfrozenset())以兼容不同 Python 版本nonebot/typing.py。StateFlag与T_State带标记的事件处理状态StateFlagclass一个无字段的标记类其__repr__返回StateFlag()。它本身不承载数据仅作为哨兵对象存在。T_Statevar类型为dict[Any, Any]说明为事件处理状态 State 类型。源码实现为_STATE_FLAG StateFlag() T_State: TypeAlias t.Annotated[dict[t.Any, t.Any], _STATE_FLAG]这是Annotated在 NoneBot 中最典型的应用T_State本质是dict[Any, Any]但通过Annotated附加了一个_STATE_FLAG标记。这样参数注入系统无需依赖字符串比较即可精确识别类型为T_State的参数——在 nonebot/internal/params.py 中StateParam._check_param正是通过origin_is_annotated(get_origin(param.annotation))且_STATE_FLAG in get_args(param.annotation)来判定注入的if origin_is_annotated(get_origin(param.annotation)) and _STATE_FLAG in get_args(param.annotation): return cls() # legacy: param is named state and has no type annotation elif param.annotation param.empty and param.name state: return cls()这同时保证了向后兼容即使不写类型注解只要参数名为state也能注入。从源码注释看使用Annotated标记还有一个目的避免 Python 3.11 中ForwardRef重新创建泛型类型的问题nonebot/typing.py。T_State贯穿整个事件处理链路在 nonebot/message.py 中每个事件处理都会创建一个state: dict[Any, Any] {}Matcher.run的_default_state也声明为ClassVar[T_State]nonebot/internal/matcher/matcher.py事件响应器实例化时通过self._default_state.copy()初始化状态。_DependentCallable同步/异步双兼容的可调用类型虽然_DependentCallable以下划线开头私有类型不在文档公开列表中但它是理解整组类型别名的关键_DependentCallable: TypeAlias t.Callable[..., T] | t.Callable[..., t.Awaitable[T]]它表示一个返回T或Awaitable[T]的可调用对象——即同时接受同步函数与异步函数。NoneBot 中所有处理器/钩子函数都既可以是普通def也可以是async def框架在调用时会通过is_coroutine_callable判断并自动适配同步函数经run_sync包装执行nonebot/dependencies/init.py。这正是T_RuleChecker、T_Handler等类型能以同一签名兼容两种函数为底层原因。钩子类型族一Bot 生命周期与 API 调用钩子T_BotConnectionHook与T_BotDisconnectionHook类型_DependentCallable[Any]说明Bot 连接建立/断开时执行的钩子函数。两者允许的依赖参数完全相同DependParam子依赖参数BotParamBot 对象DefaultParam带有默认值的参数对应的装饰器是Driver.on_bot_connect与Driver.on_bot_disconnectnonebot/internal/driver/abstract.py它们内部以BOT_HOOK_PARAMS [DependParam, BotParam, DefaultParam]即文档列出的三种依赖参数解析并存储钩子。实际触发链路为_bot_connect/_bot_disconnect在连接建立/断开时被调用钩子通过anyio任务组并发执行并支持AsyncExitStack上下文与dependency_cache共享nonebot/internal/driver/abstract.py。因此钩子函数中可以声明bot: Bot参数直接拿到当前 Bot也可以Depends()声明子依赖还可以带默认值参数。T_CallingAPIHook类型(Bot, str, dict[str, Any]) - Awaitable[Any]说明bot.call_api钩子函数在真正调用 API 之前执行。对应Bot.on_calling_api装饰器nonebot/internal/adapter/bot.py三个位置参数分别为 bot、API 名称str、API 参数字典dict[str, Any]。在Bot.call_api的调用链中nonebot/internal/adapter/bot.py该钩子支持抛MockApiException来模拟 API 结果一旦某个 hook 抛出该异常框架会跳过真实 API 调用直接返回异常中携带的 result——这是测试中 mock 机器人 API 的官方机制。T_CalledAPIHook类型(Bot, Exception | None, str, dict[str, Any], Any) - Awaitable[Any]说明bot.call_api后执行的函数参数分别为 bot、exception、api、data、result。对应Bot.on_called_apinonebot/internal/adapter/bot.py。与 Calling 钩子不同它多出exceptionAPI 调用异常可能为 None与resultAPI 返回值两个参数且同样支持通过MockApiException改写返回值。典型用途包括记录 API 调用结果、统一处理错误、在测试中拦截并替换返回数据。钩子类型族二事件与响应器运行时的四类处理器文档将事件处理流程中的钩子细分为四类其依赖参数集合逐级递增精确对应 nonebot/message.py 中定义的EVENT_PCS_PARAMS、RUN_PREPCS_PARAMS、RUN_POSTPCS_PARAMS三组允许参数。T_EventPreProcessor/T_EventPostProcessor类型_DependentCallable[Any]说明事件预处理/后处理函数类型。允许依赖参数DependParam子依赖参数BotParamBot 对象EventParamEvent 对象StateParamState 对象DefaultParam带有默认值的参数对应nonebot.message模块的event_preprocessor/event_postprocessor装饰器nonebot/message.py。事件预处理在事件分发到各响应器之前执行若其中抛出IgnoredException则该事件被忽略、不再分发见_apply_event_preprocessors的实现nonebot/message.py事件后处理在分发完成后执行。T_RunPreProcessor/T_RunPostProcessor类型_DependentCallable[Any]说明事件响应器运行前/后处理函数类型。T_RunPreProcessor允许依赖参数DependParam、BotParam、EventParam、StateParam、MatcherParamMatcher 对象、DefaultParamT_RunPostProcessor在T_RunPreProcessor基础上额外允许ExceptionParam异常对象可能为 NoneDependParam、BotParam、EventParam、StateParam、MatcherParam、ExceptionParam、DefaultParam对应run_preprocessor/run_postprocessor装饰器nonebot/message.py。运行前处理在Matcher.run执行前触发可抛出IgnoredException取消本次运行运行后处理则接收响应器运行中捕获的异常nonebot/message.py因此后处理函数可以这样声明异常参数from nonebot import run_postprocessor run_postprocessor async def log_exception( matcher: Matcher, exception: Exception | None, ): if exception: logger.error(fMatcher {matcher} 运行失败: {exception!r})ExceptionParam的实现见 nonebot/internal/params.py它解析类型为Exception或其子类或None的参数也兼容无注解但名为exception的参数。规则与权限检查器T_RuleChecker与T_PermissionCheckerT_RuleChecker类型_DependentCallable[bool]说明RuleChecker 即判断是否响应事件的处理函数。允许依赖参数DependParam、BotParam、EventParam、StateParam、DefaultParam它对应 nonebot/internal/rule.py 中Rule.HANDLER_PARAM_TYPES的[DependParam, BotParam, EventParam, StateParam, DefaultParam]。Rule在__init__中通过Dependent[bool].parse(callchecker, allow_typesself.HANDLER_PARAM_TYPES)解析每个检查器。规则语义为与AND所有检查器返回 True 才通过且Rule之间只允许合并|会抛出RuntimeError。由于检查器可以Depends()子依赖、携带默认值参数规则函数也能复用框架的依赖注入能力。T_PermissionChecker类型_DependentCallable[bool]说明PermissionChecker 即判断事件是否满足权限的处理函数。允许依赖参数DependParam、BotParam、EventParam、DefaultParam注意与T_RuleChecker的差别不包含StateParam——权限判断与事件状态无关。这与 nonebot/internal/permission.py 中Permission.HANDLER_PARAM_TYPES [DependParam, BotParam, EventParam, DefaultParam]完全一致。权限语义为或OR任一检查器通过即满足权限nonebot/internal/permission.py且Permission之间用|合并不被允许。典型的权限检查器写法如只允许特定会话触发from nonebot.permission import Permission from nonebot.typing import T_PermissionChecker async def only_admin(bot: Bot, event: Event) - bool: # 返回是否满足管理员条件 return ... matcher on_command(admin, permissionPermission(only_admin))会话控制更新器T_TypeUpdater与T_PermissionUpdaterT_TypeUpdater类型_DependentCallable[str]说明在Matcher.pause、Matcher.reject时被运行用于更新响应的事件类型默认会更新为message。允许依赖参数DependParam、BotParam、EventParam、StateParam、MatcherParam、DefaultParam。对应Matcher.type_updater类装饰器nonebot/internal/matcher/matcher.py它把函数解析为Dependent[str]存入_default_type_updater。在Matcher.update_type中nonebot/internal/matcher/matcher.py如果没有注册更新器则直接返回字符串messagereturn ( await updater(botbot, eventevent, stateself.state, matcherself, ...) if updater else message )T_PermissionUpdater类型_DependentCallable[Permission]说明在Matcher.pause、Matcher.reject时被运行用于更新会话对象权限默认会更新为当前事件的触发对象。允许依赖参数DependParam、BotParam、EventParam、StateParam、MatcherParam、DefaultParam。对应Matcher.permission_updaternonebot/internal/matcher/matcher.py。默认实现update_permission在没有更新器时返回Permission(User.from_event(event, permself.permission))nonebot/internal/matcher/matcher.py——即把会话权限收敛到当前事件触发者本人。这两个更新器与pause/reject的配合发生在Matcher.run的异常分支当捕获到RejectedException或PausedException时框架会先update_type再update_permission然后以priority0、tempTrue、blockTrue创建一个新的临时响应器接管后续会话nonebot/internal/matcher/matcher.py从而实现暂停会话等用户下一条消息的交互能力。这与文档中默认会更新为message、默认会更新为当前事件的触发对象的描述一一对应。T_DependencyCache依赖缓存类型类型dict[_DependentCallable[Any], DependencyCache]说明依赖缓存用于存储依赖函数的返回值。DependencyCache类定义于 nonebot/internal/params.py包含PENDING/FINISHED两种状态可保存结果或异常并通过anyio.Event支持并发等待。T_DependencyCache是以依赖函数为键、以缓存对象为值的字典。缓存的作用贯穿整个事件处理链路在handle_event中每个事件处理创建一个dependency_cache: T_DependencyCache {}nonebot/message.py随stack一起传入各级检查器、处理器与钩子在DependParam._solve中nonebot/internal/params.py当use_cacheTrue且call in dependency_cache时直接await dependency_cache[call].wait()复用结果避免同一事件内重复计算子依赖。因此如果你在一个处理器里多次Depends同一个函数默认情况下该函数只会执行一次这正是Depends(use_cacheTrue)默认行为的底层实现。综合示例在一个插件中运用多个共享类型将上述类型串联起来一个典型的插件可以同时涉及状态、规则、处理器与钩子from typing import Any from nonebot import on_command, run_preprocessor, event_preprocessor from nonebot.matcher import Matcher from nonebot.adapters import Bot, Event from nonebot.typing import T_State # T_State 注入事件处理状态 on_command(demo).handle() async def demo_handler(bot: Bot, event: Event, state: T_State): state[visited] True # 写入状态 await bot.send(event, ok) # T_RunPreProcessor 风格的运行前钩子MatcherParam 可注入 run_preprocessor async def before_run(matcher: Matcher, bot: Bot, event: Event): ... # T_EventPreProcessor 风格的事件预处理StateParam 可注入 event_preprocessor async def before_event(bot: Bot, event: Event, state: T_State): ...小结nonebot.typing是理解 NoneBot2 内部协作机制的一把钥匙底层工具函数负责在运行时解析Union、Literal、Annotated、ForwardRef等类型构造支撑依赖注入系统T_State借助Annotated标记实现精确的状态参数注入_DependentCallable让所有处理器/钩子统一支持同步与异步两种写法十余个T_*类型别名精确规定了每个生命周期钩子可注入的依赖参数集合与 nonebot/internal/driver/abstract.py、nonebot/internal/adapter/bot.py、nonebot/message.py、nonebot/internal/rule.py、nonebot/internal/permission.py 等实现中的HANDLER_PARAM_TYPES/*_PARAMS常量一一对应。编写插件时按文档标注的依赖参数声明钩子与检查器即可获得完整的依赖注入能力深入阅读 nonebot/typing.py 与上述调用方源码则能进一步理解参数解析、缓存复用与会话暂停/拒绝等机制的底层原理。赞分享后端即时通讯【免费下载链接】nonebot2跨平台 Python 异步聊天机器人框架 / Asynchronous multi-platform chatbot framework written in Python项目地址https://gitcode.com/gh_mirrors/no/nonebot2点击查看免费下载相关推荐用 VoxCPM ZipEnhancer 给参考音频降噪的实操方法3步让克隆更干净用 VoxCPM ZipEnhancer 给参考音频降噪的实操方法3步让克隆更干净 这篇 VoxCPM 实操只讲一件事内置的音频增强器 ZipEnhance后端即时通讯Roc 编译器类型依赖分析Tag 构造器名称为何不计入类型别名依赖Roc 编译器类型依赖分析Tag 构造器名称为何不计入类型别名依赖 本篇文章基于 Roc 编译仓库项目定位A fast, friendly, functiReScript Compiler类型系统高级特性泛型与模块签名ReScript Compiler类型系统高级特性泛型与模块签名 ReScript是一种强类型语言它编译为高效且人类可读的JavaScript。其类型系统是编译器编程语言开发工具上一篇MessageKit状态管理指南处理加载、错误和空状态的终极教程下一篇SCAIL社区精选案例用14B模型实现动漫角色、手绘风格与四足动物动画的神奇效果创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考