Skip to content

Commit 38f1166

Browse files
treeben77treeben77
committed
created documentation
1 parent 816d518 commit 38f1166

File tree

4 files changed

+320
-0
lines changed

4 files changed

+320
-0
lines changed

‎docs/source/access_token.rst‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
AccessToken
2+
=============================
3+
4+
.. currentmodule:: discord-oauth2.py
5+
6+
.. class:: AccessToken()
7+
8+
.. attribute:: client
9+
10+
The client which generated this AccessToken
11+
12+
:type: :class:`discordoauth2.Client`
13+
14+
.. atribute:: token
15+
16+
The raw token for this AccessToken, you can use :class:`discordoauth2.Client.from_access_token` to use it again.
17+
18+
:type: str
19+
20+
.. atribute:: expires
21+
22+
The number of seconds until it expires from when the instance was created.
23+
24+
:type: int
25+
26+
.. atribute:: scope
27+
28+
A list of scopes that are provided.
29+
30+
:type: list[str]
31+
32+
.. atribute:: refresh_token
33+
34+
The refresh_token for this AccessToken, you can use :class:`discordoauth2.Client.refresh_token` to use this authorization again after it expires.
35+
36+
:type: str
37+
38+
.. atribute:: webhook
39+
40+
The webhook URL if they was a webhook scope.
41+
42+
:type: str
43+
44+
.. atribute:: guild
45+
46+
The guild ID if a bot was added to a guild.
47+
48+
:type: int
49+
50+
.. method:: fetch_identify()
51+
52+
Returns a dictionary with a `user object <https://discord.com/developers/docs/resources/user#user-object-user-structure>`__ which includes email if the email scope is provided
53+
54+
:returns: :class:`dict`
55+
:raises discordoauth2.exceptions.HTTPException: The request failed
56+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the identify scope.
57+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
58+
59+
.. method:: fetch_connections()
60+
61+
Returns a list of `connection objects <https://discord.com/developers/docs/resources/user#connection-object-connection-structure>`__
62+
63+
:returns: :class:`list`
64+
:raises discordoauth2.exceptions.HTTPException: The request failed
65+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the connections scope.
66+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
67+
68+
69+
.. method:: fetch_guilds()
70+
71+
Returns a list of partial `guild objects <https://discord.com/developers/docs/resources/guild#guild-object>`__
72+
73+
:returns: :class:`list`
74+
:raises discordoauth2.exceptions.HTTPException: The request failed
75+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the guilds scope.
76+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
77+
78+
.. method:: fetch_guild_member(guild_id)
79+
80+
Returns a parial `guild member object <https://discord.com/developers/docs/resources/guild#guild-member-object-guild-member-structure>`__
81+
82+
:param int guild_id: The guild ID to retrieve member data from.
83+
84+
:returns: :class:`dict`
85+
:raises discordoauth2.exceptions.HTTPException: The request failed, possibly because the member is not in the guild.
86+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the guilds.member.read scope.
87+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
88+
89+
.. method:: join_guild(guild_id, nick = None, role_ids = None, mute = False, deaf = False)
90+
91+
Adds the user to a guild. The application's bot must also be in the guild, have invite permissions and it's bot token must also be provided.
92+
93+
:param int guild_id: The guild ID to retrieve member data from.
94+
:param str nick: The nickname the member should have when they join.
95+
:param list[int] role_ids: a List of role IDs to assign them when they join.
96+
:param bool mute: Wether they should be server muted when they join.
97+
:param bool deaf: Wether they should be server deafend when they join.
98+
99+
:returns: :class:`dict`
100+
:raises discordoauth2.exceptions.HTTPException: The request failed
101+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the guilds.join scope or the bot isn't in the guild/have the correct permissions.
102+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
103+
104+
.. class:: PartialAccessToken()
105+
106+
.. attribute:: client
107+
108+
The client which generated this AccessToken
109+
110+
:type: :class:`discordoauth2.Client`
111+
112+
.. atribute:: token
113+
114+
The raw token for this AccessToken, you can use :class:`discordoauth2.Client.from_access_token` to use it again.
115+
116+
:type: str
117+
118+
.. method:: fetch_identify()
119+
120+
Returns a dictionary with a `user object <https://discord.com/developers/docs/resources/user#user-object-user-structure>`__ which includes email if the email scope is provided
121+
122+
:returns: :class:`dict`
123+
:raises discordoauth2.exceptions.HTTPException: The request failed
124+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the identify scope.
125+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
126+
127+
.. method:: fetch_connections()
128+
129+
Returns a list of `connection objects <https://discord.com/developers/docs/resources/user#connection-object-connection-structure>`__
130+
131+
:returns: :class:`list`
132+
:raises discordoauth2.exceptions.HTTPException: The request failed
133+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the connections scope.
134+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
135+
136+
137+
.. method:: fetch_guilds()
138+
139+
Returns a list of partial `guild objects <https://discord.com/developers/docs/resources/guild#guild-object>`__
140+
141+
:returns: :class:`list`
142+
:raises discordoauth2.exceptions.HTTPException: The request failed
143+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the guilds scope.
144+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
145+
146+
.. method:: fetch_guild_member(guild_id)
147+
148+
Returns a parial `guild member object <https://discord.com/developers/docs/resources/guild#guild-member-object-guild-member-structure>`__
149+
150+
:param int guild_id: The guild ID to retrieve member data from.
151+
152+
:returns: :class:`dict`
153+
:raises discordoauth2.exceptions.HTTPException: The request failed, possibly because the member is not in the guild.
154+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the guilds.member.read scope.
155+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
156+
157+
.. method:: join_guild(guild_id, nick = None, role_ids = None, mute = False, deaf = False)
158+
159+
Adds the user to a guild. The application's bot must also be in the guild, have invite permissions and it's bot token must also be provided.
160+
161+
:param int guild_id: The guild ID to retrieve member data from.
162+
:param str nick: The nickname the member should have when they join.
163+
:param list[int] role_ids: a List of role IDs to assign them when they join.
164+
:param bool mute: Wether they should be server muted when they join.
165+
:param bool deaf: Wether they should be server deafend when they join.
166+
167+
:returns: :class:`dict`
168+
:raises discordoauth2.exceptions.HTTPException: The request failed
169+
:raises discordoauth2.exceptions.Forbidden: The AccessToken doesn't have the guilds.join scope or the bot isn't in the guild/have the correct permissions.
170+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.

‎docs/source/client.rst‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Client
2+
=============================
3+
4+
.. currentmodule:: discord-oauth2.py
5+
6+
.. class:: Client(id, secret, redirect, bot_token=None)
7+
8+
9+
:param int id: The application ID
10+
:param str secret: The applications secret, this should be secret!
11+
:param str redirect: The redirect URL for oauth2
12+
:param str bot_token: When adding a user to a guild, a bot with sufficent permissions is required. if you're not going to add members to a guild leave this empty.
13+
14+
.. attribute:: id
15+
16+
The application ID
17+
18+
:type: int
19+
20+
.. atribute:: redirect_url
21+
22+
The redirect URL
23+
24+
:type: str
25+
26+
.. method:: from_access_token(access_token)
27+
28+
Creates a PartialAccessToken object from a code. This is useful so you can store the :attr:`PartialAccessToken.token` and then continue using it.
29+
30+
:param str access_token: The code from oauth2, it is the code paramater on successful return redirect urls from discord's oauth2.
31+
32+
:returns: :class:`discordoauth2.PartialAccessToken`
33+
34+
.. method:: exchange_code(code)
35+
36+
Creates an AccessToken object from a code.
37+
38+
:param str code: The code from oauth2, it is the code paramater on successful return redirect urls from discord's oauth2.
39+
40+
:returns: :class:`discordoauth2.AccessToken`
41+
:raises discordoauth2.exceptions.HTTPException: The request failed, usally because the client ID, client, secret, redirect or code is incorrect
42+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
43+
44+
.. method:: refresh_token(refresh_token)
45+
46+
Creates an AccessToken object from a refresh_token. Refresh tokens are to refresh the access token when it expires.
47+
48+
:param str refresh_token: The refresh token, can be found from :attr:`discordoauth2.AccessToken.refresh_token`
49+
50+
:returns: :class:`discordoauth2.AccessToken`
51+
:raises discordoauth2.exceptions.HTTPException: The request failed, usally because the client ID, client, secret, redirect or code is incorrect
52+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
53+
54+
.. method:: client_credentails_grant(scope)
55+
56+
Creates an AccessToken object for the application's owner with the provided scope.
57+
58+
:param list[str] scope: The scope is strings divided by a list.
59+
60+
:returns: :class:`discordoauth2.AccessToken`
61+
:raises discordoauth2.exceptions.HTTPException: The request failed, usally because the client ID, client, secret, redirect or code is incorrect
62+
:raises discordoauth2.exceptions.RateLimited: You're being rate limited.
63+
64+
.. warning::
65+
66+
If the application is owned by a team, you can only request for the `identify` scope. You can also request `applications.commands.update`, but the library does not support it yet.
67+

‎docs/source/conf.py‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
3+
# -- Project information
4+
5+
project = 'discordoauth2.py'
6+
copyright = '2022, TreeBen77'
7+
author = 'TreeBen77'
8+
9+
release = '1.0'
10+
version = '1.0.1'
11+
12+
# -- General configuration
13+
14+
extensions = [
15+
'sphinx.ext.duration',
16+
'sphinx.ext.doctest',
17+
'sphinx.ext.autodoc',
18+
'sphinx.ext.autosummary',
19+
'sphinx.ext.intersphinx',
20+
]
21+
22+
intersphinx_mapping = {
23+
'python': ('https://docs.python.org/3/', None),
24+
'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
25+
}
26+
intersphinx_disabled_domains = ['std']
27+
28+
templates_path = ['_templates']
29+
30+
# -- Options for HTML output
31+
32+
html_theme = 'sphinx_rtd_theme'
33+
34+
# -- Options for EPUB output
35+
epub_show_urls = 'footnote'

‎docs/source/index.rst‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
Welcome to ``discordoauth2.py``!
2+
===============
3+
4+
Table of Contents
5+
----------
6+
7+
.. toctree::
8+
9+
client
10+
11+
Quickstart
12+
-------------------------------------------
13+
14+
Installing
15+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16+
17+
I've finally published the library to PyPi! So now you can use pip.
18+
19+
.. code::
20+
21+
pip install discord-oauth2.py
22+
23+
Example With Flask
24+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25+
26+
Don't forget to replace all the client information on line 20 and 21 with your application's own information. You can leave bot token empty if your not adding members to guilds.
27+
28+
.. code::
29+
import discordoauth2
30+
from flask import Flask, request
31+
32+
client = discordoauth2.Client(849930878276993044, secret="very-secret-code",
33+
redirect="https://findingfakeurlsisprettyhard.tv/oauth2", bot_token="bot-token-only-required-for-guild-joining")
34+
app = Flask(__name__)
35+
36+
@app.route("/oauth2")
37+
def oauth2():
38+
code = request.args.get("code")
39+
40+
access = client.exchange_code(code)
41+
42+
identify = access.fetch_identify()
43+
connections = access.fetch_connections()
44+
guilds = access.fetch_guilds()
45+
46+
return f"""{identify}<br><br>{connections}<br><br>{guilds}"""
47+
48+
app.run("0.0.0.0", 8080)

0 commit comments

Comments
 (0)