Skip to content

Commit 8953b0f

Browse files
EvieePyEvieePy
committed
Base reference docs for adapters.
1 parent 7c9e171 commit 8953b0f

File tree

4 files changed

+169
-1
lines changed

4 files changed

+169
-1
lines changed

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ References
6464
references/user
6565
references/eventsub_subscriptions
6666
references/exceptions
67+
references/web
6768

6869
.. toctree::
6970
:maxdepth: 1

‎docs/references/web.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. currentmodule:: twitchio
2+
3+
4+
Web/OAuth Reference
5+
###################
6+
7+
.. attributetable:: twitchio.web.AiohttpAdapter
8+
9+
.. autoclass:: twitchio.web.AiohttpAdapter
10+
:members:
11+
12+
.. attributetable:: twitchio.web.StarletteAdapter
13+
14+
.. autoclass:: twitchio.web.StarletteAdapter
15+
:members:

‎twitchio/web/aio_adapter.py‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,81 @@
5353

5454

5555
class AiohttpAdapter(BaseAdapter, web.Application):
56+
"""The AiohttpAdapter for OAuth and Webhook based EventSub.
57+
58+
This adapter uses ``aiohttp`` which is a base dependency and should be installed and available with Twitchio.
59+
60+
Optionally you can use `Starlette <https://www.starlette.io/>`_ with `Uvicorn <https://www.uvicorn.org/>`_ by using the
61+
:class:`StarletteAdapter`. This will require additional dependencies.
62+
63+
An adapter will always be started and is ran alongside the :class:`~twitchio.Client` or
64+
:class:`~twitchio.ext.commands.Bot` by default. You can disable starting the adapter by passing ``with_adapter=False``
65+
to :meth:`twitchio.Client.start` or :meth:`twitchio.Client.run`.
66+
67+
The adapter can be used to authenticate users via OAuth, and supports webhooks for EventSub, with in-built event
68+
dispatching to the :class:`~twitchio.Client`.
69+
70+
The default callbacks for OAuth are:
71+
72+
- ``/oauth`` E.g. ``http://localhost:4343/oauth`` or ``https://mydomain.org/oauth``.
73+
- Should be used with the ``?scopes=`` query parameter to pass a URL encoded list of scopes.
74+
See: :class:`~twitchio.Scopes` for a helper class for generating scopes.
75+
76+
- ``/oauth/callback`` E.g. ``http://localhost:4343/oauth/callback`` or ``https://mydomain.org/oauth/callback``.
77+
- The redirect URL for OAuth request. This should be set in the developer console of your application on Twitch.
78+
79+
The default callbacks for EventSub are:
80+
81+
- ``/callback`` E.g. ``http://localhost:4343/callback`` or ``https://mydomain.org/callback``.
82+
83+
84+
This class handles processing and validating EventSub requests for you, and dispatches any events identical to
85+
the websocket equivalent.
86+
87+
Parameters
88+
----------
89+
host: str | None
90+
An optional :class:`str` passed to bind as the host address. Defaults to ``localhost``.
91+
port: int | None
92+
An optional :class:`int` passed to bind as the port for the host address. Defaults to ``4343``.
93+
domain: str | None
94+
An optional :class:`str` passed used to identify the external domain used, if any. If passed, the domain will be used
95+
for the redirect URL in OAuth and for validation in EventSub. It must be publicly accessible and support HTTPS.
96+
eventsub_path: str | None
97+
An optional :class:`str` passed to use as the path to the eventsub callback. Defaults to ``/callback``. E.g.
98+
``http://localhost:4343/callback`` or ``https://mydomain.org/callback``.
99+
eventsub_secret: str | None
100+
An optional :class:`str` passed to use as the EventSub secret. It is recommended you pass this parameter when using
101+
an adapter for EventSub, as it will reset upon restarting otherwise. You can generate token safe secrets with the
102+
:mod:`secrets` module.
103+
104+
Examples
105+
--------
106+
107+
.. code-block:: python3
108+
109+
import twitchio
110+
from twitchio import web
111+
from twitchio.ext import commands
112+
113+
114+
class Bot(commands.Bot):
115+
116+
def __init__(self) -> None:
117+
# Requests will be sent to, as an example:
118+
# http://bot.twitchio.dev
119+
# You DO NOT need to pass a domain, however not passing a domain will mean only you can authenticate
120+
# via OAuth and Webhooks will not be supported...
121+
# The domain should support HTTPS and be publicly accessible...
122+
# An easy way to do this is add your domain to a CDN like Cloudflare and set SSL to Flexible.
123+
#
124+
# Visit: http://localhost:8080/oauth?scopes=channel:bot as the broadcaster as an example.
125+
# Visit: https://bot.twitchio.dev?scopes=channel:bot as the broadcaster as an example.
126+
127+
adapter = web.AiohttpAdapter(domain="bot.twitchio.dev", port=8080)
128+
super().__init__(adapter=adapter)
129+
"""
130+
56131
client: Client
57132

58133
def __init__(
@@ -99,10 +174,12 @@ def __init_subclass__(cls: type[AiohttpAdapter]) -> None:
99174

100175
@property
101176
def eventsub_url(self) -> str:
177+
"""Property returning the fully qualified URL to the EventSub callback."""
102178
return f"{self._domain}{self._eventsub_path}"
103179

104180
@property
105181
def redirect_url(self) -> str:
182+
"""Property returning the fully qualified URL to the OAuth callback."""
106183
return f"{self._domain}/oauth/callback"
107184

108185
async def event_startup(self) -> None:
@@ -165,7 +242,6 @@ async def eventsub_callback(self, request: web.Request) -> web.Response:
165242
except Exception as e:
166243
return web.Response(text=f"Challenge Failed. Failed to verify the integrity of the message: {e}", status=400)
167244

168-
# TODO: Types...
169245
data: Any = _from_json(resp) # type: ignore
170246
sent: datetime.datetime = parse_timestamp(timestamp)
171247
now: datetime.datetime = datetime.datetime.now(tz=datetime.UTC)

‎twitchio/web/starlette_adapter.py‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,80 @@
5858

5959

6060
class StarletteAdapter(BaseAdapter, Starlette):
61+
"""The StarletteAdapter for OAuth and Webhook based EventSub.
62+
63+
This adapter uses ``starlette`` which is an optional dependency and needs to be installed.
64+
65+
Optionally you can use `Aiohttp <https://docs.aiohttp.org/en/stable/>`_ by using the :class:`AiohttpAdapter`.
66+
67+
An adapter will always be started and is ran alongside the :class:`~twitchio.Client` or
68+
:class:`~twitchio.ext.commands.Bot` by default. You can disable starting the adapter by passing ``with_adapter=False``
69+
to :meth:`twitchio.Client.start` or :meth:`twitchio.Client.run`.
70+
71+
The adapter can be used to authenticate users via OAuth, and supports webhooks for EventSub, with in-built event
72+
dispatching to the :class:`~twitchio.Client`.
73+
74+
The default callbacks for OAuth are:
75+
76+
- ``/oauth`` E.g. ``http://localhost:4343/oauth`` or ``https://mydomain.org/oauth``.
77+
- Should be used with the ``?scopes=`` query parameter to pass a URL encoded list of scopes.
78+
See: :class:`~twitchio.Scopes` for a helper class for generating scopes.
79+
80+
- ``/oauth/callback`` E.g. ``http://localhost:4343/oauth/callback`` or ``https://mydomain.org/oauth/callback``.
81+
- The redirect URL for OAuth request. This should be set in the developer console of your application on Twitch.
82+
83+
The default callbacks for EventSub are:
84+
85+
- ``/callback`` E.g. ``http://localhost:4343/callback`` or ``https://mydomain.org/callback``.
86+
87+
88+
This class handles processing and validating EventSub requests for you, and dispatches any events identical to
89+
the websocket equivalent.
90+
91+
Parameters
92+
----------
93+
host: str | None
94+
An optional :class:`str` passed to bind as the host address. Defaults to ``localhost``.
95+
port: int | None
96+
An optional :class:`int` passed to bind as the port for the host address. Defaults to ``4343``.
97+
domain: str | None
98+
An optional :class:`str` passed used to identify the external domain used, if any. If passed, the domain will be used
99+
for the redirect URL in OAuth and for validation in EventSub. It must be publicly accessible and support HTTPS.
100+
eventsub_path: str | None
101+
An optional :class:`str` passed to use as the path to the eventsub callback. Defaults to ``/callback``. E.g.
102+
``http://localhost:4343/callback`` or ``https://mydomain.org/callback``.
103+
eventsub_secret: str | None
104+
An optional :class:`str` passed to use as the EventSub secret. It is recommended you pass this parameter when using
105+
an adapter for EventSub, as it will reset upon restarting otherwise. You can generate token safe secrets with the
106+
:mod:`secrets` module.
107+
108+
Examples
109+
--------
110+
111+
.. code-block:: python3
112+
113+
import twitchio
114+
from twitchio import web
115+
from twitchio.ext import commands
116+
117+
118+
class Bot(commands.Bot):
119+
120+
def __init__(self) -> None:
121+
# Requests will be sent to, as an example:
122+
# http://bot.twitchio.dev
123+
# You DO NOT need to pass a domain, however not passing a domain will mean only you can authenticate
124+
# via OAuth and Webhooks will not be supported...
125+
# The domain should support HTTPS and be publicly accessible...
126+
# An easy way to do this is add your domain to a CDN like Cloudflare and set SSL to Flexible.
127+
#
128+
# Visit: http://localhost:8080/oauth?scopes=channel:bot as the broadcaster as an example.
129+
# Visit: https://bot.twitchio.dev?scopes=channel:bot as the broadcaster as an example.
130+
131+
adapter = web.StarletteAdapter(domain="bot.twitchio.dev", port=8080)
132+
super().__init__(adapter=adapter)
133+
"""
134+
61135
client: Client
62136

63137
def __init__(
@@ -104,10 +178,12 @@ def __repr__(self) -> str:
104178

105179
@property
106180
def eventsub_url(self) -> str:
181+
"""Property returning the fully qualified URL to the EventSub callback."""
107182
return f"{self._domain}{self._eventsub_path}"
108183

109184
@property
110185
def redirect_url(self) -> str:
186+
"""Property returning the fully qualified URL to the OAuth callback."""
111187
return f"{self._domain}/oauth/callback"
112188

113189
async def event_startup(self) -> None:

0 commit comments

Comments
 (0)