NoneBot2 Documentation

nonebot-plugin-alconna improves the NoneBot development experience through three main components:

1. Enhanced Command Parsing: Uses Alconna to provide the on_alconna event responder, offering superior parsing compared to on_command or on_regex.
2. Universal Message Components: Provides cross-platform message handling via:
   • UniMessage: A universal message model for conversion and exporting across adapters.
   • Message Segments: Text, Image, At, etc., compatible with both UniMessage and Alconna parsing.
   • Functionality: message_recall, message_edit, message_reaction.
   • Target: A universal model for active message sending.
   • Dependency Injection/Rules: UniMsg, MsgId, MsgTarget, at_in, at_me.
3. Built-in Feature Plugins:
   • echo: Echoes reply messages.
   • help: Lists help information for on_alconna responders.
   • lang: Switches Alconna language.
   • switch: Enables/disables specific commands.
   • with: Loads command headers in the current session for sub-commands to save typing.

NoneBot uses dependency injection to provide context information (like the current event or bot) to event handlers. This allows for cleaner, more reusable code.

Key concepts:

• Dependent: A callable (like an event handler or a custom dependency function) that uses dependency injection.
• Dependency: The object being injected (e.g., the current Event, Bot, etc.).

Important Rules:

• Type Annotations are critical: They determine which dependency is injected and trigger the overload mechanism. If a type annotation does not match the actual data type, the Dependent (the handler) will be skipped.
• Non-dependency parameters: Any parameter that cannot be resolved as a dependency and has a default value is treated as a standard non-dependency parameter and will use its default value.
• Error Handling: If a parameter cannot be resolved and has no default value, a ValueError("Unknown parameter") is raised.
• Debugging: To inspect the dependency resolution process, set the log level to TRACE in your configuration.

A NoneBot robot consists of four primary components that work together to handle messaging and functionality:

1. NoneBot Framework Core: The central body responsible for connecting all components and providing basic robot functionality.
2. Driver (Driver): Implements client/server functionality. It is responsible for receiving and sending messages, typically via HTTP communication.
3. Adapter (Adapter): Sits on top of the Driver. It is responsible for converting platform-specific messages into the NoneBot event/operating system message format.
4. Plugin (Plugin): The implementation of the robot's actual features. Plugins typically handle events and perform a series of operations.

While the Framework Core is mandatory, the Driver, Adapter, and Plugins can be selected and combined according to your needs. Note that some plugins may only be compatible with specific platforms depending on how they were written.

An Event Responder in NoneBot consists of several key components that determine how and when a handler is triggered:

• Type (type): The event type the responder listens for (e.g., meta_event, message, notice, request). An empty string "" matches all event types. Type checking happens before permission and rule checks.
• Permission (permission): A Permission object checked after the type check. If it passes, the responder proceeds to rule checking.
• Rule (rule): A Rule object checked after permission. If it passes, the responder is triggered.
• Priority (priority): A positive integer. Lower values are triggered first. If priorities are equal, they are triggered in registration order.
• Block (block): A boolean. If True, the event propagation stops after this responder is triggered, preventing lower-priority responders from receiving it.
• Lifespan:
  • temp: If True, the responder is automatically destroyed after being triggered once.
  • expire_time: A datetime object. If set, the responder is destroyed after this time.
• Default State (default_state): A dict used to initialize the responder's state when triggered.

A Message is a sequence of MessageSegment objects (a subclass of List[MessageSegment]). You can construct it in several ways:

1. Directly: Pass a str, a MessageSegment, an Iterable[MessageSegment], or adapter-specific types to the Message constructor.
2. Arithmetic: Use the + operator to combine str, Message objects, or MessageSegment objects.
3. From Dictionaries: Use Pydantic's TypeAdapter to validate and construct MessageSegment or Message from dictionary/list data.

Note: Always ensure the Message type matches the platform adapter you are using (e.g., use nonebot.adapters.console.Message for Console adapter).

from nonebot.adapters.console import Message, MessageSegment

# Direct construction
Message("Hello, world!")
Message(MessageSegment.text("Hello, world!"))
Message([MessageSegment.text("Hello, world!")])

# From dictionaries using Pydantic
from pydantic import TypeAdapter
TypeAdapter(MessageSegment).validate_python(
    {"type": "text", "data": {"text": "text"}}
)

TypeAdapter(Message).validate_python(
    [MessageSegment.text("text"), {"type": "text", "data": {"text": "text"}}],
)