API Reference#

The following section outlines the API of disco_oauth2.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured, these logs will not be output anywhere.

Client#

class disco_oauth2.Client(*, client_id, client_secret, redirect_uri, scopes=None, connector=None, proxy=None, proxy_auth=None, http_trace=None)#

Represents a client that offers interaction to the discord OAuth2 API.

Parameters:

client_id (int) – The OAuth2 application client id.
client_secret (str) – The OAuth2 application client secret.
redirect_uri (str) – The OAuth2 redirect url. This url must configurated from uri’s at discord developer portal.
scopes (Optional[List[str]]) – List of OAuth2 scopes. Default None.
connector (Optional[aiohttp.BaseConnector]) – A connector for aiohttp client API. aiohttp documentation. Default None.
proxy (Optional[str]) – The proxy URL. Default None.
proxy_auth (Optional[aiohttp.BasicAuth]) –
Object that represents proxy HTTP Basic Authorization. aiohttp documentation. Default None.
http_trace (Optional[aiohttp.TraceConfig]) –
The trace configuration to use for tracking HTTP requests the library does using aiohttp. aiohttp documentation. Default None.

async exchange_code(code)#

Exchanges the code you receive from the OAuth2 redirect.

Parameters:: code (str) – The code from the querystring.
Return type:: AccessToken

async refresh_token(refresh_token)#

Refreshes an access token. This can be useful to anticipate the expiration and refresh the token.

Parameters:: refresh_toke (str) – The user’s refresh token.
Return type:: AccessToken

async revoke_token(token)#

Revokes a token, token can be either an access token or an refresh token. This can be useful to invalidate the previous token.

RFC7009.

Note

Invalid tokens do not cause an error response.

Parameters:: token (str) – The refresh or access token that will get revoked.

async fetch_user(access_token)#

Fetch user’s information from discord api using user’s access token.

You must have the scope identify to use this. To access user’s email you must have the scope email.

Parameters:: access_token (AccessToken) – The user’s access token.
Return type:: User

get_oauth_url(*, prompt=..., state=..., response_type='code', disable_guild_select=..., guild_id=..., permissions=..., scopes=..., redirect_uri=...)#

Returns the OAuth2 URL to authorize this application.

Parameters:

prompt (str) – Controls how existing authorizations are handled, either consent or none. You must have scopes set to use this.
state (str) – A unique cryptographically secure hash. discord documentation
response_type (Literal["code", "token"]) – The response type, either code or token. The token is for client-side web applications only. Defaults code.
disable_guild_select (bool) – Disallows the user from changing the guild for the bot invite, either true or false. You must have the scope bot to use this.
guild_id (bool) – The guild id to pre-fill at authorization url. You must have the scope bot to use this.
permissions (int) – The permissions flags for the bot invite. You must have the scope bot to use this.
scopes (Iterable[str]) –
An optional valid list of scopes. Defaults to self.scopes.

New in version 1.3.
redirect_uri (str) –
An optional valid redirect URI. Defaults self.redirect_uri

New in version 1.3.

Return type:

The OAuth2 URL with all the received parameters.

get_partial_user(*, access_token)#

Returns a partial user.

This is useful if you have a access_token but don’t want to do an API call to fetch it again.

Note that this partial user class will not let you use methods that requires user information.

Parameters:: access_token (AccessToken) – The user’s access token.
Return type:: PartialUser

async close()#: Closes and cleanup operations on the client.

AccessToken#

class disco_oauth2.AccessToken#

Represents a access token response information provided by discord.

access_token#

The user’s access token.

Type:: str

token_type#

The token type.

Type:: str

refresh_token#

The user’s refresh token.

Type:: str

expires_in#

When this access token will expire (in seconds).

Type:: int

Discord Models#

User#

class disco_oauth2.User#

Represents your Discord user that contains information from the OAuth2 API.

x == y: Compare the ids of the two users and verify that they are the same.

x != y: Compare the ids of the two users and verify that they are the different.

hash(x): Return the user’s hash.

str(x): Returns the user’s id with discriminator.

id#

The user’s unique id.

Type:: int

name#

The user’s username.

Type:: str

discriminator#

The user’s discriminator.

Type:: str

email#

The user’s email.

Type:: Optional[str]

bot#

If the current user is a bot account.

Type:: bool

system#

If the user is a system user.

Type:: bool

verified#

If the user’s email is verified.

Type:: bool

locale#

The IETF language tag used to identify the language the user is using.

Type:: Optional[str]

mfa_enabled#

Specifies if the user has MFA turned on.

Type:: bool

async refresh()#

Refreshes the access token for the user.

Return type:: AccessToken

async add_guild(guild, bot_token, *, nick=None, roles=None, mute=None, deaf=None)#

Adds a user to the guild.

You must have the scope guilds.join to use this.

Parameters:

guild (Guild) – Guild that the user will join.
bot_token (str) – A bot token that is in the target guild. Discord requires a bot that you have a bot that is in the target guild you want to add the user.
nick (Optional[str]) – Value to set user’s nickname to.
roles (Optional[List[int]]) – A list of role ids that will be added to the member.
mute (Optional[bool]) – Whether the user is muted in voice channels
deaf (Optional[bool]) – Whether the user is deafened in voice channels

async fetch_guilds()#

Fetch a list of partial guilds that the user is a member of.

You must have the scope guilds to use this.

Return type:: List[Guild]

async fetch_connections()#

Fetch a list of connections of the user.

You must have the scope connections to use this.

Return type:: List[Connection]

async fetch_member(guild_id)#

Fetch the user’s object member from guild ID.

You must have the scope guilds.members.read to use this.

Parameters:: guild_id (int) – The guild’s ID that the user is member of
Return type:: Member

property accent_colour#

Returns the user’s accent colour, if applicable.

Note

This property will return the color in hex format.

Type:: Optional[str]

property avatar_url#

Returns the link of cdn for the avatar the user has.

Type:: Optional[str]

property banner#

Returns the user’s banner asset, if available.

Type:: Optional[str]

property created_at#

Returns the date of when the user account was created in UTC.

Type:: datetime.datetime

property default_avatar#

Returns the default avatar for a given user. This is calculated by the user’s discriminator.

Type:: str

property display_avatar#

Returns the user’s display avatar.

This method is similar to avatar_url, but if the user doesn’t have an avatar it will give the default avatar.

Type:: str

property flags#

Returns the resolved flags of the user.

Type:: Permissions

property mention#

Returns a string format to mention this user in discord.

Type:: str

property public_flags#

Returns the resolved public flags of the user.

Type:: Permissions

Guild#

class disco_oauth2.Guild#

Represents a Discord partial guild.

This is referred to as a “server” in the official Discord UI.

x == y: Checks if two guilds are equal.

x != y: Checks if two guilds are not equal.

hash(x): Returns the guild’s hash.

str(x): Returns the guild’s name.

id#

The guild id.

Type:: int

name#

The guild name.

Type:: str

permissions#

An Permissions class that represents the permissions of the user in the guild.

Type:: Optional[Permissions]

features#

A list of features that the guild has.

Type:: Optional[List[str]]

property permissions#

Returns the resolved permissions that the oauth2 user has in this guild.

Type:: Permissions

property icon#

Returns the guild’s icon url, if available.

Type:: Optional[str]

property is_owner#

Returns if the current user is the owner of the guild.

Type:: Optional[str]

Member#

class disco_oauth2.Member#

Represents a Discord member to a Guild.

x == y: Compare the ids of the two members and verify that they are the same.

x != y: Compare the ids of the two members and verify that they are the different.

hash(x): Return the member’s hash.

str(x): Returns the member’s id with discriminator.

user#

The user representation of this member.

Type:: User

guild_id#

The guild ID that the user is member of.

Type:: int

nick#

The guild specific nickname of the user.

Type:: str

roles#

The list of role ids that the member has

Type:: SnowflakeList

joined_at#

An aware datetime object that specifies the date and time in UTC that the member joined the guild.

Type:: datetime.datetime

premium_since#

An aware datetime object that specifies the date andtime in UTC that the member “Nitro boost” the guild. This could be None.

Type:: Optional[datetime.datetime]

deaf#

If the user is deafened in voice channels.

Type:: bool

mute#

If the user is muted in voice channels

Type:: bool

pending#

If the user has not yet passed the guild’s Membership Screening requirements.

Type:: bool

timed_out_until#

An aware datetime object that specifies the date and time in UTC that the user’s time out will expire. This is None when the user is not timed out.

Type:: Optional[datetime.datetime]

property permissions#

Returns the resolved permissions that the oauth2 user has in this guild.

Type:: Permissions

property mention#

Returns a string format to mention this member in discord.

Type:: str

property display_name#

Returns the user’s display name.

Type:: str

property guild_avatar_url#

Returns the link of cdn for the avatar the member has.

Type:: Optional[str]

property display_avatar#

Returns the member’s display avatar.

Type:: str

Connection#

class disco_oauth2.Connection#

Represents connection object that the user has attached.

id#

The connection’s unique id.

Type:: int

name#

The connection’s name.

Type:: str

type#

The service of the connection (twitch, youtube).

Type:: str

revoked#

If the connection is revoked.

Type:: bool

verified#

If the connection is verified.

Type:: bool

friend_sync#

If friend sync is enabled for this connection.

Type:: bool

show_activity#

If activities related to this connection will be shown in presence updates

Type:: bool

visibility#

Visibility of this connection

Type:: Visibility

Integrations#

class disco_oauth2.ServerIntegration#

Represents discord server integrations.

id#

The integration unique id.

Type:: int

name#

The integration name.

Type:: str

type#

The integration type (twitch, youtube, discord, …).

Type:: IntegrationType

enabled#

If this integration enabled.

Type:: bool

syncing#

If this integration syncing.

Type:: bool

role_id#

role id that this integration uses for “subscribers”.

Type:: int

enable_emoticons#

If emoticons should be synced for this integration (twitch only currently).

Type:: Optional[bool]

expire_behavior#

The behavior of expiring subscribers (remove_role or kick).

Type:: Optional[ExpireBehavior]

expire_grace_period#

The grace period (in days) before expiring subscribers.

Type:: int

user#

User for this integration.

Type:: User

account#

Integration account information.

Type:: IntegrationAccount

synced_at#

When this integration was last synced.

Type:: Optional[datetime.datetime]

subscriber_count#

How many subscribers this integration has.

Type:: Optional[int]

revoked#

If has this integration been revoked.

Type:: bool

application#

The bot/OAuth2 application for discord integrations, if available.

Type:: Optional[IntegrationApp]

class disco_oauth2.IntegrationAccount#

Represents integration account.

id#

Id of the account.

Type:: int

name#

Name of the account.

Type:: str

class disco_oauth2.ExpireBehavior#: An enumeration.

class disco_oauth2.IntegrationApp#

Represents the integration application provided by Discord.

id#

The application unique id.

Type:: int

name#

The application name.

Type:: str

description#

The description of the app.

Type:: str

property icon#

Returns the app’s icon url, if available.

Type:: Optional[str]

class disco_oauth2.ExpireBehavior#: An enumeration.

Flags#

Permissions#

class disco_oauth2.Permissions(value)#

create_instant_invite#

Returns True if the user can create instant invites.

Type:: bool

kick_members#

Returns True if the user can kick users from the guild.

Type:: bool

ban_members#

Returns True if a user can ban users from the guild.

Type:: bool

administrator#

Returns True if a user is an administrator. This role overrides all other permissions. This also bypasses all channel-specific overrides.

Type:: bool

manage_channels#

Returns True if a user can edit, delete, or create channels in the guild. This also corresponds to the “Manage Channel” channel-specific override.

Type:: bool

manage_guild#

Returns True if a user can edit guild properties.

Type:: bool

add_reactions#

Returns True if a user can add reactions to messages.

Type:: bool

view_audit_log#

Returns True if a user can view the guild’s audit log.

Type:: bool

priority_speaker#

Returns True if a user can be more easily heard while talking.

Type:: bool

stream#

Returns True if a user can stream in a voice channel.

Type:: bool

read_messages#

Returns True if a user can read messages from all or specific text channels.

Type:: bool

send_messages#

Returns True if a user can send messages from all or specific text channels.

Type:: bool

send_tts_messages#

Returns True if a user can send TTS messages from all or specific text channels.

Type:: bool

manage_messages#

Returns True if a user can delete or pin messages in a text channel.

Type:: bool

embed_links#

Returns True if a user’s messages will automatically be embedded by Discord.

Type:: bool

attach_files#

Returns True if a user can send files in their messages.

Type:: bool

read_message_history#

Returns True if a user can read a text channel’s previous messages.

Type:: bool

mention_everyone#

Returns True if a user’s @everyone or @here will mention everyone in the text channel.

Type:: bool

external_emojis#

Returns True if a user can use emojis from other guilds.

Type:: bool

view_guild_insights#

Returns True if a user can view the guild’s insights.

Type:: bool

connect#

Returns True if a user can connect to a voice channel.

Type:: bool

speak#

Returns True if a user can speak in a voice channel.

Type:: bool

mute_members#

Returns True if a user can mute other users.

Type:: bool

deafen_members#

Returns True if a user can deafen other users.

Type:: bool

move_members#

Returns True if a user can move users between other voice channels.

Type:: bool

use_voice_activation#

Returns True if a user can use voice activation in voice channels.

Type:: bool

change_nickname#

Returns True if a user can change their nickname in the guild.

Type:: bool

manage_nicknames#

Returns True if a user can change other user’s nickname in the guild.

Type:: bool

manage_roles#

Returns True if a user can create or edit roles less than their role’s position. This also corresponds to the “Manage Permissions” channel-specific override.

Type:: bool

manage_webhooks#

Returns True if a user can create, edit, or delete webhooks.

Type:: bool

manage_emojis#

Returns True if a user can create, edit, or delete emojis.

Type:: bool

use_slash_commands#

Returns True if a user can use slash commands.

Type:: bool

request_to_speak#

Returns True if a user can request to speak in a stage channel.

Type:: bool

UserFlags#

class disco_oauth2.UserFlags(value)#

staff#

Returns True if the user is a Discord Employee.

Type:: bool

partner#

Returns True if the user is a Discord Partner.

Type:: bool

hypesquad#

Returns True if the user is a HypeSquad Events member.

Type:: bool

bug_hunter_level_1#

Returns True if the user is a bug hunter level 1.

Type:: bool

bug_hunter#

Returns True if the user is a bug hunter level 1.

Type:: bool

hypesquad_online_house_1#

Returns True if the user is a HypeSquad Bravery member.

Type:: bool

hypesquad_bravery#

Returns True if the user is a HypeSquad Bravery member.

Type:: bool

hypesquad_online_house_2#

Returns True if the user is a HypeSquad Brilliance member.

Type:: bool

hypesquad_brilliance#

Returns True if the user is a HypeSquad Brilliance member.

Type:: bool

hypesquad_online_house_3#

Returns True if the user is a HypeSquad Balance member.

Type:: bool

hypesquad_balance#

Returns True if the user is a HypeSquad Balance member.

Type:: bool

early_supporter#

Returns True if the user is an Early Supporter.

Type:: bool

team_pseudo_user#

Returns True if the user is a Team User.

Type:: bool

team_user#

Returns True if the user is a Team User.

Type:: bool

system#

Returns True if the user is a system user (i.e. represents Discord officially).

Type:: bool

bug_hunter_level_2#

Returns True if the user is a Bug Hunter Level 2

Type:: bool

verified_bot#

Returns True if the user is a Verified Bot.

Type:: bool

verified_developer#

Returns True if the user is an Early Verified Bot Developer.

Type:: bool

certified_moderator#

Returns True if the user is a Discord Certified Moderator.

Type:: bool

bot_http_interactions#

Returns True if the user is a bot that only uses HTTP interactions and is shown in the online member list.

Type:: bool

spammer#

Returns True if the user is flagged as a spammer by Discord.

Type:: bool