yawaflua/Flask-Discord
1
0
Fork 0
mirror of https://github.com/yawaflua/Flask-Discord.git synced 2025-12-09 20:09:30 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation

Browse Source
This commit is contained in:
thecosmos
2019-05-08 15:46:24 +05:30
parent b34f201155
commit ce488393e6
7 changed files with 282 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
README.md
View File

@@ -1 +1,68 @@
# Flask-Discord # Flask-Discord
Discord OAuth2 extension for Flask.
### Installation
To install current latest release you can use following command:
```sh
python3 -m pip install Flask-Discord
```
### Basic Example
```python
from flask import Flask, redirect, url_for
from flask_discord import DiscordOAuth2Session
CONFIGS = {
"client_id": 9999999999,
"client_secret": "your client secret",
"redirect_uri": "default redirect uri",
}
app = Flask(__name__)
app.secret_key = "random bytes representing flask secret key"
discord = DiscordOAuth2Session(**CONFIGS)
@app.route("/login")
def login():
return discord.create_session()
@app.route("/callback")
def callback():
discord.callback()
return redirect(url_for(".me"))
@app.route("/me")
def me():
user = discord.fetch_user()
return f"""
<html>
<head>
<title>{user.name}</title>
</head>
<body>
<img src='{user.avatar_url}' />
</body>
</html>
"""
if __name__ == "__main__":
app.run()
```
### Requirements
* Flask
* requests_oauthlib
### Documentation

3
flask_discord/__init__.py
View File

@@ -4,3 +4,6 @@ from .client import DiscordOAuth2Session
__all__ = [ __all__ = [
"DiscordOAuth2Session", "DiscordOAuth2Session",
] ]
__version__ = "0.0.1"

55
flask_discord/_http.py
View File

@@ -1,4 +1,5 @@
import os import os
import abc
from . import configs from . import configs
@@ -6,7 +7,20 @@ from flask import session, jsonify
from requests_oauthlib import OAuth2Session from requests_oauthlib import OAuth2Session
class DiscordOAuth2HttpClient(object): class DiscordOAuth2HttpClient(abc.ABC):
"""An OAuth2 http abstract base class providing some factory methods.
This class is meant to be overridden by flask_discord.DiscordOAuth2Session class.
Attributes
----------
client_id : int
The client ID of discord application provided.
client_secret : str
The client secret of discord application provided.
redirect_uri : str
The default URL to use to redirect user to after authorization.
"""
def __init__(self, client_id, client_secret, redirect_uri): def __init__(self, client_id, client_secret, redirect_uri):
self.client_id = client_id self.client_id = client_id
@@ -19,7 +33,25 @@ class DiscordOAuth2HttpClient(object):
def _token_updater(token): def _token_updater(token):
session["oauth2_token"] = token session["oauth2_token"] = token
def _make_session(self, token=None, state=None, scope=None): def _make_session(self, token: str = None, state: str = None, scope: list = None) -> OAuth2Session:
"""A low level method used for creating OAuth2 session.
Parameters
----------
token : str, optional
The authorization token to use which was previously received from authorization code grant.
state : str, optional
The state to use for OAuth2 session.
scope : list, optional
List of valid `Discord OAuth2 Scopes
<https://discordapp.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes>`_.
Returns
-------
OAuth2Session
An instance of OAuth2Session class.
"""
return OAuth2Session( return OAuth2Session(
client_id=self.client_id, client_id=self.client_id,
token=token or session.get("oauth2_token"), token=token or session.get("oauth2_token"),
@@ -33,7 +65,24 @@ class DiscordOAuth2HttpClient(object):
auto_refresh_url=configs.TOKEN_URL, auto_refresh_url=configs.TOKEN_URL,
token_updater=self._token_updater) token_updater=self._token_updater)
def get(self, route): def get(self, route: str) -> dict:
"""Sends HTTP GET 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 GET request to.
Example: ``/users/@me``
Returns
-------
dict
Dictionary containing received from sent HTTP GET request.
"""
return self._make_session().get(configs.API_BASE_URL + route).json() return self._make_session().get(configs.API_BASE_URL + route).json()
def get_json(self): def get_json(self):

38
flask_discord/client.py
View File

@@ -4,8 +4,38 @@ from flask import request, session, redirect
class DiscordOAuth2Session(_http.DiscordOAuth2HttpClient): class DiscordOAuth2Session(_http.DiscordOAuth2HttpClient):
"""Main client class representing hypothetical OAuth2 session with discord.
It uses Flask `session <http://flask.pocoo.org/docs/1.0/api/#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 which
def create_session(self, scope=None): Parameters
----------
client_id : int
Client ID of your discord application.
client_secret : str
Client secret of your discord application.
redirect_uri : str
The default URL to be used to redirect user after the OAuth2 authorization.
"""
def create_session(self, scope: list = None):
"""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
<https://discordapp.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes>`_.
Returns
-------
redirect
Flask redirect to discord authorization servers to complete authorization code grant process.
"""
scope = scope or request.args.get("scope", str()).split() or configs.DEFAULT_SCOPES scope = scope or request.args.get("scope", str()).split() or configs.DEFAULT_SCOPES
discord_session = self._make_session(scope=scope) discord_session = self._make_session(scope=scope)
authorization_url, state = discord_session.authorization_url(configs.AUTHORIZATION_BASE_URL) authorization_url, state = discord_session.authorization_url(configs.AUTHORIZATION_BASE_URL)
@@ -13,6 +43,12 @@ class DiscordOAuth2Session(_http.DiscordOAuth2HttpClient):
return redirect(authorization_url) return redirect(authorization_url)
def callback(self): def callback(self):
"""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 <http://flask.pocoo.org/docs/1.0/api/#flask.session>`_ object.
"""
if request.values.get("error"): if request.values.get("error"):
return request.values["error"] return request.values["error"]
discord = self._make_session(state=session.get("oauth2_state")) discord = self._make_session(state=session.get("oauth2_state"))

63
flask_discord/models/connections.py
View File

@@ -2,15 +2,44 @@ from .user import User
class Integration(object): class Integration(object):
""""Class representing discord server integrations.
Attributes
----------
id : int
Integration ID.
name : str
Name of integration.
type : str
Integration type (twitch, youtube, etc).
enabled : bool
A boolean representing if this integration is enabled.
syncing : bool
A boolean representing if this integration is syncing.
role_id : int
ID that this integration uses for subscribers.
expire_behaviour : int
An integer representing the behaviour of expiring subscribers.
expire_grace_period : int
An integer representing the grace period before expiring subscribers.
user : User
Object representing user of this integration.
account : dict
A dictionary representing raw
`account <https://discordapp.com/developers/docs/resources/guild#integration-account-object>`_ object.
synced_at : ISO8601 timestamp
Representing when this integration was last synced.
"""
def __init__(self, payload): def __init__(self, payload):
self._payload = payload self._payload = payload
self.id = self._payload.get("id") self.id = int(self._payload.get("id", 0))
self.name = self._payload.get("name") self.name = self._payload.get("name")
self.type = self._payload.get("type") self.type = self._payload.get("type")
self.enabled = self._payload.get("enabled") self.enabled = self._payload.get("enabled")
self.syncing = self._payload.get("syncing") self.syncing = self._payload.get("syncing")
self.role_id = self._payload.get("role_id") self.role_id = int(self._payload.get("role_id", 0))
self.expire_behaviour = self._payload.get("expire_behaviour") self.expire_behaviour = self._payload.get("expire_behaviour")
self.expire_grace_period = self._payload.get("expire_grace_period") self.expire_grace_period = self._payload.get("expire_grace_period")
self.user = User(self._payload.get("user", dict())) self.user = User(self._payload.get("user", dict()))
@@ -19,10 +48,37 @@ class Integration(object):
class UserConnection(object): class UserConnection(object):
"""Class representing connections in discord account of the user.
Attributes
----------
id : int
ID of the connection account.
name : str
The username of the connection account.
type : str
The service of connection (twitch, youtube).
revoked : bool
A boolean representing whether the connection is revoked.
integrations : list
A list of server Integration objects.
verified : bool
A boolean representing whether the connection is verified.
friend_sync : bool
A boolean representing whether friend sync is enabled for this connection.
show_activity : bool
A boolean representing whether activities related to this connection will
be shown in presence updates.
visibility : int
An integer representing
`visibility <https://discordapp.com/developers/docs/resources/user#user-object-visibility-types>`_
of this connection.
"""
def __init__(self, payload): def __init__(self, payload):
self._payload = payload self._payload = payload
self.id = self._payload.get("id") self.id = int(self._payload.get("id", 0))
self.name = self._payload.get("name") self.name = self._payload.get("name")
self.type = self._payload.get("type") self.type = self._payload.get("type")
self.revoked = self._payload.get("revoked") self.revoked = self._payload.get("revoked")
@@ -37,4 +93,5 @@ class UserConnection(object):
@property @property
def is_visible(self): def is_visible(self):
"""A property returning bool if this integration is visible to everyone."""
return bool(self.visibility) return bool(self.visibility)

19
flask_discord/models/guild.py
View File

@@ -2,10 +2,26 @@ from .. import configs
class Guild(object): class Guild(object):
"""Class representing discord Guild the user is part of.
Attributes
----------
id : int
Discord ID of the guild.
name : str
Name of the guild.
icon_hash : str
Hash of guild's icon.
is_owner : bool
Boolean determining if current user is owner of the guild or not.
permissions_value : int
An integer representing permissions of current user in the guild.
"""
def __init__(self, payload): def __init__(self, payload):
self._payload = payload self._payload = payload
self.id = self._payload["id"] self.id = int(self._payload["id"])
self.name = self._payload["name"] self.name = self._payload["name"]
self.icon_hash = self._payload.get("icon") self.icon_hash = self._payload.get("icon")
self.is_owner = self._payload.get("owner") self.is_owner = self._payload.get("owner")
@@ -16,4 +32,5 @@ class Guild(object):
@property @property
def icon_url(self): def icon_url(self):
"""A property returning direct URL to the guild's icon."""
return configs.GUILD_ICON_BASE_URL.format(guild_id=self.id, icon_hash=self.icon_hash) return configs.GUILD_ICON_BASE_URL.format(guild_id=self.id, icon_hash=self.icon_hash)

47
flask_discord/models/user.py
View File

@@ -2,12 +2,42 @@ from .. import configs
class User(object): class User(object):
"""Class representing Discord User.
Attributes
----------
id : int
The discord ID of the user.
username : str
The discord username of the user.
discriminator : int
4 - digits discord tag of the user.
avatar_hash : str
Hash of users avatar.
bot : bool
A boolean representing whether the user belongs to an OAuth2 application.
mfa_enabled : bool
A boolean representing whether the user has two factor enabled on their account.
locale : str
The user's chosen language option.
verified : bool
A boolean representing whether the email on this account has been verified.
email : str
User's email ID.
flags : int
An integer representing the
`user flags <https://discordapp.com/developers/docs/resources/user#user-object-user-flags>`_.
premium_type : int
An integer representing the
`type of nitro subscription <https://discordapp.com/developers/docs/resources/user#user-object-premium-types>`_.
"""
def __init__(self, payload): def __init__(self, payload):
self._payload = payload self._payload = payload
self.id = self._payload["id"] self.id = int(self._payload["id"])
self.username = self._payload["username"] self.username = self._payload["username"]
self.discriminator = self._payload["discriminator"] self.discriminator = int(self._payload["discriminator"])
self.avatar_hash = self._payload.get("avatar", self.discriminator) self.avatar_hash = self._payload.get("avatar", self.discriminator)
self.bot = self._payload.get("bot", False) self.bot = self._payload.get("bot", False)
self.mfa_enabled = self._payload.get("mfa_enabled") self.mfa_enabled = self._payload.get("mfa_enabled")
@@ -22,20 +52,33 @@ class User(object):
@property @property
def name(self): def name(self):
"""An alias to the username attribute."""
return self.username return self.username
@property @property
def avatar_url(self): def avatar_url(self):
"""A property returning direct URL to user's avatar."""
return configs.USER_AVATAR_BASE_URL.format(user_id=self.id, avatar_hash=self.avatar_hash) return configs.USER_AVATAR_BASE_URL.format(user_id=self.id, avatar_hash=self.avatar_hash)
@property @property
def is_avatar_animated(self): def is_avatar_animated(self):
"""A boolean representing if avatar of user is animated. Meaning user has GIF avatar."""
return self.avatar_hash.startswith("a_") return self.avatar_hash.startswith("a_")
def to_json(self): def to_json(self):
"""A utility method which returns raw user object as it was returned from discord.
Returns
-------
dict
A dict of user's document.
"""
return self._payload return self._payload
class Bot(User): class Bot(User):
"""Class representing the client user itself.
"""
pass pass