API Reference

This sections has reference to all of the available classes, their attributes and available methods.

Discord OAuth2 Client

class quartcord.DiscordOAuth2Session(app, client_id=None, client_secret=None, redirect_uri=None, bot_token=None, users_cache=None, locks_cache=None)

Main client class representing hypothetical OAuth2 session with discord. It uses Quart session local proxy object to save state, authorization token and keeps record of users sessions across different requests. This class inherits quartcord._http.DiscordOAuth2HttpClient class.

Parameters:

• app (Quart) – An instance of your quart application.

• client_id (int, optional) – The client ID of discord application provided. Can be also set to quart config with key DISCORD_CLIENT_ID.

• client_secret (str, optional) – The client secret of discord application provided. Can be also set to quart config with key DISCORD_CLIENT_SECRET.

• redirect_uri (str, optional) – The default URL to use to redirect user to after authorization. Can be also set to quart config with key DISCORD_REDIRECT_URI.

• bot_token (str, optional) – The bot token of the application. This is required when you also need to access bot scope resources beyond the normal resources provided by the OAuth. Can be also set to quart config with key DISCORD_BOT_TOKEN.

• users_cache (cachetools.LFUCache, optional) – Any dict like mapping to internally cache the authorized users. Preferably an instance of cachetools.LFUCache or cachetools.TTLCache. If not specified, default cachetools.LFUCache is used. Uses the default max limit for cache if DISCORD_USERS_CACHE_MAX_LIMIT isn’t specified in app config.

client_id

The client ID of discord application provided.

Type:

int

redirect_uri

The default URL to use to redirect user to after authorization.

Type:

str

users_cache

A dict like mapping to internally cache the authorized users. Preferably an instance of cachetools.LFUCache or cachetools.TTLCache. If not specified, default cachetools.LFUCache is used. Uses the default max limit for cache if DISCORD_USERS_CACHE_MAX_LIMIT isn’t specified in app config.

Type:

cachetools.LFUCache

property authorized

A boolean indicating whether current session has authorization token or not.

async bot_request(route: str, method='GET', **kwargs) → dict | str

Make HTTP request to specified endpoint with bot token as authorization headers.

Parameters:

• route (str) – Route or endpoint URL to send HTTP request to.

• method (str, optional) – Specify the HTTP method to use to perform this request.

Returns:

Dictionary containing received from sent HTTP GET request if content-type is application/json otherwise returns raw text content of the response.

Return type:

dict, str

Raises:

• quartcord.Unauthorized – Raises quartcord.Unauthorized if current user is not authorized.

• quartcord.RateLimited – Raises an instance of quartcord.RateLimited if application is being rate limited by Discord.

async callback()

A method which should be always called after completing authorization code grant process usually in callback view. It fetches the authorization token and saves it quart session object.

async create_session(scope: list | None = None, *, data: dict | None = None, prompt: bool = True, permissions: Permissions | int = 0, **params)

Primary method used to create OAuth2 session and redirect users for authorization code grant.

Parameters:

• scope (list, optional) – An optional list of valid Discord OAuth2 Scopes.

• data (dict, optional) – A mapping of your any custom data which you want to access after authorization grant. Use :py:meth:quartcord.DiscordOAuth2Session.callback to retrieve this data in your callback view.

• prompt (bool, optional) – Determines if the OAuth2 grant should be explicitly prompted and re-approved. Defaults to True. Specify False for implicit grant which will skip the authorization screen and redirect to redirect URI.

• permissions (Union[discord.Permissions, int], optional) – An optional parameter determining guild permissions of the bot while adding it to a guild using discord OAuth2 with bot scope. It is same as generating so called bot invite link which redirects to your callback endpoint after bot authorization flow. Defaults to 0 or no permissions.

• params (kwargs, optional) – Additional query parameters to append to authorization URL for customized OAuth flow.

Returns:

Quart redirect to discord authorization servers to complete authorization code grant process.

Return type:

redirect

async static fetch_connections() → list

This method returns list of user connection objects from internal cache if it exists otherwise makes an API call to do so.

Returns:

List of quartcord.models.UserConnection objects.

Return type:

list

async fetch_guilds(use_cache=True) → list

This method returns list of guild objects from internal cache if it exists otherwise makes an API call to do so.

Parameters:

use_cache (bool, optional) – can be set to False to avoid using the cache.

Returns:

List of quartcord.models.Guild objects.

Return type:

list

async fetch_user() → User

This method returns user object from the internal cache if it exists otherwise makes an API call to do so.

Return type:

quart_discord.models.User

async static get_authorization_token() → dict

A static method which returns a dict containing Discord OAuth2 token and other secrets which was saved previously by :py:meth:`quartcord.DiscordOAuth2Session.save_authorization_token from user’s cookies.

You must override this method if you are implementing server side session handling.

async request(route: str, method='GET', data=None, oauth=True, **kwargs) → dict | str

Sends HTTP request to provided route or discord endpoint.

Note

It automatically prefixes the API Base URL so you will just have to pass routes or URL endpoints.

Parameters:

• route (str) – Route or endpoint URL to send HTTP request to. Example: /users/@me

• method (str, optional) – Specify the HTTP method to use to perform this request.

• data (dict, optional) – The optional payload the include with the request.

• oauth (bool) – A boolean determining if this should be Discord OAuth2 session request or any standard request.

Returns:

Dictionary containing received from sent HTTP GET request if content-type is application/json otherwise returns raw text content of the response.

Return type:

dict, str

Raises:

• quartcord.Unauthorized – Raises quartcord.Unauthorized if current user is not authorized.

• quartcord.RateLimited – Raises an instance of quartcord.RateLimited if application is being rate limited by Discord.

revoke()

This method clears current discord token, state and all session data from quart session. Which means user will have to go through discord authorization token grant flow again. Also tries to remove the user from internal cache if they exist.

async static save_authorization_token(token: dict)

A staticmethod which saves a dict containing Discord OAuth2 token and other secrets to the user’s cookies. Meaning by default, it uses client side session handling.

Override this method if you want to handle the user’s session server side. If this method is overridden then, you must also override quartcord.DiscordOAuth2Session.get_authorization_token().

property user_id: int | None

A property which returns Discord user ID if it exists in quart quart.session object.

Returns:

• int – The Discord user ID of current user.

• None – If the user ID doesn’t exists in quart quart.session.

class quartcord._http.DiscordOAuth2HttpClient(app, client_id=None, client_secret=None, redirect_uri=None, bot_token=None, users_cache=None, locks_cache=None)

An OAuth2 http abstract base class providing some factory methods. This class is meant to be overridden by quartcord.DiscordOAuth2Session and should not be used directly.

async bot_request(route: str, method='GET', **kwargs) → dict | str

Make HTTP request to specified endpoint with bot token as authorization headers.

Parameters:

• route (str) – Route or endpoint URL to send HTTP request to.

• method (str, optional) – Specify the HTTP method to use to perform this request.

Returns:

Dictionary containing received from sent HTTP GET request if content-type is application/json otherwise returns raw text content of the response.

Return type:

dict, str

Raises:

• quartcord.Unauthorized – Raises quartcord.Unauthorized if current user is not authorized.

• quartcord.RateLimited – Raises an instance of quartcord.RateLimited if application is being rate limited by Discord.

async request(route: str, method='GET', data=None, oauth=True, **kwargs) → dict | str

Sends HTTP request to provided route or discord endpoint.

Note

It automatically prefixes the API Base URL so you will just have to pass routes or URL endpoints.

Parameters:

• route (str) – Route or endpoint URL to send HTTP request to. Example: /users/@me

• method (str, optional) – Specify the HTTP method to use to perform this request.

• data (dict, optional) – The optional payload the include with the request.

• oauth (bool) – A boolean determining if this should be Discord OAuth2 session request or any standard request.

Returns:

Dictionary containing received from sent HTTP GET request if content-type is application/json otherwise returns raw text content of the response.

Return type:

dict, str

Raises:

• quartcord.Unauthorized – Raises quartcord.Unauthorized if current user is not authorized.

• quartcord.RateLimited – Raises an instance of quartcord.RateLimited if application is being rate limited by Discord.

property user_id: int | None

A property which returns Discord user ID if it exists in quart quart.session object.

Returns:

• int – The Discord user ID of current user.

• None – If the user ID doesn’t exists in quart quart.session.

Models

class quartcord.models.Guild(payload)

Class representing discord Guild the user is part of.

Operations

x == y

Checks if two guild’s are the same.

x != y

Checks if two guild’s are not the same.

str(x)

Returns the guild’s name.

id

Discord ID of the guild.

Type:

int

name

Name of the guild.

Type:

str

icon_hash

Hash of guild’s icon.

Type:

str

is_owner

Boolean determining if current user is owner of the guild or not.

Type:

bool

permissions

An instance of discord.Permissions representing permissions of current user in the guild.

Type:

discord.Permissions

async classmethod fetch_from_api(cache=True)

A class method which returns an instance or list of instances of this model by implicitly making an API call to Discord. If an instance of quartcord.User exists in the users internal cache who belongs to these guilds then, the cached property quartcord.User.guilds is updated.

Parameters:

cache (bool) – Determines if the quartcord.User.guilds cache should be updated with the new guilds.

Returns:

List of instances of quartcord.Guild to which this user belongs.

Return type:

list[quartcord.Guild, …]

property icon_url

A property returning direct URL to the guild’s icon. Returns None if guild has no icon set.

to_json()

A utility method which returns raw payload object as it was received from discord.

Returns:

A dict representing raw payload object received from discord.

Return type:

dict

class quartcord.models.User(payload)

Class representing Discord User.

Operations

x == y

Checks if two user’s are the same.

x != y

Checks if two user’s are not the same.

str(x)

Returns the user’s name with discriminator.

id

The discord ID of the user.

Type:

int

username

The discord username of the user.

Type:

str

display_name

The global display name of the user.

Type:

str

discriminator

A four length string representing discord tag of the user (deprecated).

Type:

str

avatar_hash

Hash of users avatar.

Type:

str

bot

A boolean representing whether the user belongs to an OAuth2 application.

Type:

bool

mfa_enabled

A boolean representing whether the user has two factor enabled on their account.

Type:

bool

locale

The user’s chosen language option.

Type:

str

verified

A boolean representing whether the email on this account has been verified.

Type:

bool

email

User’s email ID.

Type:

str

flags

An integer representing the user flags.

Type:

int

premium_type

An integer representing the type of nitro subscription.

Type:

int

connections

A list of quartcord.UserConnection instances. These are cached and this list might be empty.

Type:

list

async add_to_guild(guild_id) → dict

Method to add user to the guild, provided OAuth2 session has already been created with guilds.join scope.

Parameters:

guild_id (int) – The ID of the guild you want this user to be added.

Returns:

A dict of guild member object. Returns an empty dict if user is already present in the guild.

Return type:

dict

Raises:

quartcord.Unauthorized – Raises quartcord.Unauthorized if current user is not authorized.

property avatar_url

A property returning direct URL to user’s avatar.

Parameters:

size (int) – The resolution of the avatar. Can be any power of two between 16 and 4096. Defaults to 1024.

Returns:

• str – The Discord CDN URL to user’s avatar.

• None – If user doesn’t have any avatar set.

property default_avatar_url

A property which returns the default avatar URL as when user doesn’t have any avatar set.

Parameters:

size (int) – The resolution of the avatar. Can be any power of two between 16 and 4096. Defaults to 1024.

Returns:

• str – The Discord CDN URL to user’s avatar.

• None – If user doesn’t have any avatar set.

async fetch_connections() → list

A method which makes an API call to Discord to get user’s connections. It prepares the internal connection cache and returns list of all connection instances.

Returns:

A list of quartcord.UserConnection instances.

Return type:

list

async classmethod fetch_from_api(guilds=False, connections=False)

A class method which returns an instance of this model by implicitly making an API call to Discord. The user returned from API will always be cached and update in internal cache.

Parameters:

• guilds (bool) – A boolean indicating if user’s guilds should be cached or not. Defaults to False. If chose to not cache, user’s guilds can always be obtained from quartcord.Guilds.fetch_from_api().

• connections (bool) – A boolean indicating if user’s connections should be cached or not. Defaults to False. If chose to not cache, user’s connections can always be obtained from quartcord.Connections.fetch_from_api().

Returns:

• cls – An instance of this model itself.

• [cls, …] – List of instances of this model when many of these models exist.

async fetch_guilds() → list

A method which makes an API call to Discord to get user’s guilds. It prepares the internal guilds cache and returns list of all guilds the user is member of.

Returns:

List of quartcord.Guilds instances.

Return type:

list

classmethod get_from_cache()

A class method which returns an instance of this model if it exists in internal cache.

Returns:

• quartcord.User – An user instance if it exists in internal cache.

• None – If the current doesn’t exists in internal cache.

async get_guilds() → list

A method returns the user’s guilds from cache or makes an API call to Discord to get user’s guilds.

Returns:

List of quartcord.Guilds instances.

Return type:

list

property guilds

A cached mapping of user’s guild ID to quartcord.Guild. The guilds are cached when the first API call for guilds is requested, so it might be an empty dict.

property is_avatar_animated

A boolean representing if avatar of user is animated. Meaning user has GIF avatar.

property name

An alias to the username attribute.

to_json()

A utility method which returns raw payload object as it was received from discord.

Returns:

A dict representing raw payload object received from discord.

Return type:

dict

class quartcord.models.Integration(payload)

Class representing discord server integrations.

id

Integration ID.

Type:

int

name

Name of integration.

Type:

str

type

Integration type (twitch, youtube, etc).

Type:

str

enabled

A boolean representing if this integration is enabled.

Type:

bool

syncing

A boolean representing if this integration is syncing.

Type:

bool

role_id

ID that this integration uses for subscribers.

Type:

int

expire_behaviour

An integer representing the behaviour of expiring subscribers.

Type:

int

expire_grace_period

An integer representing the grace period before expiring subscribers.

Type:

int

account

A dictionary representing raw account object.

Type:

dict

synced_at

Representing when this integration was last synced.

Type:

ISO8601 timestamp

class quartcord.models.UserConnection(payload)

Class representing connections in discord account of the user.

id

ID of the connection account.

Type:

str

name

The username of the connection account.

Type:

str

type

The service of connection (twitch, youtube).

Type:

str

revoked

A boolean representing whether the connection is revoked.

Type:

bool

integrations

A list of server Integration objects.

Type:

list

verified

A boolean representing whether the connection is verified.

Type:

bool

friend_sync

A boolean representing whether friend sync is enabled for this connection.

Type:

bool

show_activity

A boolean representing whether activities related to this connection will be shown in presence updates.

Type:

bool

visibility

An integer representing visibility of this connection.

Type:

int

async classmethod fetch_from_api(cache=True)

A class method which returns an instance or list of instances of this model by implicitly making an API call to Discord. If an instance of quartcord.User exists in the users internal cache who are attached to these connections then, the cached property quartcord.User.connections is updated.

Parameters:

cache (bool) – Determines if the quartcord.User.guilds cache should be updated with the new guilds.

Returns:

List of instances of quartcord.UserConnection to which this user belongs.

Return type:

list[quartcord.UserConnection, …]

property is_visible

A property returning bool if this integration is visible to everyone.

to_json()

A utility method which returns raw payload object as it was received from discord.

Returns:

A dict representing raw payload object received from discord.

Return type:

dict

Utilities

@quartcord.requires_authorization

A decorator for quart views which raises exception quartcord.Unauthorized if the user is not authorized from Discord OAuth2.

Exceptions

class quartcord.HttpException

Base Exception class representing a HTTP exception.

class quartcord.RateLimited(json, headers)

A HTTP Exception raised when the application is being rate limited. It provides the response attribute which can be used to get more details of the actual response from the Discord API with few more shorthands to response.json().

message

A message saying you are being rate limited.

Type:

str

json

The actual JSON data received. Shorthand to await response.json().

Type:

dict

headers

The actual response headers received from the API.

Type:

dict

retry_after

The number of milliseconds to wait before submitting another request.

Type:

int

is_global

A value indicating if you are being globally rate limited or not

Type:

bool

class quartcord.Unauthorized

A HTTP Exception raised when user is not authorized.

class quartcord.AccessDenied

Exception raised when user cancels OAuth authorization grant.