Data Classes#

Revolt API is packed with various complex data models and types. These classes wrap these data models in easy to use form so you don’t have to worry about dealing with JSON and bitwise values, handling optional fields, default values etc. All of that workload is handled by the library.

Bitwise Flags#

Permissions#

class luster.Permissions(value: int = 0, **flags: bool)#

A class that provides an interface for manipulating bitwise permissions value.

This class provides a user friendly way of manipulating permissions value using simple booleans. The permissions can either be passed during initialization as keyword arguments or raw permission value can be passed as first parameter.

Following special operations are supported between Permissions instances:

  • Equality operations

  • Less than and greater than operations

Note that this class is used in places where the permission can only take two values: enabled or disabled. In some cases, their may be a third option of “inheriting” permissions from a certain parent entity. In that case, PermissionOverwrite is used instead. The example is channel role permissions.

value#

The raw bitwise value of permissions.

Type

int

assign_roles = 512#

Allows assigning roles to members below oneselves ranking.

ban_members = 128#

Allows banning server members.

change_avatar = 4096#

Allows changing ownself server avatar.

change_nickname = 1024#

Allows changing ownself nickname.

connect = 1073741824#

Allows connecting to voice channels.

deafen_members = 17179869184#

Allows deafening other members in voice channels.

invite_others = 33554432#

Allows creating invite for a server or channel.

kick_members = 64#

Allows kicking server members.

manage_channel = 1#

An alias for manage_channels.

manage_channels = 1#

Allows managing server channels.

manage_customization = 16#

Allows managing server emojis.

manage_messages = 8388608#

Allows operation on messages such as deleting and pinning.

manage_nicknames = 2048#

Allows changing other members nickname.

manage_permissions = 4#

Allows managing permissions on server and channels.

manage_roles = 8#

Allows managing server roles.

manage_server = 2#

Allows managing the server settings.

manage_webhooks = 16777216#

Allows operation on server webhooks.

masquerade = 268435456#

Allows changing avatar and nickname on every message.

move_members = 34359738368#

Allows removing and moving members in voice channels.

mute_members = 8589934592#

Allows muting other members in voice channels.

react = 536870912#

Allows reacting to messages.

read_message_history = 2097152#

Allows viewing messages history of a text channel.

remove_avatars = 8192#

Allows removing avatars of other members.

send_embeds = 67108864#

Allows attaching rich embeds on messages.

send_messages = 4194304#

Allows sending messages in a text channel.

speak = 2147483648#

Allows speaking in voice channels.

timeout_members = 256#

Allows timing out other members.

upload_files = 134217728#

Allows uploading file in messages.

video = 4294967296#

Allows streaming video in voice channels.

view_channels = 1048576#

Allows viewing the server channels.

Generic Data Models#

BaseModel#

class luster.BaseModel(*args, **kwargs)#

A protocol that acts as a base for most data models.

Almost all data model classes provided by the library are compatible with this class. The Object class allows you to create custom models and provides the minimal functionality required to be compatible with this class.

This protocol supports runtime checks such as isinstance() and issubclass().

id#

The ID of this model.

Type

str

Object#

class luster.Object(id: str)#

Represents a generic object.

This class implements the minimal functionality required to be compatible with BaseModel. This class can be initialized manually and can be useful in certain cases.

An example application of this class is when you want to perform an HTTP operation on a Revolt entity and you just have the ID of that entity. Instead of fetching that entity first, you can pass the instance of this class to HTTP method. Most (not all) HTTP methods allow you to pass this class.

In many cases, This class may also be returned in API responses. These are the cases when library could not resolve the complete entity from cache so it falls back to this class.

Parameters

id (str) – The ID for this object.

Data Models#

File#

class luster.File(data: types.File, state: State)#

Represents a file from Revolt CDN.

id#

The unique ID of this file.

Type

str

tag#

The tag or bucket that this file has been uploaded to. This attribute can be used to determine whether the file was an attachment, avatar or banner etc.

See also

The FileTag enum.

Type

types.FileTag

filename#

The original filename of file.

Type

str

content_type#

The content type of this file.

Type

str

size#

The size of this file, in bytes.

Type

int

type#

The type of this file.

See also

FileType enum

Type

types.FileType

deleted#

Whether this file has been deleted.

Type

bool

reported#

Whether this file has been reported.

Type

bool

message_id#

If file was uploaded as an attachment, the ID of message that attached this file.

Type

Optional[str]

user_id#

If file was uploaded by a user, the ID of user that uploaded this file.

Type

Optional[str]

server_id#

If file was uploaded inside or by a server, the ID of server that uploaded this file.

Type

Optional[str]

object_id#

The ID of object relevant to this file.

Type

Optional[str]

property url: str#

The URL of this file.

Returns

Return type

str

PartialUploadedFile#

class luster.PartialUploadedFile(data: types.UploadFileResponse, tag: types.FileTag, state: State)#

Represents an uploaded file.

This is a partial model that only includes the uploaded file’s ID and tag/bucket.

This model is generally returned by Client.upload_file().

id#

The file’s ID.

Type

str

tag#

The bucket that this file was uploaded to.

Type

types.FileTag

User#

class luster.User(data: types.User, state: State)#

Represents a user entity.

id#

The unique ID of this user.

Type

str

username#

The username of this user.

Type

str

avatar#

The avatar of user, if they have one.

Type

Optional[File]

badges#

The bitfield value for user profile badges.

Type

int

flags#

The bitfield value for user flags.

Type

int

privileged#

Whether the user is a privileged user.

Type

bool

relationship#

The relationship of user with another user or themselves.

Type

types.RelationshipStatus

online#

Whether the user is online right now.

Type

bool

relationships#

The relationships of this user with other users.

Type

List[Relationship]

profile#

The user’s profile.

Type

Optional[Profile]

status#

The user’s current status.

Type

Optional[Status]

property default_avatar_url: str#

The URL pointing to user’s default avatar.

This is not user’s actual avatar.

Returns

Return type

str

property display_avatar_url: str#

The URL pointing to user’s displayed avatar.

This property is a shorthand that returns the user’s actual avatar URL if they have one and falls back to default avatar URL if they don’t have a custom avatar.

Returns

Return type

str

async edit(*, status_text: Optional[str] = ..., status_presence: Optional[types.PresenceType] = ..., profile_content: Optional[str] = ..., profile_background: Optional[Union[str, BufferedReader]] = ..., avatar: Optional[Union[str, BufferedReader]] = ...) → User#

Edits the user.

This method requires the user to be the current authenticated user. Otherwise, This method will fail.

Passing None to the parameters hinted as typing.Optional will remove that field.

Parameters

  • status_text (Optional[str]) – The user’s custom status.

  • status_presence (Optional[types.PresenceType]) –

    The user’s presence type.

    See also

    The PresenceType enum.

  • profile_content (Optional[str]) – The content of profile “aka” the bio section.

  • profile_background (Optional[Union[str, io.BufferedReader]]) – The profile background of the user. If a str is passed, It is considered the attachment ID and is passed directly. If a io.BufferedReader is passed, It will be automatically uploaded to file server first using HTTPHandler.upload_file()

  • avatar (Optional[Union[str, io.BufferedReader]]) – The avatar of the user. If a str is passed, It is considered the attachment ID and is passed directly. If a io.BufferedReader is passed, It will be automatically uploaded to file server first using HTTPHandler.upload_file()

Returns

The updated user.

Return type

User

Raises

HTTPException – Failed to edit the user.

async fetch_profile() → luster.users.Profile#

Fetches the profile of this user.

Returns

The user’s profile

Return type

Profile

Raises

  • HTTPException – The request failed.

  • HTTPNotFound – You are not allowed to fetch this user’s profile.

is_bot() → bool#

Indicates if the user is a bot.

Returns

Return type

bool

Relationship#

class luster.Relationship(data: types.Relationship, user: User)#

Represents a relationship of a user with another user.

user#

The user that the relationship belong to.

Type

User

id#

The ID of user that the relationship is with.

Type

str

status#

The status of this relationship.

See also

RelationshipStatus enum

Type

types.RelationshipStatus

Status#

class luster.Status(data: types.Status, user: User)#

Represents the status of a user.

user#

The user that the status belong to.

Type

User

text#

The user’s custom status text, if any set.

Type

Optional[str]

presence#

The user’s presence type.

See also

PresenceType enum

Type

types.PresenceType

Profile#

class luster.Profile(data: types.Profile, user: User)#

Represnts a user’s profile.

user#

The user that the profile belong to.

Type

User

content#

The user’s bio, if any set.

Type

Optional[str]

background#

The user’s banner background, if any set.

Type

Optional[File]

PartialUserBot#

class luster.PartialUserBot(data: types.PartialUserBot, user: User)#

Represents a “partial” bot.

This partial model only contains the subset of actual model. You can obtain this from User.bot.

user#

The user that this model belong to.

Type

User

owner_id#

The ID of owner of this bot.

Type

str

Server#

class luster.Server(data: types.Server, state: State)#

Represents a Revolt server.

id#

The ID of this server.

Type

str

owner_id#

The ID of user that owns this server.

Type

str

name#

The name of this server.

Type

str

icon#

The server’s icon, if any set.

Type

Optional[File]

banner#

The server’s banner, if any set.

Type

Optional[File]

description#

The description of this server, if any set.

Type

Optional[str]

channel_ids#

The list of IDs of channels in this server.

Type

List[str]

flags#

The enum for server flags.

Type

int

nsfw#

Whether this server is marked as NSFW.

Type

bool

discoverable#

Whether this server is available for discovery.

Type

bool

analytics#

Whether this server has enabled analytics data.

Type

bool

system_messages#

The system messages channels assignments.

Type

SystemMessages

categories#

The list of categories associated to this server.

Type

List[Category]

default_permissions#

The default permissions across the server.

Type

Permissions

roles#

The list of roles in this server.

Type

List[Role]

channels() → List[ServerChannel]#

The list of channels in this server.

Under the hood, this method finds channels related to this server from global channel cache. If a channel is not cached, it is not included in the returned list of channels.

Returns

Return type

List[ServerChannel]

async create_channel(*, name: str, type: Literal['TextChannel'], description: str = ..., nsfw: bool = ...) → TextChannel#
async create_channel(*, name: str, type: Literal['VoiceChannel'], description: str = ..., nsfw: bool = ...) → VoiceChannel

Creates a channel in this server.

This operation requires manage_channels permission in the server.

Parameters

  • name (str) – The name of channel.

  • type (types.ChannelTypeServer) – The type of channel.

  • description (str) – The description of channel.

  • nsfw (bool) – Whether to mark the channel as NSFW.

Returns

The created channel.

Return type

ServerChannel

Raises

  • HTTPForbidden – You are not allowed to do this.

  • HTTPException – The request failed.

async delete() → None#

Deletes or leaves the server.

If you own the server, this method deletes it otherwise leaves it.

Raises

HTTPException – The request failed.

async edit(*, name: str = ..., description: Optional[str] = ..., icon: Optional[Union[str, BufferedReader]] = ..., banner: Optional[Union[str, BufferedReader]] = ..., system_messages: SystemMessages = ..., analytics: bool = ...) → Server#

Edits the server.

This requires the manage_server permission in the server.

Parameters

  • name (str) – The name of server.

  • description (Optional[str]) – The description of server. Passing None removes the existing description of server.

  • icon (Optional[Union[str, io.BufferedReader]]) – The icon of server. Passing None removes the icon. If a str is passed, It is considered the attachment ID and is passed directly. If a io.BufferedReader is passed, It will be automatically uploaded to file server first using HTTPHandler.upload_file()

  • banner (Optional[Union[str, io.BufferedReader]]) – The banner of server. Passing None removes the banner. If a str is passed, It is considered the attachment ID and is passed directly. If a io.BufferedReader is passed, It will be automatically uploaded to file server first using HTTPHandler.upload_file()

  • system_messages (Optional[SystemMessages]) – The system messages channels of the server.

  • analytics (bool) – Whether to enable analytics data for this server.

Returns

The updated server.

Return type

Server

Raises

  • HTTPForbidden – Missing permissions.

  • HTTPException – The editing failed.

get_role(role_id: str) → Optional[luster.permissions.Role]#

Returns the role related to given role ID.

If the role for given ID is not cached, None is returned.

Parameters

role_id (str) – The ID of role.

Returns

The looked up role, if present.

Return type

Optional[Role]

async mark_read() → None#

Marks this server as read.

Raises

HTTPException – The request failed.

roles() → List[luster.permissions.Role]#

The list of roles in this server.

Returns

Return type

List[Role]

async set_default_permissions(permissions: luster.permissions.Permissions) → luster.server.Server#

Sets the permissions for the default role.

This operation requires the Permissions.manage_permissions permission in the parent server.

Parameters

permissions (Permissions) – The new permissions.

Returns

The updated server.

Return type

Server

Raises

  • HTTPException – The operation failed.

  • HTTPForbidden – You are not allowed to do this.

async set_role_permissions(role: luster.protocols.BaseModel, permissions: luster.permissions.PermissionOverwrite) → luster.server.Server#

Sets the permissions for a specific role.

This operation requires the Permissions.manage_permissions permission in the server.

Parameters
Returns

The updated server.

Return type

Server

Raises

  • HTTPException – The operation failed.

  • HTTPForbidden – You are not allowed to do this.

SystemMessages#

class luster.SystemMessages(*, user_joined: Optional[BaseModel] = ..., user_left: Optional[BaseModel] = ..., user_kicked: Optional[BaseModel] = ..., user_banned: Optional[BaseModel] = ...)#

Represents system messages channels assignment for a server.

This class can generally be obtained using Server.system_messages attribute. You may also initialize this class when editing system messages using Server.edit() method.

Parameters

  • user_joined (Optional[BaseModel]) – The channel used for notifying user joins.

  • user_left (Optional[BaseModel]) – The channel used for notifying user leaves.

  • user_kicked (Optional[BaseModel]) – The channel used for notifying user kicks.

  • user_banned (Optional[BaseModel]) – The channel used for notifying user bans.

copy() → luster.system_messages.SystemMessages#

Creates the shallow copy of this class.

Returns

The created shallow copy.

Return type

SystemMessages

classmethod from_dict(data: types.SystemMessages, *, state: Optional[State] = None) → Self#

Converts a dictionary to SystemMessages.

Parameters

  • data (types.SystemMessages) – The dictionary to convert.

  • state (Optional[State]) – The state to use for resolving channels. If not given, all attributes fallback to use Object class.

Returns

The converted instance.

Return type

SystemMessages

to_dict() → types.SystemMessages#

Returns a dictionary format of this class compatible with Revolt API schema.

Returns

Return type

types.SystemMessages

property user_banned: Optional[BaseModel]#

The channel assigned for notifications regarding user bans.

Returns

Return type

Optional[BaseModel]

property user_joined: Optional[BaseModel]#

The channel assigned for notifications regarding users joining.

Returns

Return type

Optional[BaseModel]

property user_kicked: Optional[BaseModel]#

The channel assigned for notifications regarding user kicks.

Returns

Return type

Optional[BaseModel]

property user_left: Optional[BaseModel]#

The channel assigned for notifications regarding users leaving.

Returns

Return type

Optional[BaseModel]

Category#

class luster.Category(data: types.Category, state: State)#

Represents a category for other channels.

id#

The ID of this category.

Type

str

title#

The title of this category.

Type

str

channel_ids#

The list of channel IDs that are in this category.

Type

List[str]

channels() → List[luster.channels.ServerChannel]#

The list of channels in this category.

Returns

The channels associated to this category.

Return type

List[ServerChannel]

Role#

class luster.Role(role_id: str, data: types.Role, state: State)#

Represents a server role.

id#

The ID of role.

Type

str

name#

The name of role.

Type

str

colour#

The CSS representation of role’s colour.

Type

Optional[str]

hoist#

Whether this role is displayed separate from others.

Type

bool

rank#

The rank of role in hierarchy.

Type

int

property permissions: luster.permissions.PermissionOverwrite#

The permissions of this role.

Returns

Return type

PermissionOverwrite

ServerChannel#

class luster.ServerChannel(data: types.ServerChannel, state: State)#

The common base class for channels in a server.

For convenience, This type has been narrowed down to following subclasses:

id#

The ID of this channel.

Type

str

type#

The type of this channel.

Type

types.ChannelTypeServer

server_id#

The ID of server that this channel belongs to.

Type

str

name#

The name of this channel.

Type

str

description#

The description of this channel.

Type

Optional[str]

nsfw#

Whether this channel is marked as NSFW.

Type

bool

property default_permissions: luster.permissions.PermissionOverwrite#

The default permission overwrite on this channel.

Returns

Return type

PermissionOverwrite

async delete() → None#

Deletes the channel.

This operation requires the Permissions.manage_channels permission in the parent server.

Raises

  • HTTPException – The deletion failed.

  • HTTPForbidden – You are not allowed to do this.

property role_permissions: Mapping[str, luster.permissions.PermissionOverwrite]#

The role permissions of this channel.

This returns a mapping with key being the ID of role and value being the permission overwrite for that role.

Returns

Return type

Mapping[str, PermissionOverwrite]

property server: Optional[Server]#

The server for this channel.

This property might rarely return None if the server relating to this channel is not cached.

Returns

The channel’s server.

Return type

Optional[Server]

async set_default_permissions(permissions: luster.permissions.PermissionOverwrite) → luster.channels.ServerChannel#

Sets the permissions overrides for the default role.

This operation requires the Permissions.manage_permissions permission in the parent server.

Parameters

permissions (PermissionOverwrite) – The new permissions.

Returns

The updated channel.

Return type

ServerChannel

Raises

  • HTTPException – The operation failed.

  • HTTPForbidden – You are not allowed to do this.

async set_role_permissions(role: luster.protocols.BaseModel, permissions: luster.permissions.PermissionOverwrite) → luster.channels.ServerChannel#

Sets the permissions overrides for a specific role.

This operation requires the Permissions.manage_permissions permission in the parent server.

Parameters
Returns

The updated channel.

Return type

ServerChannel

Raises

  • HTTPException – The operation failed.

  • HTTPForbidden – You are not allowed to do this.

TextChannel#

class luster.TextChannel(data: types.ServerChannel, state: State)#

Represents a text channel in a server.

This class inherits the ServerChannel class.

last_message_id#

The ID of last message sent in this channel.

Type

Optional[str]

VoiceChannel#

class luster.VoiceChannel(data: types.ServerChannel, state: State)#

Represents a voice channel in a server.

This class inherits the ServerChannel class.

PrivateChannel#

class luster.PrivateChannel(data: types.PrivateChannel, state: State)#

The common base class for private channels.

For convenience, This type has been narrowed down to following subclasses:

id#

The ID of this channel.

Type

str

type#

The type of this channel.

Type

types.ChannelTypePrivate

async delete() → None#

Deletes the channel.

In case of groups, This leaves the channel and in case of direct messages, This closes the channel.

When called in a group context, manage_channel permission is required.

Raises

  • HTTPException – The deletion failed.

  • HTTPForbidden – You are not allowed to do this.

SavedMessages#

class luster.SavedMessages(data: types.PrivateChannel, state: State)#

Represents a saved messages channel.

This is often referred to as “Saved Notes” channel in the Revolt UI and is limited to a single user.

This class inherits PrivateChannel class.

user_id#

The ID of user that this channel belongs to.

Type

str

DirectMessage#

class luster.DirectMessage(data: types.PrivateChannel, state: State)#

Represents a direct message (DM) between two users.

This class inherits PrivateChannel class.

recipient_ids#

The IDs of recipients that this channel is with.

Type

List[str]

active#

Whether this channel is active on both sides.

Type

bool

last_message_id#

The ID of last message sent in this channel.

Type

Optional[str]

Group#

class luster.Group(data: types.PrivateChannel, state: State)#

Represents a group channel between several users.

This class inherits PrivateChannel class.

name#

The name of this channel.

Type

str

owner_id#

The ID of user that this channel is with.

Type

str

recipient_ids#

The IDs of recipients that are in this channel.

Type

List[str]

description#

The description of this channel.

Type

Optional[str]

icon#

The icon of this channel.

Type

Optional[File]

last_message_id#

The ID of last message sent in this channel.

Type

Optional[str]

nsfw#

Whether this channel is marked as NSFW.

Type

bool

permissions#

The default set of permissions applied to every member in the group.

Type

Permissions

async add_recipient(user: luster.protocols.BaseModel) → None#

Adds a new member to this group.

Parameters

user (BaseModel) – The user to add.

Raises

  • HTTPForbidden – You are not allowed to add members.

  • HTTPException – The addition failed.

async fetch_owner() → luster.users.User#

Fetches the user that owns this group.

Returns

The group owner.

Return type

User

Raises

HTTPException – Failed to fetch the owner.

async fetch_recipients() → List[luster.users.User]#

Fetches the users that are part of this group.

Returns

The recipients of this group.

Return type

List[User]

Raises

HTTPException – The fetching failed.

async remove_recipient(user: luster.protocols.BaseModel) → None#

Removes a member from this group.

Parameters

user (BaseModel) – The user to remove.

Raises

  • HTTPForbidden – You are not allowed to remove members.

  • HTTPException – The removal failed.

async set_default_permissions(permissions: luster.permissions.PermissionOverwrite) → luster.channels.ServerChannel#

Sets the permissions overrides for the default role.

This operation requires the Permissions.manage_permissions permission in the parent server.

Returns

The updated channel.

Return type

Group

Raises

  • HTTPException – The operation failed.

  • HTTPForbidden – You are not allowed to do this.

Data Classes#

PermissionOverwrite#

class luster.PermissionOverwrite(**permissions: Optional[bool])#

Represents a permission overwrite.

Permission overwrites are used to configure overriden permissions on certain server channels.

This class is similar to Permissions and takes the same keyword arguments. The main difference between this class and Permissions is that the default value for a permission is None rather than False.

When initializing, either a boolean or None (default) can be passed to a permission’s value:

  • None (default) represents inherit permission meaning the permission inherits from the server’s default permissions set.

  • False represents that the permission is explicitly denied in the channel.

  • True represents that the permission is explicitly allowed in the channel.

Equality operations between permission overwrite instances are supported.

classmethod from_pair(allow: luster.permissions.Permissions, deny: luster.permissions.Permissions) → typing_extensions.Self#

Creates a PermissionOverwrite from provided allow-deny pair.

Parameters

  • allow (Permissions) – Permissions instance with all permissions enabled that are allowed in the overwrite.

  • deny (Permissions) – Permissions instance with all permissions enabled that are denied in the overwrite.

Returns

The permission overwrite.

Return type

PermissionOverwrite

pair() → Tuple[luster.permissions.Permissions, luster.permissions.Permissions]#

Returns the allow and deny tuple pair for this overwrite.

The first element in the returned tuple is the Permissions instance with all permissions enabled that are allowed in this overwrite while second element is the Permissions with all permissions enabled that are denied in this overwrite.

Returns

The allow deny pair.

Return type

Tuple[Permissions, Permissions]