1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
:orphan:
v2 to v3 migration guide
========================
With version 3, this library made the switch from being mixed sync and async to being fully async.
On top of that, it also switched from returning the mostly raw api response as dictionaries over to using objects and generators, making the overall usability easier.
But this means that v2 and v3 are not compatible.
In this guide I will give some basic help on how to migrate your existing code.
.. note:: This guide will only show a few examples, please read the documentation for everything you use carefully, its likely that something has changed with every single one!
**Please note that any call mentioned here that starts with a** :code:`await` **will have to be called inside a async function even if not displayed as such!**
Library Initialization
----------------------
You now need to await the Twitch Object and refresh callbacks are now async.
.. code-block:: python
:caption: V2 (before)
from twitchAPI.twitch import Twitch
def user_refresh(token: str, refresh_token: str):
print(f'my new user token is: {token}')
def app_refresh(token: str):
print(f'my new app token is: {token}')
twitch = Twitch('app_id', 'app_secret')
twitch.app_auth_refresh_callback = app_refresh
twitch.user_auth_refresh_callback = user_refresh
.. code-block:: python
:caption: V3 (now)
from twitchAPI.twitch import Twitch
async def user_refresh(token: str, refresh_token: str):
print(f'my new user token is: {token}')
async def app_refresh(token: str):
print(f'my new app token is: {token}')
twitch = await Twitch('my_app_id', 'my_app_secret')
twitch.app_auth_refresh_callback = app_refresh
twitch.user_auth_refresh_callback = user_refresh
Working with the API results
----------------------------
As detailed above, the API now returns Objects instead of pure dictionaries.
Below are how each one has to be handled. View the documentation of each API method to see which type is returned.
TwitchObject
^^^^^^^^^^^^
A lot of API calls return a child of :py:const:`~twitchAPI.object.TwitchObject` in some way (either directly or via generator).
You can always use the :py:const:`~twitchAPI.object.TwitchObject.to_dict()` method to turn that object to a dictionary.
Example:
.. code-block:: python
blocked_term = await twitch.add_blocked_term('broadcaster_id', 'moderator_id', 'bad_word')
print(blocked_term.id)
IterTwitchObject
^^^^^^^^^^^^^^^^
Some API calls return a special type of TwitchObject.
These usually have some list inside that you may want to dicrectly itterate over in your API usage but that also contain other usefull data
outside of that List.
Example:
.. code-block:: python
lb = await twitch.get_bits_leaderboard()
print(lb.total)
for e in lb:
print(f'#{e.rank:02d} - {e.user_name}: {e.score}')
AsyncIterTwitchObject
^^^^^^^^^^^^^^^^^^^^^
A few API calls will have usefull data outside of the list the pagination itterates over.
For those cases, this object exist.
Example:
.. code-block:: python
schedule = await twitch.get_channel_stream_schedule('user_id')
print(schedule.broadcaster_name)
async for segment in schedule:
print(segment.title)
AsyncGenerator
^^^^^^^^^^^^^^
AsyncGenerators are used to automatically itterate over all possible resuts of your API call, this will also automatically handle pagination for you.
In some cases (for example stream schedules with repeating entries), this may result in a endless stream of entries returned so make sure to add your own
exit conditions in such cases.
The generated objects will always be children of :py:const:`~twitchAPI.object.TwitchObject`, see the docs of the API call to see the exact object type.
Example:
.. code-block:: python
async for tag in twitch.get_all_stream_tags():
print(tag.tag_id)
PubSub
------
All callbacks are now async.
.. code-block:: python
:caption: V2 (before)
# this will be called
def callback_whisper(uuid: UUID, data: dict) -> None:
print('got callback for UUID ' + str(uuid))
pprint(data)
.. code-block:: python
:caption: V3 (now)
async def callback_whisper(uuid: UUID, data: dict) -> None:
print('got callback for UUID ' + str(uuid))
pprint(data)
EventSub
--------
All `listen_` and `unsubscribe_` functions are now async
.. code-block:: python
:caption: listen and unsubscribe in V2 (before)
event_sub.unsubscribe_all()
event_sub.listen_channel_follow(user_id, on_follow)
.. code-block:: python
:caption: listen and unsubscribe in V3 (now)
await event_sub.unsubscribe_all()
await event_sub.listen_channel_follow(user_id, on_follow)
:const:`~twitchAPI.eventsub.EventSub.stop()` is now async
.. code-block:: python
:caption: stop() in V2 (before)
event_sub.stop()
.. code-block:: python
:caption: stop() in V3 (now)
await event_sub.stop()
|
