API-Reference

The API-Reference of the wrapper. Contains all methods and classes usable.

Meta

Misc information about the wrapper.

Version

rin.__version__

The current version of the wrapper.

Caching

Things regarding caching and caches in the wrapper.

Cache

class rin.Cache

A class which represents an in-memory cache.

Note

All cache-able classes have this class under the attribute Class.cache

user: rin.User = rin.User.cache.get(123)
rin.User.cache.set(123, User)

Parameters

max (None | int) – The max amount of items before poping the last inserted object.

root

The internal dict of the cache.

Type

dict

max

The max amount of items the cache can have at a given time.

Type

None | int

len

The current amount of items in the cache.

Type

int

iterator()

An iterator for the cache’s values.

Returns

An iterator of the values.

Return type

typing.Iterator[T]

set(key, value)

Sets a key to the given value.

Parameters

• key (str | int) – The key to set.

• value (typing.Any) – The value to set to the key.

Returns

The value being set.

Return type

typing.Any

get(key)

Retrieves a value from the given key.

Parameters

key (str | int) – The key to retrieve from.

Returns

The value retrieved from the key.

Return type

None | typing.Any

pop(key=None)

Pops an item from the internal dict.

If no key is passed, the last inserted key will be popped.

Parameters

key (None | str | int) – The key to pop from the internal dict.

Returns

The value from the popped key.

Return type

typing.Any

Cacheable

class rin.Cacheable

Represents a class that is cache-able.

cache

The cache of the class.

Type

Cache

API Interface

Things in regard to handling and helping use of the API.

GatewayClient

class rin.GatewayClient

A client which makes a connection to the gateway.

This client is used to receive events from the gateway. This client also can utilize RESTful requests.

Parameters

• token (str) – The token to use for authorization.

• no_chunk (bool) – If chunking at startup should be disabled.

• loop (None | asyncio.AbstractEventLoop) – The loop to use for async operations.

• intents (int) – The intents to identify with when connecting to the gateway.

loop

The loop being used for async operations.

Type

asyncio.AbstractEventLoop

rest

The RESTful request handler.

Type

RESTClient

intents

The intents the client is registered with.

Type

int

gateway

The gateway handler for the client.

Type

Gateway

dispatcher

The dispatch manager for the client.

Type

Dispatcher

@on(self, event, check=<function GatewayClient.<lambda>>)

Registers a callback to an event.

Parameters

• event (Event) – The event to register to.

• check (Callable[…, bool]) – The check the event has to pass in order to be dispatched.

Return type

Callable[…, Listener]

@once(self, event, check=<function GatewayClient.<lambda>>)

Registers a onetime callback to an event. :param event: The event to register to. :type event: Event :param check: The check the event has to pass in order to be dispatched. :type check: Callable[…, bool]

Return type

Callable[…, Listener]

async start()

Starts the connection.

This method starts the connection to the gateway.

Return type

None

async close()

Closes the client.

This method closes the gateway connection as well as the aiohttp.ClientSession used by RESTClient.

Parameters

reason (str) – The reason to close the client with.

Return type

None

sender(snowflake)

Creates a MessageBuilder from the client.

Parameters

snowflake (Snowflake | int) – The snowflake of the channel to create the builder for.

Returns

The created MessageBuilder instance.

Return type

MessageBuilder

unserialize(data, *, cls)

Un-serializes a serialized object. Used for persistent objects.

Note

Objects could be inaccurate or outdated. It’s suggested that you verify the object to be correct.

Parameters

• data (dict) – The data of the object. This is retrieved via Base.serialize().

• cls (type) – The class to create via the data given.

Returns

The object created with the data.

Return type

object

dispatch(event, *payload)

Dispatches an event.

Examples

client.dispatch(rin.Events.MESSAGE_CREATE, rin.Message(...))
# Here `rin.Message(...)` is the payload that gets dispatched to the event's callback.

Parameters

• event (Event) – The event to dispatch.

• payload (Any) – The payload to dispatch the event with.

Returns

A list of tasks created by the dispatch call.

Return type

list[asyncio.Task]

collect(event, *, amount, timeout=None, check=<function GatewayClient.<lambda>>)

Registers a collector to an event.

Arguments of the callback will be passed as lists when the event has been collected X amount of times.

Parameters

• event (Event) – The event to register to.

• amount (int) – The amount to collect before dispatching.

• check (Callable[..., bool]) – The check needed to be valid in order to collect an event.

• timeout (None | timedelta) –

Return type

Callable[…, Collector]

RESTClient

class rin.RESTClient

The class used to make RESTful API requests.

This class implements requesting which works in tandem with the concurrent request ratelimit system. Allows for safe requesting and bucket depletion handling.

Note

The session attribute is only set after at least 1 request.

Parameters

• token (str) – The token used for authorization.

• client (GatewayClient) – The client being used.

session

The session assiocated with the RESTClient.

Type

aiohttp.ClientSession

token

The token used for authorization.

Type

str

client

The client being used.

Type

GatewayClient

semaphores

The semaphores used for each bucket. This is used to ensure safety and allowing concurrent requests.

Type

dict[str, asyncio.Semaphore]

async connect(url)

Makes a connection to the gateway.

Parameters

url (str) – The url of the gateway.

Returns

The gateway after connection is made.

Return type

Gateway

async request(method, route, **kwargs)

Makes a request to the Route.

A safe request method of the client. Ensures bucket depletion is safe along with global ratelimits.

Parameters

• method (str) – The method to make the request with, E.g “GET”.

• route (Route) – The route to use for the request

• kwargs (Any) – Extra things to pass to the request, E.g json=payload.

Raises

.HTTPException – Something went wrong with the request.

Returns

The return data from the request.

Return type

Any

Route

class rin.Route

BASE = 'https://discord.com/api/v{0}/'

Route used for RESTful requests.

This class is used in the wrapper where requests are made. The wrapper does not have a centralized part that has all predefined RESTful calls. The wrapper will instead utilize Routes in class depedent methods to make their respective requests.

Parameters

• endpoint (str) – The endpoint of the Route.

• version (str) – The version of the RESTful API to use.

• channel_id (None | int) – The channel ID being used. This is used for bucket specificity.

• guild_id (None | int) – The guild ID being used. This is used for bucket specificity.

• webhook_id (None | int) – The webhook ID being used. This is used for bucket specificity.

• webhook_token (None | str) – The webhook token being used. This is used for bucket specificity.

endpoint

The fully formed endpoint of the route.

Type

str

event

The event used for the bucket once depleted. Used in tandem with the concurrent request ratelimit system. Allowing safe concurrent requests.

Type

asyncio.Event

channel_id

The channel ID being used. This is used for bucket specificity.

Type

None | int

guild_id

The guild ID being used. This is used for bucket specificity.

Type

None | int

webhook_id

The webhook ID being used. This is used for bucket specificity.

Type

None | int

webhook_token

The webhook token being used. This is used for bucket specificity.

Type

None | str

property bucket: str

The bucket of the Route.

Errors

Errors used in the wrapper.

HTTPException

exception rin.HTTPException

Bases: Exception

Represents an error when making a request.

Parameters

data (dict[str, Any]) – The data of the error received from the RESTful API.

data

The data of the error.

Type

dict[str, Any]

property code: int

The error’s code.

property message: str

The error’s message.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

BadRequest

exception rin.BadRequest

Bases: rin.rest.errors.HTTPException

Represents a 400 HTTP error.

Forbidden

exception rin.Forbidden

Bases: rin.rest.errors.HTTPException

Represents a 403 HTTP error.

NotFound

exception rin.NotFound

Bases: rin.rest.errors.HTTPException

Represents a 404 HTTP error.

Unauthorized

exception rin.Unauthorized

Bases: rin.rest.errors.HTTPException

Represents a 401 HTTP error.

Builders

Model builders.

IntentsBuilder

class rin.IntentsBuilder

A helper class for Intents. Creates an intent value from passed in keyword-arguments.

Note

All valid intents for Intents.create() are shown below but with lowercased names. Privileged intents are prefixed with a !.

NAME	VALUE	USE
GUILDS	1 << 0	GUILD_CREATE GUILD_UPDATE GUILD_DELETE GUILD_ROLE_CREATE GUILD_ROLE_UPDATE GUILD_ROLE_DELETE CHANNEL_CREATE CHANNEL_UPDATE CHANNEL_DELETE CHANNEL_PINS_UPDATE THREAD_CREATE THREAD_UPDATE THREAD_DELETE THREAD_LIST_SYNC THREAD_MEMBER_UPDATE THREAD_MEMBERS_UPDATE * STAGE_INSTANCE_CREATE STAGE_INSTANCE_UPDATE STAGE_INSTANCE_DELETE
!GUILD_MEMBERS	1 << 1	GUILD_MEMBER_ADD GUILD_MEMBER_UPDATE GUILD_MEMBER_REMOVE THREAD_MEMBERS_UPDATE *
GUILD_BANS	1 << 2	GUILD_BAN_ADD GUILD_BAN_REMOVE
GUILD_EMOJIS_AND_STICKERS	1 << 3	GUILD_EMOJIS_UPDATE GUILD_STICKERS_UPDATE
GUILD_INTEGRATIONS	1 << 4	GUILD_INTEGRATIONS_UPDATE INTEGRATION_CREATE INTEGRATION_UPDATE INTEGRATION_DELETE
GUILD_WEBHOOKS	1 << 5	WEBHOOKS_UPDATE
GUILD_INVITES	1 << 6	INVITE_CREATE INVITE_DELETE
GUILD_VOICE_STATES	1 << 7	VOICE_STATE_UPDATE
!GUILD_PRESENCES	1 << 8	PRESENCE_UPDATE
GUILD_MESSAGES	1 << 9	MESSAGE_CREATE MESSAGE_UPDATE MESSAGE_DELETE MESSAGE_DELETE_BULK
GUILD_MESSAGE_REACTIONS	1 << 10	MESSAGE_REACTION_ADD MESSAGE_REACTION_REMOVE MESSAGE_REACTION_REMOVE_ALL MESSAGE_REACTION_REMOVE_EMOJI
GUILD_MESSAGE_TYPING	1 << 11	TYPING_START
DIRECT_MESSAGES	1 << 12	MESSAGE_CREATE MESSAGE_UPDATE MESSAGE_DELETE CHANNEL_PINS_UPDATE
DIRECT_MESSAGE_REACTIONS	1 << 13	MESSAGE_REACTION_ADD MESSAGE_REACTION_REMOVE MESSAGE_REACTION_REMOVE_ALL MESSAGE_REACTION_REMOVE_EMOJI
DIRECT_MESSAGE_TYPING	1 << 14	TYPING_START
GUILD_SCHEDULED_EVENTS	1 << 16	GUILD_SCHEDULED_EVENT_CREATE GUILD_SCHEDULED_EVENT_UPDATE GUILD_SCHEDULED_EVENT_DELETE GUILD_SCHEDULED_EVENT_USER_ADD GUILD_SCHEDULED_EVENT_USER_REMOVE

classmethod create(**kwargs)

Creates an intents instance with a value specific to the passed in keyword-arguments.

Examples

intents = Intents.create(guild_members=True)

Parameters

kwargs (bool) – Keyword-arguments specific to the Intent with True/False value.

Returns

A created intents instance with a value corresponding to the keyword-arguments passed.

Return type

Intents

classmethod default(**kwargs)

Creates an intents instance without privileged intents.

Parameters

kwargs (class:bool) – Extra intents to create along side the default ones.

Returns

A created intents instance with the corresponding value.

Return type

Intents

classmethod privileged(**kwargs)

Creates an intents instance with only privileged intents.

Parameters

kwargs (class:bool) – Extra intents to create along side the privileged ones.

Returns

A created intents instance with the corresponding value.

Return type

Intents

classmethod none()

Creates an intents instance without any intents.

Returns

A created intents instance with no value.

Return type

Intents

EmbedBuilder

class rin.EmbedBuilder

classmethod from_dict(data)

Creates an Embed object from a dict.

Parameters

data (dict) – The data to create the embed from

Returns

A created embed from the dict.

Return type

EmbedBuilder

to_dict()

Creates a dict representing the embed.

Returns

The dict representing the embed.

Return type

dict

property title: None | str

The embed’s title.

property description: None | str

The embed’s description.

property url: None | str

The embed’s url.

property timestamp: None | datetime

The embed’s timestamp.

property color: None | int

The embed’s color.

property footer: None | EmbedFooter

The embed’s footer.

set_footer(text, icon_url=None)

Sets the embed’s footer.

Parameters

• text (str) – The text of the footer

• icon_url (None | str) – The icon url of the footer

Return type

None

property image: None | EmbedImage

The embed’s image.

set_image(url, height=None, width=None)

Sets the embed’s image.

Parameters

• url (str) – The url of the image.

• height (None | :class``int`) – The height of the image.

• width (None | int) – The width of the image.

Return type

None

property thumbnail: None | EmbedThumbnail

The embed’s thumbnail.

set_thumbnail(url, height=None, width=None)

Sets the embed’s thumbnail.

Parameters

• url (str) – The url of the image.

• height (None | int) – The height of the thumbnail.

• width (None | int) – The width of the thumbnail.

Return type

None

property video: None | EmbedVideo

The embed’s video.

set_video(url, height=None, width=None)

Sets the embed’s video.

Parameters

• url (str) – The url of the video.

• height (None | int) – The height of the video.

• width (None | int) – The width of the video.

Return type

None

property provider: None | EmbedProvider

The embed’s provider.

set_provider(name=None, url=None)

Sets the embed’s provider.

Parameters

• name (None | str) – The name of the provider.

• url (None | str) – The url of the provider.

Return type

None

property author: None | EmbedAuthor

The embed’s author.

set_author(name, url=None, icon_url=None)

Sets the embed’s author.

Parameters

• name (str) – The name of the author.

• url (None | str) – The url of the author.

• icon_url (None | str) – The icon url of the author.

Return type

None

property fields: None | list[EmbedField]

The embed’s fields.

add_field(name, value, inline=False)

Adds a field to the embed.

Parameters

• name (str) – The fields name

• value (str) – The value of the field

• inline (bool) – Whether or not the field is inline

Return type

None

MessageBuilder

class rin.MessageBuilder

A helper class used to add messaging functionality.

This class is intended to be used both internally and in frontend. It is encouraged to construct this class when sending a message without an object. This allows for users to not have a full object to send messages.

client

The client being used to send a message.

Type

GatewayClient

snowflake

The snowflake of the channel to send a message to.

Type

Snowflake

set_snowflake(snowflake)

A helper method ued to set the snowflake of the instance. Useful for classes such as a DM Channel.

Parameters

snowflake (Snowflake) – The snowflake to set.

Return type

None

async send(content=None, tts=False, embeds=[], files=[], rows=[], reply=None, mentions=AllowedMentions(everyone=True, roles=True, users=True, replied_user=True))

Sends a message into the channel corresponding to the passed in Snowflake.

Parameters

• content (None | str) – The content to give the message.

• tts (bool) – If the message should be sent with text-to-speech. Defaults to False.

• embeds (list) – A list of EmbedBuilder instances to send with the message.

• files (list) – A list of File instances to send with the message.

• reply (None | Message) – The message to reply to.

• mentions (AllowedMentions) – The allowed mentions of the message.

• rows (list[ActionRow]) –

Returns

An instance of the newly sent message.

Return type

Message

ANSIBuilder

class rin.ANSIBuilder

A helper class to build ANSI codeblocks.

lines

A list of str which have been created. This will be all joined together when finalizing the construction.

Type

list

new(text, *, mode=Mode.BOLD, fore=Color.DEFAULT, back=Color.DEFAULT, reset_after=True, new_line=True)

Creates a new string using the mode passed in.

Parameters

• text (str) – The message to color/style.

• mode (Mode) – The mode to use, E.g BOLD, DIM etc.

• fore (Color) – The foreground color to use.

• back (Color) – The background color to use.

• reset_after (bool) – If a reset code should be added after adding the new line.

• new_line (bool) – If a new line should be added after adding this one.

Return type

None

colorful(text, *, mode=Mode.BOLD)

Turns a string into a colorful one.

Parameters

• text (str) – The text to turn colorful.

• mode (Mode) – The mode to use for the text.

Return type

None

clear()

Clears the current lines of the builder.

Return type

None

property text: str

A string form of all the messages currently inside of the builders lines.

property final: str

Returns an ANSI codeblock with the string form of the builder.

class rin.Mode

Mode enum. Holds all supported ANSI modes.

ESCAPE

The ANSI escape unicode.

Type

str

RESET

The ANSI escape reset code.

Type

str

BOLD

The ANSI escape bold code.

Type

str

DIM

The ANSI escape dim code.

Type

str

UNDERLINE

The ANSI escape underline code.

Type

str

class rin.Color

Color enum. Holds all supported ANSI colors.

Each enum contains a tuple of two elements, the first being the forground color code, and the second being the background color code.

BLACK

The black color codes.

Type

tuple

RED

The red color codes.

Type

tuple

GREEN

The green color codes.

Type

tuple

YELLOW

The yellow color codes.

Type

tuple

BLUE

The blue color codes.

Type

tuple

MAGENTA

The magenta color codes.

Type

tuple

CYAN

The cyan color codes.

Type

tuple

WHITE

The white color codes.

Type

tuple

DEFAULT

The default color code.

Type

tuple

Assets

Classes/Models used for assets.

File

class rin.File

A helper class for files.

Parameters

• fp (str | os.PathLike | bytes) – The file path of the class, or source.

• name (None | str) – The name of the file.

fp

The file path of the class, or source.

Type

str | os.PathLike | bytes

name

The name of the file.

Type

None | str

source

The source of the file.

Type

bytes

read(size)

Reads the bytes of the file.

Parameters

size (None | int) – The size of bytes to read up to.

Returns

The read bytes.

Return type

bytes

close()

Closes the file.

Return type

None

Models

Models in the wrapper.

BaseModel

class rin.BaseModel

static field(key=None, type=<class 'str'>, **kwargs)

Sets a field for the class.

Acts as almost a placeholder value. Actual value is set on construction.

Parameters

• key (None | str) – The key to do the data lookup with.

• type (type) – The type to use when constructing.

• kwargs (Any) – Extra options to pass to attr.field().

Return type

Any

static property(key, type=<class 'str'>, **kwargs)

Sets a property of the class. Used for adding a constructor.

Parameters

• key (None | str) – The key to do the data lookup from.

• type (type) – The type to use when constructing.

• kwargs (Any) – Extra arguments to pass to attr.field().

Return type

Callable[…, Any]

construct()

This method actually handles construction of attributes.

This method will iterate through all the fields specified on this class. It will then check the type of the field by looking through the metadata.

Return type

None

Snowflake

class rin.Snowflake

Bases: int

Represents a snowflake.

static __new__(cls, *args, **kwargs)

Parameters

• args (Any) –

• kwargs (Any) –

Return type

rin.models.snowflake.Snowflake

property created_at: datetime.datetime

The time at which the snowflake was created.

AllowedMentions

class rin.AllowedMentions

Represents an allowed mentions object.

This is used to determine the allowed mentions of any messages being sent from the client’s user.

Parameters

• everyone (bool) – If mentioning everyone is allowed. By default True.

• roles (bool | list) – Either a list of role IDs, or a boolean value. Determines the allowed roles to be mentioned.

• users (bool | list) – Either a list of user IDs, or a boolean value. Dtermines the allowed users to be mentioned.

• replied_user (bool) – If mentioning the replied user to the message is allowed.

classmethod none()

Creates a AllowedMentions instance that has no allowed mentions set.

Returns

The created instance.

Return type

AllowedMentions

to_dict()

Turns the AllowedMentions instance into a usable dict.

Returns

The created dict from the AllowedMentions instance.

Return type

dict

Message

class rin.Message

Bases: rin.models.base.BaseModel, rin.models.cacheable.Cacheable

Represents a Message.

snowflake

The snowflake of the message.

Type

Snowflake

channel_id

The snowflake of the message’s parent channel.

Type

Snowflake

guild_id

The snowflake of the guild the message was sent in. None if the message was sent inside of a direct-message channel.

Type

None | Snowflake

webhook_id

The snowflake of the webhook if the message was sent from one.

Type

None | Snowflake

application_id

The snowflake of the message’s application.

Type

None | Snowflake

user

The user object of the user who sent the message.

Type

User

member

The member object of the user who sent the message.

Type

dict

content

The content of the message.

Type

str

tts

If the message was sent with text-to-speech.

Type

bool

mentioned_everyone

If the message mentioned everyone.

Type

bool

mention_roles

A list of mentioned roles in the message.

Type

list[dict]

mention_channels

A list of mentioned channels in the message.

Type

list[dict]

attachments

A list of attachments sent with the message.

Type

list[dict]

thread

The thread the message was sent in, if any.

Type

None | dict

sticker_items

A list of stickers sent with the message.

Type

list[dict]

reactions

A list of the reactions on the message.

Type

list[dict]

interaction

The interaction of the message. Only given when the message is an interaction response.

Type

None | dict

components

A list of message components sent with the message.

Type

list[dict]

nonce

Used for validating a message was sent.

Type

None | str

pinned

If the message is pinned.

Type

bool

type

The message’s type.

Type

MessageType

application

The application of the message.

Type

None | dict

message_reference

The message’s reference.

Type

None | dict

embeds

A list of embeds sent with the message.

Type

list[EmbedBuilder]

mentions

A list of mentioned users in the message.

Type

list[User]

timestamp

The timestamp for when the message was created.

Type

datetime.datetime

editted_at

The time when the message was editted. None if the message hasn’t been editted.

Type

datetime.datetime

reference()

Creates a message reference from the instance.

Returns

The created dict representing the message’s reference.

Return type

dict

async reply(content=None, tts=False, embeds=[], files=[], rows=[], mentions=AllowedMentions(everyone=True, roles=True, users=True, replied_user=True))

Sends a message repyling to this message into the channel corresponding to the passed in Snowflake.

Parameters

• content (None | str) – The content to give the message.

• tts (bool) – If the message should be sent with text-to-speech. Defaults to False.

• embeds (list) – A list of EmbedBuilder instances to send with the message.

• files (list) – A list of File instances to send with the message.

• mentions (AllowedMentions) – The allowed mentions of the message.

• rows (list[ActionRow]) –

Returns

An instance of the newly sent message.

Return type

Message

async delete()

Deletes the message.

Raises

.HTTPException – Something went wrong.

Return type

None

async react(reaction)

Adds a reaction to the message.

Parameters

reaction (str) – The reaction to react with.

Raises

.HTTPException – Something went wrong.

Return type

None

async delete_reaction(reaction, user=None)

Deletes a reaction from the message.

Parameters

• reaction (str) – The reaction to delete from the message.

• user (None | User | Snowflake | int) – The user to remove the reaction from. If no user is passed the user will be defaulted to the current authorised user.

Raises

.HTTPException – Something went wrong.

Return type

None

async pin()

Pins the message.

Raises

.HTTPException – Something went wrong while making the request.

Return type

None

async unpin()

Unpins the message.

Raises

.HTTPException – Something went wrong while making the request.

Return type

None

User

class rin.User

Bases: rin.models.base.BaseModel, rin.models.cacheable.Cacheable

Represents a discord user.

snowflake

The snowflake of the user.

Type

Snowflake

discriminator

The user’s discriminator.

Type

str

username

The username of the user.

Type

str

avatar

The avatar hash of the user.

Type

None | str

banner

The banner hash of the user.

Type

None | str

accent_color

The accent color of the user.

Type

None | int

bot :class:`bool`

If the user is a bot user.

system

If the user is an offical discord system user.

Type

bool

mfa_enabled

If the user has mfa enabled.

Type

bool

verified

If the user’s email is verified. Given with the email scope.

Type

bool

email

The user’s email which is connected to the account. Given with the email scope.

Type

None | str

locale

The language option of the user. Given with the identify scope.

Type

None | str

flags

The flags of the user’s account. Given with the identify scope.

Type

int

public_flags

The public flags on the user’s accoumt. Given with the identify scope.

Type

int

premium

The premium type of the user. Given with the identify scope.

Type

int

async edit(username=None, avatar=None)

Edits the current authorized user.

Parameters

• username (None | str) – The new username to give the user.

• avatar (None | bytes) – The new avatar to give the user.

Raises

HTTPException – Something went wrong.

Returns

The user after editting is finished.

Return type

User