API Reference

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

Discord OAuth2 Client

class flask_discord.DiscordOAuth2Session(app=None, client_id=None, client_secret=None, redirect_uri=None, bot_token=None, users_cache=None, proxy=None, proxy_auth=None)

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

Parameters:

• app (Flask) – An instance of your flask application.

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

• client_secret (str, optional) – The client secret of discord application provided. Can be also set to flask 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 flask 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 flask 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.

bot_request(route: str, method='GET', **kwargs) → Union[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:

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

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

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 flask session object.

create_session(scopes: Optional[Union[list, DiscordOAuth2Scope]] = None, *, data: Optional[dict] = None, prompt: bool = True, permissions: Union[Permissions, int] = 0, **params)

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

Parameters:

• scopes (list, optional) – An optional list of valid Discord OAuth2 Scopes from flask_discord.DiscordOAuth2Scope.

• data (dict, optional) – A mapping of your any custom data which you want to access after authorization grant. Use :py:meth:flask_discord.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:

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

Return type:

redirect

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 flask_discord.models.UserConnection objects.

Return type:

list

static fetch_guilds() → list

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

Returns:

List of flask_discord.models.Guild objects.

Return type:

list

static 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:

flask_discord.models.User

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:`flask_discord.DiscordOAuth2Session.save_authorization_token from user’s cookies.

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

init_app(app)

A method to lazily initialize the application. Use this when you’re using flask factory pattern to create your instances of your flask application.

Parameters:

app (Flask) –

An instance of your flask application.

request(route: str, method='GET', data=None, oauth=True, **kwargs) → Union[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:

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

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

revoke()

This method clears current discord token, state and all session data from flask 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.

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 flask_discord.DiscordOAuth2Session.get_authorization_token().

property user_id: Optional[int]

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

Returns:

• int – The Discord user ID of current user.

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

class flask_discord.DiscordOAuth2Scope(value)

These are a list of all the OAuth2 scopes that Discord supports. Some scopes require approval from Discord to use. Requesting them from a user without approval from Discord may cause undocumented/error behavior in the OAuth2 flow.

READ_ACTIVITIES

Allows your app to fetch data from a user’s “Now Playing/Recently Played” list - requires Discord approval.

WRITE_ACTIVITIES

Allows your app to update a user’s activity - requires Discord approval (NOT REQUIRED FOR GAMESDK ACTIVITY MANAGER).

READ_APPLICATION_BUILDS

Allows your app to read build data for a user’s applications.

UPLOAD_APPLICATION_BUILDS

Allows your app to upload/update builds for a user’s applications - requires Discord approval.

APPLICATION_COMMANDS

Allows your app to use Slash Commands in a guild.

UPDATE_APPLICATION_COMMANDS

Allows your app to update its Slash Commands via this bearer token - client credentials grant only.

READ_APPLICATION_ENTITLEMENTS

Allows your app to read entitlements for a user’s applications.

READ_UPDATE_APPLICATION_STORE

Allows your app to read and update store data (SKUs, store listings, achievements, etc.) for a user’s applications.

BOT

For oauth2 bots, this puts the bot in the user’s selected guild by default.

CONNECTIONS

Allows /users/@me/connections to return linked third-party accounts.

EMAIL

Enables /users/@me to return an email.

JOIN_GROUP_DM

Allows your app to join users to a group dm.

GUILDS

Allows /users/@me/guilds to return basic information about all of a user’s guilds.

JOIN_GUILDS

Allows /guilds/{guild.id}/members/{user.id} to be used for joining users to a guild.

IDENTIFY

Allows /users/@me without email.

READ_MESSAGES

For local rpc server api access, this allows you to read messages from all client channels (otherwise restricted to channels/guilds your app creates).

READ_RELATIONSHIPS

Allows your app to know a user’s friends and implicit relationships - requires Discord approval.

RPC

For local rpc server access, this allows you to control a user’s local Discord client - requires Discord approval.

WRITE_RPC_ACTIVITIES

For local rpc server access, this allows you to update a user’s activity - requires Discord approval.

READ_RPC_NOTIFICATIONS

For local rpc server access, this allows you to receive notifications pushed out to the user - requires Discord approval.

READ_RPC_VOICE

For local rpc server access, this allows you to read a user’s voice settings and listen for voice events - requires Discord approval.

READ_RPC_VOICE

For local rpc server access, this allows you to update a user’s voice settings - requires Discord approval.

INCOMING_WEBHOOK

This generates a webhook that is returned in the oauth token response for authorization code grants.

class flask_discord._http.DiscordOAuth2HttpClient(app=None, client_id=None, client_secret=None, redirect_uri=None, bot_token=None, users_cache=None, proxy=None, proxy_auth=None)

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

bot_request(route: str, method='GET', **kwargs) → Union[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:

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

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

init_app(app)

A method to lazily initialize the application. Use this when you’re using flask factory pattern to create your instances of your flask application.

Parameters:

app (Flask) –

An instance of your flask application.

request(route: str, method='GET', data=None, oauth=True, **kwargs) → Union[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:

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

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

property user_id: Optional[int]

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

Returns:

• int – The Discord user ID of current user.

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

Models

class flask_discord.models.Guild(payload)

Class representing discord Guild the user is part of.

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

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 flask_discord.User exists in the users internal cache who belongs to these guilds then, the cached property flask_discord.User.guilds is updated.

Parameters:

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

Returns:

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

Return type:

list[flask_discord.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 flask_discord.models.User(payload)

Class representing Discord User.

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

discriminator

4 length string representing discord tag of the user.

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 flask_discord.UserConnection instances. These are cached and this list might be empty.

Type:

list

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:

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

property avatar_url

A property returning direct URL to user’s avatar.

property default_avatar_url

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

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 flask_discord.UserConnection instances.

Return type:

list

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 flask_discord.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 flask_discord.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.

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 flask_discord.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:

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

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

property guilds

A cached mapping of user’s guild ID to flask_discord.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 flask_discord.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 flask_discord.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

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 flask_discord.User exists in the users internal cache who are attached to these connections then, the cached property flask_discord.User.connections is updated.

Parameters:

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

Returns:

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

Return type:

list[flask_discord.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

@flask_discord.requires_authorization

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

Exceptions

class flask_discord.HttpException

Base Exception class representing a HTTP exception.

class flask_discord.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().

json

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

Type:

dict

message

A message saying you are being rate limited.

Type:

str

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 flask_discord.Unauthorized

A HTTP Exception raised when user is not authorized.

class flask_discord.AccessDenied

Exception raised when user cancels OAuth authorization grant.

Configuration Values

Flask Discord attempts to fetch expected configuration keys from the config of initialized flask app.

DISCORD_CLIENT_ID

Client ID of your Discord application. Can be retrieved from your Discord developers dashboard. This can be also passed as client_id to flask_discord.DiscordOAuth2Session constructor.

DISCORD_CLIENT_SECRET

The client secret of your Discord application. Can also be retrieved from your Discord developers dashboard. This can be also passed as client_secret to flask_discord.DiscordOAuth2Session constructor.

DISCORD_REDIRECT_URI

The default URL to use to redirect user to after authorization. This should be exactly same as what you’ve specified in Redirects in Discord developers dashboard OAuth2 section. This can be also passed as redirect_uri to flask_discord.DiscordOAuth2Session constructor.

DISCORD_BOT_TOKEN

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. This can be also passed as bot_token to flask_discord.DiscordOAuth2Session constructor.

DISCORD_USERS_CACHE_MAX_LIMIT

Flask Discord has an internal caching layer to prevent rate limits. This specifies the max number of users to be cached using the default Last Frequently Used cache implementation. Defaults to 100.