Handlers#

Some users might want to go beyond the boundaries and might want to handle everything by themself. Fortunately, library provides a set of classes that provide low level control over the API. Conventionally, we tend to call these low level classes, “Handlers”

Following are the main handlers provided by the library:

HTTPHandler
WebsocketHandler

HTTPHandler#

class luster.HTTPHandler(*, token: str, session: Optional[aiohttp.client.ClientSession] = None, bot: bool = True)#

A class that handles HTTP requests to Revolt API.

In most cases, you might not need to interact with this class. Client provides a high level abstraction for this class.

You should not initialize this class manually. Instead, use the create_http_handler() helper function. In a Client, you can use Client.http_handler to get the instance of this class.

Parameters

token (str) – The bot or session token used for authenticating requests. This cannot be modified once initialized.
bot (bool) – Whether the passed token is a bot token. Set this to False when a session token is passed. Defaults to True.
session (Optional[aiohttp.ClientSession]) –
The client session used for making HTTP requests.

If not provided, A session is created internally and would be closed automatically after usage. Note that when a session is provided by the user, It must be closed by the user. Library will not take it’s ownership.

AUTUMN_BASE_URL: ClassVar[str] = 'https://autumn.revolt.chat'#: The base URL for Autumn file service.

BASE_URL: ClassVar[str] = 'https://api.revolt.chat'#: The base URL used for routes.

USER_AGENT: ClassVar[str] = 'Luster (0.1.0a3, https://github.com/izxxr/luster)'#

The user agent for attaching to requests.

This by default includes library name but could be modified to be different.

Danger

Sending user agent that are invalid or are in invalid format can result in failing HTTP requests. It is recommended to not change this attribute!

async add_group_member(channel_id: str, user_id: str) → types.AddGroupMemberResponse#

Adds a member to group.

Parameters

channel_id (str) – The ID of group to add member to.
user_id (str) – The ID of user to add.

Returns

Return type

types.AddGroupMemberResponse

property bot: bool#

Indicates whether token is a bot token.

Returns
Return type: bool

async change_username(json: types.ChangeUsernameJSON) → types.ChangeUsernameResponse#

Changes the username of current user.

Parameters: json (types.EditUserJSON) – The JSON body for request.
Returns
Return type: types.ChangeUsernameResponse

async close() → bool#

Closes the underlying client session, if possible.

Returns: Indicates whether the session was closed.
Return type: bool

property closed: bool#

Indicates whether the underlying session is closed.

Returns
Return type: bool

async create_group(json: types.CreateGroupJSON) → types.CreateGroupResponse#

Creates a group.

Parameters: json (types.CreateGroupJSON) – The JSON body for request.
Returns
Return type: types.CreateGroupResponse

async create_server(json: types.CreateServerJSON) → types.CreateServerResponse#

Creates a new server.

Parameters: json (types.CreateServerJSON) – The JSON body for request.
Returns
Return type: types.CreateServerResponse

async create_server_channel(server_id: str, json: types.CreateServerChannelJSON) → types.CreateServerChannelResponse#

Creates a channel in a server.

Parameters

server_id (str) – The ID of server to create the channel in.
json (types.CreateServerChannelJSON) – The JSON body for request.

Returns

Return type

types.CreateServerChannelResponse

async delete_channel(channel_id: str) → types.DeleteChannelResponse#

Deletes the channel by it’s ID.

For server channel, This route deletes the channel and for direct messages and groups, This route leaves or closes the channel.

Parameters: channel_id (str) – The ID of channel to delete.
Returns
Return type: types.DeleteChannelResponse

async delete_server(server_id: str) → types.DeleteChannelResponse#

Deletes a server.

If the requesting user is not the server owner, The server is left by the user.

Parameters: server_id (str) – The ID of server to delete.
Returns
Return type: types.DeleteChannelResponse

async edit_channel(channel_id: str, json: types.EditChannelJSON) → types.EditChannelResponse#

Edits a channel.

Parameters

channel_id (str) – The ID of channel to delete.
json (types.EditChannelJSON) – The JSON body for request.

Returns

Return type

types.EditChannelResponse

async edit_server(server_id: str, json: types.EditServerJSON) → types.EditServerResponse#

Edits a server.

Parameters

server_id (str) – The ID of server to edit.
json (types.EditServerJSON) – The JSON body for request.

Returns

Return type

types.EditServerResponse

async edit_user(json: types.EditUserJSON) → types.EditUserResponse#

Edits the current user.

Parameters: json (types.EditUserJSON) – The JSON body for request.
Returns
Return type: types.EditUserResponse

async fetch_channel(channel_id: str) → types.FetchChannelResponse#

Fetches the channel by it’s ID.

Parameters: channel_id (str) – The ID of channel to fetch.
Returns
Return type: types.FetchChannelResponse

async fetch_direct_message_channels() → types.FetchDirectMessageChannelsResponse#

Fetches the direct message channels.

This returns all currently open direct messages and group channels that user is part of.

Returns
Return type: types.FetchDirectMessageChannelsResponse

async fetch_group_members(channel_id: str) → types.FetchGroupMembersResponse#

Fetches the members of a group.

Parameters: channel_id (str) – The ID of group to fetch members of.
Returns
Return type: types.FetchGroupMembersResponse

async fetch_node_info() → types.NodeInfo#: An alias of query_node() method.

async fetch_profile(user_id: str) → types.FetchProfileResponse#

Fetch a user’s profile.

Parameters: json (types.EditUserJSON) – The JSON body for request.
Returns
Return type: types.FetchProfileResponse

async fetch_self() → types.FetchSelfResponse#

Fetches the user information for current authenticated user.

Returns
Return type: types.FetchSelfResponse

async fetch_server(server_id: str) → types.FetchServerResponse#

Fetches a server.

Parameters: server_id (str) – The ID of server to fetch.
Returns
Return type: types.FetchServerResponse

async fetch_user(user_id: str) → types.FetchUserResponse#

Fetches the user of given ID.

Parameters: user_id (str) – The ID of user to fetch.
Returns
Return type: types.FetchUserResponse

async mark_server_as_read(server_id: str) → types.MarkServerAsReadResponse#

Marks a server as read.

Parameters: server_id (str) – The ID of server to mark as read.
Returns
Return type: types.MarkServerAsReadResponse

async open_direct_message(user_id: str) → types.OpenDirectMessageResponse#

Opens the direct message channel with a user.

This returns the opened direct message or saved messages channel if the given user ID belongs to ownself.

Parameters: user_id (str) – The ID of user to open direct message channel with.
Returns
Return type: types.OpenDirectMessageResponse

async query_node() → types.NodeInfo#

Fetches the information about current Revolt instance.

This route does not require authorization.

Returns
Return type: types.NodeInfo

async remove_group_member(channel_id: str, user_id: str) → types.RemoveGroupMemberResponse#

Removes a member from a group.

Parameters

channel_id (str) – The ID of group to remove member from.
user_id (str) – The ID of user to remove.

Returns

Return type

types.RemoveGroupMemberResponse

async request(method: str, route: str, base_url: Optional[str] = None, **kwargs: Any) → Any#

Requests a certain route and returns the response data.

Parameters

method (str) – The HTTP method to use.
route (str) – The route that will be appended to BASE_URL.
base_url (str) – Override the base URL per request. Defaults to BASE_URL.
**kwargs –
The keyword arguments that are passed to aiohttp.ClientSession.request(). It is worth noting that provided headers will be updated to include the proper authentication headers and you don’t have to add any authentication headers manually.

Following headers will be overwritten:
- X-Session-Token
- X-Bot-Token

property session: Optional[aiohttp.client.ClientSession]#

The client session used for making HTTP requests.

Returns
Return type: Optional[aiohttp.ClientSession]

property session_owner: bool#

Indicates whether library owns the HTTP session.

Returns
Return type: bool

async set_channel_default_permission(channel_id: str, json: types.SetChannelDefaultPermissionJSON) → types.SetChannelDefaultPermissionResponse#

Sets permissions override for the default role in a server channel.

The channel ID must point to a server text or voice channel or a private group channel.

Parameters

channel_id (str) – The ID of server channel to set the role permission for.
json (types.SetChannelRolePermissionJSON) – The new permissions data.

Returns

Return type

types.SetChannelDefaultPermissionResponse

async set_channel_role_permission(channel_id: str, role_id: str, json: types.SetChannelRolePermissionJSON) → types.SetChannelRolePermissionResponse#

Sets permissions override for a specific role in a server channel.

The channel ID must point to a server text or voice channel.

Parameters

channel_id (str) – The ID of server channel to set the role permission for.
role_id (str) – The ID of role whose permission is being set.
json (types.SetChannelRolePermissionJSON) – The new permissions data.

Returns

Return type

types.SetChannelRolePermissionResponse

async set_server_default_permission(server_id: str, json: types.SetServerDefaultPermissionJSON) → types.SetServerDefaultPermissionResponse#

Sets permissions for the default role in a server.

Parameters

server_id (str) – The ID of server to set the role permission for.
json (types.SetServerRolePermissionJSON) – The new permissions data.

Returns

Return type

types.SetServerDefaultPermissionResponse

async set_server_role_permission(server_id: str, role_id: str, json: types.SetServerRolePermissionJSON) → types.SetServerRolePermissionResponse#

Sets permissions for a specific role in a server.

Parameters

server_id (str) – The ID of server to set the role permission for.
role_id (str) – The ID of role whose permission is being set.
json (types.SetServerRolePermissionJSON) – The new permissions data.

Returns

Return type

types.SetServerRolePermissionResponse

property token: Optional[str]#

The token used for authenticating requests.

Returns
Return type: Optional[str]

async upload_file(file: io.BufferedReader, tag: types.FileTag) → types.UploadFileResponse#

Uploads a file to Autumn file server.

Parameters

file (io.BufferedReader) – The file buffer to upload.
tag (types.FileTag) – The tag or bucket to upload this file to.

Returns

The uploaded file.

Return type

types.UploadFileResponse

luster.create_http_handler(*, cls: Literal[None] = 'None', token: str, session: Optional[aiohttp.client.ClientSession] = None, bot: bool = True) → luster.http.HTTPHandler#

luster.create_http_handler(*, cls: Optional[Type[luster.http.HTTPHandlerT]] = None, token: str, session: Optional[aiohttp.client.ClientSession] = None, bot: bool = True) → luster.http.HTTPHandlerT

A helper for creating a HTTPHandler.

This function can either be awaited or be used in an asynchronous context manager.

Example:

async with luster.create_http_handler(token="...") as http:
    await http.fetch_api_info()

# is equivalent of

http = await luster.create_http_handler()
await http.fetch_api_info()

# After usage, don't forget to close!
await http.close()

Parameters

cls (Optional[Type[HTTPHandler]]) – The class type of HTTPHandler to return. This can be used to return custom subclasses.
token (str) – The bot or session token used for authenticating requests. This cannot be modified once initialized.
bot (bool) – Whether the passed token is a bot token. Set this to False when a session token is passed. Defaults to True.
session (Optional[aiohttp.ClientSession]) –
The client session used for making HTTP requests.

If not provided, A session is created internally and would be closed automatically after usage. Note that when a session is provided by the user, It must be closed by the user. Library will not take it’s ownership.

Returns

The created HTTP handler.

Return type

HTTPHandler

WebsocketHandler#

class luster.WebsocketHandler(http_handler: HTTPHandler, version: types.WebsocketVersion = 1)#

A class that handles websocket connection with Revolt Events API.

This is a low level interface of Client that provides interface for realtime communication with Revolt Events API using websocket.

Parameters

http_handler (HTTPHandler) – The HTTP handler used for opening websocket connections.
version (types.WebsocketVersion) – The version of websocket protocol to use. Defaults to 1 and currently there are no other options than 1

async close() → None#: Closes the websocket connection.

property closed: bool#

Indicates whether the websocket connection is closed.

Returns
Return type: bool

async connect() → None#

Connects the websocket.

This is a blocking coroutine that does not return until websocket connection is closed.

async get_websocket_url(*, include_token: bool = True, transport_format: Optional[types.WebsocketFormat] = None) → str#

Gets the websocket URL including relevant parameters.

This under the hood uses the HTTPHandler.query_node() route to retrieve the websocket URL.

Parameters

include_token (bool) – Whether to include token in the returned URL.
transport_format (types.WebsocketFormat) – The format to use for websocket packets transporation. By default or by omitting this parameter, The ideal format is automatically selected.

Returns

The websocket URL used for connecting to Revolt websocket.

Return type

str

property http_handler: luster.http.HTTPHandler#

The HTTP handler associated to this websocket handler.

Returns
Return type: HTTPHandler

property latency: float#

The current latency of websocket.

This is measured by delay between ping sent by client and it’s acknowledgement by the server.

Returns
Return type: float

async on_websocket_event(type: types.EventTypeRecv, data: Dict[str, Any]) → Any#

A hook that gets called whenever a websocket event is received.

By default, this does nothing. The subclasses can override this method to implement custom behaviour.

Parameters

type (types.EventTypeRecv) – The type of event that was received.
data (dict) – The received data.

async send(type: types.EventTypeSend, data: Dict[str, Any]) → None#

Sends an event via websocket.

Parameters

type (types.EventTypeSend) – The type of event to send.
data (dict) – The event data, excluding type.

State#

class luster.State(http_handler: HTTPHandler, websocket_handler: WebsocketHandler, cache: Cache)#

A class that manages state of a Revolt bot.

This class mainly serves the purpose of properly passing data and tracking state across different classes and specifically data models.

You should not worry about this class when using Client as it is automatically handled under the hood. However, when using various handlers to interact with Revolt API, you might need to manually initialize models in which case you will need this class.

Parameters

http_handler (HTTPHandler) – The HTTP handler used for HTTP requests.
websocket_handler (WebsocketHandler) – The websocket handler used for websocket connections.
cache (Cache) – The cache handler used for caching entities.

property cache: Cache#

The cache handler associated to this state.

Returns
Return type: Cache

property http_handler: HTTPHandler#

The HTTP handler associated to this state.

Returns
Return type: HTTPHandler

property websocket_handler: WebsocketHandler#

The websocket handler associated to this state.

Returns
Return type: WebsocketHandler