Events (astra.events)

Overview

Event modules provide the filtering, dispatch and context objects used by the application layer.

class EventEmitter[source]

Event registry.

Allows functions to subscribe to specific event names and provides mechanisms for firing events with automatic task scheduling for sync and async callbacks.

on(event, callback=None, criteria=None)[source]

Subscribes a listener to an event.

Can be used as a decorator or a direct function call.

Parameters:

event (str) – The name of the event to listen for.
callback (Callable | None) – The function to execute.
criteria (Any) – An optional filter object or function.

Example:

@client.on("message")
async def handle_message(msg):
 print(msg.body)

off(handle)[source]

Unregisters a listener using its handle.

Parameters:: handle (int)

async emit_async(event, payload=None)[source]

Triggers an event and waits for all handlers to complete.

Parameters:

event (str)
payload (Any)

emit(event, payload=None)[source]

Triggers an event asynchronously without waiting for completion.

Parameters:

event (str)
payload (Any)

class EventDispatcher(client)[source]

Routes incoming events across the application.

Handles priority-based execution, command parsing, and event interception via middlewares.

add_middleware(middleware)[source]

Injects a middleware to pre-process or block events.

Parameters:: middleware (Callable[[str, Any], Awaitable[bool]])

async wait_for(event_name, criteria=None, timeout=None)[source]

Suspends execution until a specific event arrives.

Parameters:

event_name (str)
criteria (Criterion | None)
timeout (float | None)

Return type:

subscribe(event_name, callback, criteria=None, priority=0, is_command=False, command_name=None)[source]

Registers a new event handler.

Parameters:

event_name (str)
callback (Callable[[...], Awaitable[None]])
criteria (Criterion | None)
priority (int)
is_command (bool)
command_name (str | None)

Return type:

set_event_callback(callback)[source]

Registers a callback invoked on every event dispatch (used by SyncEngine).

Parameters:: callback (Callable[[], None])

async dispatch(name, payload)[source]

Dispatches an event through the engine.

Parameters:

name (str)
payload (Any)

This module provides the criteria (filters) used to match events in the Astra framework.

class Criterion[source]

Base class for all event matching criteria.

Criteria can be combined using logical operators: - & (AND) - | (OR) - ~ (NOT)

abstractmethod async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class AndCriterion(c1, c2)[source]

Parameters:

c1 (Criterion)
c2 (Criterion)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class OrCriterion(c1, c2)[source]

Parameters:

c1 (Criterion)
c2 (Criterion)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class NotCriterion(c)[source]

Parameters:: c (Criterion)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class AllCriterion[source]

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class ChatTypeCriterion(is_group)[source]

Parameters:: is_group (bool)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class TextMatchCriterion(pattern, exact=False, ignore_case=True)[source]

Parameters:

pattern (str)
exact (bool)
ignore_case (bool)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class RegexCriterion(pattern, flags=re.IGNORECASE)[source]

Parameters:

pattern (str)
flags (int)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class IdentityCriterion(ids, field='chat_id')[source]

Parameters:

ids (str | List[str])
field (str)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class DirectionCriterion(outgoing)[source]

Parameters:: outgoing (bool)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class TypeCriterion(attr, value=True)[source]

Parameters:

attr (str)
value (Any)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class CommandCriterion(command, prefixes='/.')[source]

Parameters:

command (str | List[str])
prefixes (str)

async matches(event)[source]

Determines if the given event matches this criterion.

Parameters:: event (Any)
Return type:: bool

class Filters[source]

Collection of event matching criteria.

static command(name, prefixes='/.')[source]

Matches if the message is a specific command.

Example

command(“ping”, “.”) -> Matches “.ping” command(“.ping”) -> Matches “.ping” (infer prefix from name)

Parameters:

name (str | List[str])
prefixes (str)

Return type:

static text_contains(text, ignore_case=True)[source]

Matches if the message text contains the given substring.

Parameters:

text (str)
ignore_case (bool)

Return type:

static text_is(text, ignore_case=True)[source]

Matches if the message text exactly matches the given string.

Parameters:

text (str)
ignore_case (bool)

Return type:

static regex(pattern)[source]

Matches message text against a regular expression.

Parameters:: pattern (str)
Return type:: Criterion

static chat(chat_id)[source]

Matches events from specific chat JIDs.

Parameters:: chat_id (str | List[str])
Return type:: Criterion

static sender(user_id)[source]

Matches events from specific user JIDs.

Parameters:: user_id (str | List[str])
Return type:: Criterion

static has_attribute(attribute, value=True)[source]

Custom attribute matcher for advanced use cases.

Parameters:

attribute (str)
value (Any)

Return type:

static create(func)[source]

Creates a custom filter from a callable.

Parameters:: func (Callable[[Any], bool | Any])
Return type:: Criterion

class EventContext(client, event, command=None, args=None, prefix=None)[source]

The context of a WhatsApp event.

Provides a high-level API for interacting with the message or chat that triggered the event.

Parameters:

client (Client)
event (Any)
command (str | None)
args (List[str] | None)
prefix (str | None)

__init__(client, event, command=None, args=None, prefix=None)[source]

Initialize the event context.

Parameters:

client (Client) – The Astra client instance.
event (Any) – The raw event or Message object.
command (str | None) – The command name (if applicable).
args (List[str] | None) – Command arguments (if applicable).
prefix (str | None) – The command prefix used (if applicable).

async reply(text)[source]

Sends a reply quoting this message.

Parameters:: text (str)
Return type:: Any

async react(emoji)[source]

Reacts to this message with an emoji.

Parameters:: emoji (str)
Return type:: bool

async edit(text)[source]

Edits this message (if sent by the bot).

Parameters:: text (str)
Return type:: bool

async delete(everyone=True)[source]

Deletes this message.

Parameters:: everyone (bool)
Return type:: bool

async respond(text, **kwargs)[source]

# Response logic. Edits the message if it’s outgoing (from bot), otherwise replies. Now includes robust fallback for self-chats and bridge failures.

Parameters:: text (str)
Return type:: Any

property body: str: Alias for text for compatibility with Message model.

Example: registering an event

from astra import Client
from astra.events import Filters

client = Client()

@client.on("message", Filters.text_contains("urgent"))
async def on_urgent(ctx):
 await ctx.reply("Received — will review asap")

Async behavior

Dispatcher schedules handler invocations as asyncio tasks to avoid blocking

the incoming event loop.

Filters can be coroutine-backed — they are awaited during dispatch.