DOCSEARCHbyAlgolia
Submit Docs

NoneBot Documentation

website·Indexed 33 days ago

https://nonebot.dev/

A plugin-based framework for building bots. The documentation covers core components like Matchers, Rules, and Permissions, as well as adapter writing, plugin development, and integration with tools like NB-CLI, Alconna, and NoneBug for unit testing. It provides guides for version 2.4.4, 2.5.0, and the 'Next' version, including best practices for database management via nonebot-plugin-orm and deployment.

Tokens
298.3K
Snippets
1.7K
Records
2.2K
Agent score
64%

What's inside NoneBot

  1. Overview of NoneBot Dependency Injection

    NoneBot uses a dependency injection system to provide context information (like the current Bot, Event, and State) to event handlers. This system consists of two phases: parameter parsing (where function arguments are analyzed to identify dependencies and converted into Dependent objects) and execution (where the identified dependencies are resolved and their return values are passed into the handler).

    Crucially, type annotations are used to determine which dependency to inject. If the type annotation does not match the actual data type provided, the handler will be skipped due to the overload mechanism. For debugging dependency resolution, set the log-level configuration to TRACE.

  2. Overview of NoneBot Event Responders (Matchers)

    An Event Responder (Matcher) is the basic unit used to respond to received events in NoneBot. All responders inherit from the Matcher base class. They function by filtering events based on specific rules and processing them through predefined dependencies.

  3. Overview of NoneBot Event Responders (Matchers)

    An Event Responder (Matcher) is the basic unit for responding to received events in NoneBot. All event responders inherit from the Matcher base class. They function by filtering events based on specific rules and processing them through predefined dependencies.

  4. Overview of NoneBot Exception Hierarchy

    The nonebot.exception module contains all exceptions that may be thrown during NoneBot runtime. Many of these are caught internally by NoneBot to trigger specific behaviors. The hierarchy is as follows:

    • NoneBotException (Base)
      • ParserExit
      • ProcessException
        • IgnoredException
        • SkippedException
          • TypeMisMatch
        • MockApiException
        • StopPropagation
      • MatcherException
        • PausedException
        • RejectedException
        • FinishedException
      • AdapterException
        • NoLogException
        • ApiNotAvailable
        • NetworkError
        • ActionFailed
      • DriverException
        • WebSocketClosed

  5. Overview of nonebot-plugin-alconna

    The nonebot-plugin-alconna plugin enhances NoneBot development through three main components:

    1. Enhanced Command Parsing: Provides the on_alconna event responder helper based on the Alconna library, offering more powerful parsing capabilities than on_command, on_shell, or on_regex.
    2. Universal Message Components: Implements cross-platform message handling including:
      • UniMessage: A universal message model for conversion, export, and sending across adapters.
      • Text, Image, At: Universal message segment models.
      • Functional helpers: message_recall, message_edit, and message_reaction.
      • Target: A universal target model for proactive message sending.
      • Dependency injections and Rules: UniMsg, MsgId, MsgTarget, at_in, and at_me.
    3. Built-in Functional Plugins: Includes echo (echoes messages), help (lists Alconna responder help), lang (switches Alconna language), switch (enables/disables commands), and with (loads command headers for sub-commands in a session).

  6. Overview of NoneBot Dependency Injection

    NoneBot uses a dependency injection system to provide context information (like the current Bot, Event, and Matcher) to event handlers. This keeps code clean and reusable. The system consists of two phases: Parameter Parsing (identifying dependencies and generating Dependent objects) and Execution (injecting the resolved values into the function).

    Critical Note: Type annotations are essential. If the type annotation does not match the actual data type provided by the injection, the handler will be skipped due to the overload mechanism. To debug parsing issues, set the log-level configuration to TRACE.

  7. Overview of nonebot-plugin-alconna

    nonebot-plugin-alconna is a comprehensive plugin for NoneBot that provides three main capabilities:

    1. Enhanced Command Parsing: Introduces the on_alconna event responder, which offers more powerful parsing capabilities than standard functions like on_command, on_shell, or on_regex by leveraging the Alconna library.
    2. Universal Message Components: Provides a cross-platform message model (UniMessage) and segments (Text, Image, At) for sending, receiving, recalling, and editing messages across different adapters. It includes utility functions like message_recall, message_edit, and message_reaction, as well as a Target model for active message sending.
    3. Built-in Functional Plugins: Includes ready-to-use plugins such as echo (message echoing), help (listing Alconna responder help), lang (switching Alconna language), switch (toggling commands), and with (session-based command prefix loading).

  8. Overview of nonebot-plugin-alconna

    nonebot-plugin-alconna is a comprehensive plugin for NoneBot that enhances command parsing and message handling. It consists of three main components:

    1. Enhanced Command Parsing: Provides the on_alconna event responder helper based on the Alconna library, offering more powerful parsing capabilities than standard on_command, on_shell, or on_regex functions.
    2. Universal Message Components: Implements cross-platform message operations (sending, recalling, editing, reacting) using models like UniMessage (universal message model), Text, Image, At (message segments), and Target (message targets). It also provides dependency injections and Rules such as UniMsg, MsgId, MsgTarget, at_in, and at_me.
    3. Built-in Functional Plugins: Includes utility plugins like echo (message echoing), help (lists Alconna responder help), lang (switches Alconna language), switch (enables/disables commands), and with (loads command headers for sub-commands in a session).

    It supports a wide range of adapters including OneBot (11/12), Telegram, Feishu, GitHub, QQ bot, DingTalk, Console, Kook, Mirai, Ntchat, Minecraft, Walle-Q, Discord, Red, Satori, Dodo IM, Kritor, Tailchat, Mail, wxmp, Heybox, and Milky.

  9. Overview of NoneBot Exception Hierarchy

    NoneBot uses a structured exception hierarchy to manage runtime behavior. While many of these are handled internally by the framework, they define how events are ignored, skipped, or terminated. The primary base class is NoneBotException.
    NoneBotException
├── ParserExit
├── ProcessException
|   ├── IgnoredException
|   ├── SkippedException
|   |   └── TypeMisMatch
|   ├── MockApiException
|   └── StopPropagation
├── MatcherException
|   ├── PausedException
|   ├── RejectedException
|   └── FinishedException
├── AdapterException
|   ├── NoLogException
|   ├── ApiNotAvailable
|   ├── NetworkError
|   └── ActionFailed
└── DriverException
    └── WebSocketClosed

  10. Overview of nonebot-plugin-alconna

    nonebot-plugin-alconna is a plugin designed to enhance the NoneBot development experience. It consists of three main components:

    1. Enhanced Command Parsing: Provides the on_alconna event responder helper based on Alconna, offering more powerful parsing capabilities than on_command, on_shell, or on_regex.
    2. Universal Message Components: Implements cross-platform message handling (sending, receiving, recalling, editing, and reacting) via:
      • UniMessage: A universal message model for conversion and export across adapters.
      • Text, Image, At: Universal message segment models.
      • Target: A universal target model for proactive message sending.
      • Utility functions: message_recall, message_edit, message_reaction.
      • Dependency injection and Rules: UniMsg, MsgId, MsgTarget, at_in, at_me.
    3. Built-in Functional Plugins: Includes pre-implemented plugins such as echo (echoes messages), help (lists Alconna responder help), lang (switches Alconna language), switch (toggles commands), and with (loads command headers for sub-commands in a session).

  11. Overview of NoneBot Event Responders (Matchers)

    An Event Responder (Matcher) is the basic unit used to respond to received events in NoneBot. All event responders inherit from the Matcher base class. They function by filtering events based on specific rules and processing them through predefined dependencies.

  12. Overview of NoneBot Dependency Injection

    NoneBot uses dependency injection to provide context (like the current event or bot instance) to event handlers, making code cleaner and more reusable. The system consists of two phases: parameter parsing (identifying Dependency and creating a Dependent object) and execution (injecting the resolved values into the function).

    Critical Note: Type annotations are essential. If the type annotation does not match the actual data type provided by the injection system, the handler will be skipped due to the overload mechanism. To debug injection issues, set the log-level configuration to TRACE.