Events#

Luster mainly revolves around the concept of events. Events are messages received over websocket whenever something happens such as message sent, user updated, message updated etc.

Luster provides an easy to use API in luster.Client to efficiently listen to events and respond to them. This page of the documentation documents the classes that are passed to event listeners and contain information about the invoked event.

An Intro to Listeners#

First things first, let’s quickly discuss what an event listener is and how we can register one.

Event listener is a simple function that is called whenever a specific event happens.

We can use the luster.Client.listen() decorator to register an event listener. The first parameter in this decorator is the name of event to listen to. luster.WebsocketEvent enum provides all the possible values for this parameter.

Example:

@client.listen(luster.WebsocketEvent.READY)
async def on_ready(event: luster.events.Ready):
    print(f"Bot is ready!")

Notice that the function is taking a single parameter event, All listeners take this parameter. The object passed in this parameter contains the information about the event. Depending on the event, this parameter will take different class all inheriting a common base class, BaseEvent.

Note

For users manually using the luster.WebsocketHandler, There is no event listeners API available in this class. They can override luster.WebsocketHandler.on_websocket_event() hook to receive events and handle them manually.

Event Objects#

Following classes are passed to event listener callback in the first parameter. These classes are available under luster.events module.

BaseEvent#

class luster.events.BaseEvent#

The base class for all classes relating to websocket events.

Events classes are generally passed to event listeners callbacks and contain useful information about a certain websocket event.

abstract get_event_name() → str#

Gets the name of event.

Returns: The name of event.
Return type: str

Authenticated#

class luster.events.Authenticated#

An event emitted after authenticating the websocket session.

This event can be used as an indication that client has successfully initiated the websocket session and is now ready for receiving data over websocket.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

Pong#

class luster.events.Pong(data: Any)#

An event emitted when client pings the websocket.

data: Any#: The data sent during the ping event.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

Ready#

class luster.events.Ready#

An event emitted when client is ready.

Ready means that client has successfully cached all the entities received from websocket initially.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

UserUpdate#

class luster.events.UserUpdate(before: User, after: User)#

An event emitted when ownself or another user is updated.

after: User#: The user after the update.

before: User#: The user before the update.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

UserRelationship#

class luster.events.UserRelationship(before: Relationship, after: Relationship)#

An event emitted when your relationship with another user is updated.

after: Relationship#: The relationship after the update.

before: Relationship#: The relationship before the update.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

property user: User#: The user with which the relationship was updated.

UserRelationshipUpdate#

luster.events.UserRelationshipUpdate#: An alias for UserRelationship.

ServerCreate#

class luster.events.ServerCreate(server: Server)#

An event emitted when a server is created.

This is emitted in following scenarios:

The user joins a new server.
The user creates a new server.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

server: Server#: The new server.

ServerUpdate#

class luster.events.ServerUpdate(before: Server, after: Server)#

An event emitted when a server is updated.

after: Server#: The server after the update.

before: Server#: The server before the update.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

ServerDelete#

class luster.events.ServerDelete(server: Server, channels: List[ServerChannel])#

An event emitted when a server is deleted.

channels: List[ServerChannel]#: The list of channels belonging to the server that was deleted.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

server: Server#: The deleted server.

ChannelCreate#

class luster.events.ServerCreate(server: Server)#

An event emitted when a server is created.

This is emitted in following scenarios:

The user joins a new server.
The user creates a new server.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

server: Server#: The new server.

ChannelUpdate#

class luster.events.ServerUpdate(before: Server, after: Server)#

An event emitted when a server is updated.

after: Server#: The server after the update.

before: Server#: The server before the update.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

ChannelDelete#

class luster.events.ServerDelete(server: Server, channels: List[ServerChannel])#

An event emitted when a server is deleted.

channels: List[ServerChannel]#: The list of channels belonging to the server that was deleted.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

server: Server#: The deleted server.

ChannelGroupJoin#

class luster.events.ChannelGroupJoin(channel: Group, user: Optional[User], user_id: str)#

An event emitted when a user joins a group.

channel: Group#: The joined group.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

property group: Group#

The joined group.

Returns
Return type: Group

user: Optional[User]#

The user that joined the group.

If the user isn’t cached, This might be None. Consider relying on user_id for those cases for fetching the user manually.

user_id: str#: The ID of user that joined.

ChannelGroupLeave#

class luster.events.ChannelGroupLeave(channel: Group, user: Optional[User], user_id: str)#

An event emitted when a user leaves a group.

channel: Group#: The left group.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

property group: Group#

The left group.

Returns
Return type: Group

user: Optional[User]#

The user that left the group.

If the user isn’t cached, This might be None. Consider relying on user_id for those cases for fetching the user manually.

user_id: str#: The ID of user that left.

GroupJoin#

luster.events.GroupJoin#: An alias for ChannelGroupJoin.

GroupLeave#

luster.events.GroupLeave#: An alias for ChannelGroupLeave.

ServerRoleCreate#

class luster.events.ServerRoleCreate(server: Server, role: Role)#

An event emitted when a server role is created.

Note

There is no such event in Revolt API as SERVER_ROLE_CREATE. Internally, when a role is created, the SERVER_ROLE_UPDATE event is triggered by the websocket API. The library decides whether it is a create event or update event by checking whether the targeted role is already present in cache or not.

Although not seen often, if for some reason the cache is in an invalid state, this may cause false positive dispatches.

get_event_name() → str#

Gets the name of event.

Returns: The name of event.
Return type: str

role: Role#: The created role.

server: Server#: The server that the role belongs to.

ServerRoleUpdate#

class luster.events.ServerRoleUpdate(server: Server, before: Role, after: Role)#

An event emitted when a server role is updated.

after: Role#: The updated role.

before: Role#: The role before the update.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

server: Server#: The server that the role belongs to.

ServerRoleDelete#

class luster.events.ServerRoleDelete(server: Server, role: Role)#

An event emitted when a server role is delete.

get_event_name() → types.EventTypeRecv#

Gets the name of event.

Returns: The name of event.
Return type: str

role: Role#: The role that was deleted.

server: Server#: The server that the role belongs to.

RoleCreate#

luster.events.RoleCreate#: An alias for ServerRoleCreate.

RoleUpdate#

luster.events.RoleUpdate#: An alias of ServerRoleUpdate.

RoleDelete#

luster.events.RoleDelete#: An alias of ServerRoleUpdate.