Merge branch 'master' into feature/ws-eventsub

# Conflicts:
#	.github/workflows/build.yml

Author: IAmTomahawkx

.github/workflows/build.yml

@@ -3,15 +3,15 @@ name: Build
 on:
   push:
   pull_request:
-    types: [opened, reopened, edited, synchronize]
+    types: [opened, edited, synchronize]
 
 jobs:
   lib:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.7", "3.10", "3.11"]
 
     steps:
       - name: Checkout
@@ -44,7 +44,7 @@ jobs:
       - name: Install CPython
         uses: actions/setup-python@v2
         with:
-          python-version: 3.x
+          python-version: 3.7
 
       - name: Install Deps
         run: |
@@ -68,7 +68,7 @@ jobs:
     - name: Setup Python
       uses: actions/setup-python@v2
       with:
-        python-version: 3.8
+        python-version: 3.7
 
     - name: install black
       run: |

docs/changelog.rst

@@ -1,19 +1,68 @@
 :orphan:
 
-
 Master
 ======
+- TwitchIO
+    - Bug fixes
+        - Fix :func:`~twitchio.Client.search_categories` due to :attr:`~twitchio.Game.igdb_id` being added to :class:`~twitchio.Game`
+        - Made Chatter :attr:`~twitchio.Chatter.id` property public
+
+- Other
+    - [speed] extra
+        - Added wheels on external pypi index for cchardet and ciso8601
+        - Bumped ciso8601 from >=2.2,<2.3 to >=2.2,<3
+        - Bumped cchardet from >=2.1,<2.2 to >=2.1,<3
+
+2.6.0
+======
 - TwitchIO
     - Additions
         - Added optional ``started_at`` and ``ended_at`` arguments to :func:`~twitchio.PartialUser.fetch_clips`
         - Updated docstring regarding new  HypeTrain contribution  method ``OTHER`` for :attr:`~twitchio.HypeTrainContribution.type`
+        - Add support for ``ciso8601`` if installed
+        - Added ``speed`` install flag (``pip install twitchio[speed]``) to install all available speedups
+        - Added :attr:`~twitchio.Game.igdb_id` to :class:`~twitchio.Game`
+        - Added ``igdb_ids`` argument to :func:`~twitchio.Client.fetch_games`
+        - Added ``tags`` attribute to :class:`~twitchio.Stream`, :class:`~twitchio.ChannelInfo` and :class:`~twitchio.SearchUser`
+        - Added :func:`~twitchio.PartialUser.fetch_shield_mode_status`
+        - Added :func:`~twitchio.PartialUser.update_shield_mode_status`
+        - Added :func:`~twitchio.PartialUser.fetch_followed_streams`
+        - Added :func:`~twitchio.PartialUser.shoutout`
+        - Added ``type`` arg to :func:`~twitchio.Client.fetch_streams`
 
     - Bug fixes
         - Fix :func:`~twitchio.PartialUser.fetch_bits_leaderboard` not handling ``started_at`` and :class:`~twitchio.BitsLeaderboard` not correctly parsing
+        - Fix parsing :class:`~twitchio.ScheduleSegment` where :attr:`~twitchio.ScheduleSegment.end_time` is None
+        - Fix auto reconnect of websocket. Created tasks by asyncio.create_task() need to be referred to prevent task disappearing (garbage collection)
+        - Strip newlines from message content when sending or replying to IRC websocket
+        - Removed unnessecary assert from :func:`~twitchio.Client.fetch_streams`
 
 - ext.eventsub
+    - Documentation
+        - Updated quickstart example to reflect proper usage of callback
     - Additions
         - Updated docs regarding new HypeTrain contribution method ``other`` for :attr:`~twitchio.ext.eventsub.HypeTrainContributor.type`
+        - Added Shield Status events
+            - :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_shield_mode_begin`
+            - :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_shield_mode_end`
+        - Added Shoutout events
+            - :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_shoutout_create`
+            - :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_shoutout_receive`
+        - Added :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_follows_v2`
+        - Added support for ``type`` and ``user_id`` queries on :func:`~twitchio.ext.eventsub.EventSubClient.get_subscriptions`
+
+    - Deprecations
+        - :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_follows`, use :func:`~twitchio.ext.eventsub.EventSubClient.subscribe_channel_follows_v2`
+
+
+- ext.pubsub
+    - Bug fixes
+        - Fix forced RECONNECT messages
+
+    - Additions
+        - Added proper message when wrong type is passed to a topic argument
+        - Added auth failure hook: :func:`~twitchio.ext.pubsub.PubSubPool.auth_fail_hook`
+        - Added reconnect hook: :func:`~twitchio.ext.pubsub.PubSubPool.reconnect_hook`
 
 2.5.0
 ======

docs/exts/eventsub.rst

@@ -11,7 +11,7 @@ Twitch will send you an HTTP request containing information on the event. This e
 integrating seamlessly into the twitchio Client event dispatching system.
 
 .. warning::
-    This ext requires you to have a public facing ip, and to be able to receive inbound requests.
+    This ext requires you to have a public facing ip AND domain, and to be able to receive inbound requests.
 
 .. note::
     Twitch requires EventSub targets to have TLS/SSL enabled (https). TwitchIO does not support this, as such you should
@@ -26,7 +26,7 @@ A Quick Example
     import twitchio
     from twitchio.ext import eventsub, commands
     bot = commands.Bot(token="...")
-    eventsub_client = eventsub.EventSubClient(bot, "some_secret_string", "/callback")
+    eventsub_client = eventsub.EventSubClient(bot, "some_secret_string", "https://your-url.here/callback")
     # when subscribing (you can only await inside coroutines)
 
     await eventsub_client.subscribe_channel_subscriptions(channel_ID)
@@ -64,7 +64,7 @@ Running Eventsub Inside a Commands Bot
             self.loop.create_task(esclient.listen(port=4000))
 
             try:
-                await esclient.subscribe_channel_follows(broadcaster=channel_ID)
+                await esclient.subscribe_channel_follows_v2(broadcaster=some_channel_ID, moderator=a_channel_mod_ID)
             except twitchio.HTTPException:
                 pass
 
@@ -77,7 +77,7 @@ Running Eventsub Inside a Commands Bot
 
 
     @esbot.event()
-    async def event_eventsub_notification_follow(payload: eventsub.ChannelFollowData) -> None:
+    async def event_eventsub_notification_followV2(payload: eventsub.ChannelFollowData) -> None:
         print('Received event!')
         channel = bot.get_channel('channel')
         await channel.send(f'{payload.data.user.name} followed woohoo!')
@@ -192,6 +192,22 @@ This is a list of events dispatched by the eventsub ext.
 
     Called when a hype train ends on their channel.
 
+.. function:: event_eventsub_notification_channel_shield_mode_begin(event: ChannelShieldModeBeginData)
+
+    Called when a channel's Shield Mode status is activated.
+
+.. function:: event_eventsub_notification_channel_shield_mode_end(event: ChannelShieldModeEndData)
+
+    Called when a channel's Shield Mode status is deactivated.
+
+.. function:: event_eventsub_notification_channel_shoutout_create(event: ChannelShoutoutCreateData)
+
+    Called when a channel sends a shoutout.
+
+.. function:: event_eventsub_notification_channel_shoutout_receive(event: ChannelShoutoutReceiveData)
+
+    Called when a channel receives a shoutout.
+
 API Reference
 --------------
 
@@ -219,6 +235,30 @@ API Reference
     :members:
     :inherited-members:
 
+.. attributetable::: ChannelShieldModeBeginData
+
+.. autoclass:: ChannelShieldModeBeginData
+    :members:
+    :inherited-members:
+
+.. attributetable::: ChannelShieldModeEndData
+
+.. autoclass:: ChannelShieldModeEndData
+    :members:
+    :inherited-members:
+
+.. attributetable::: ChannelShoutoutCreateData
+
+.. autoclass:: ChannelShoutoutCreateData
+    :members:
+    :inherited-members:
+
+.. attributetable::: ChannelShoutoutReceiveData
+
+.. autoclass:: ChannelShoutoutReceiveData
+    :members:
+    :inherited-members:
+
 .. attributetable::: ChannelSubscribeData
 
 .. autoclass:: ChannelSubscribeData

docs/exts/pubsub.rst

@@ -212,6 +212,32 @@ If the topic requires multiple channel ids, they should be passed as such:
         listen_to_id = 12345
         topic = pubsub.whispers(user_token)[listen_to_id]
 
+Hooks
+------
+
+There are two hooks available in the PubSubPool class. To access these hooks, subclass the PubSubPool.
+After subclassing, use the subclass like normal.
+
+The ``auth_fail_hook`` is called whenever you attempt to subscribe to a topic and the auth token is invalid.
+From the hook, you are able to fix your token (maybe you need to prompt the user for a new token), and then subscribe again.
+
+The ``reconnect_hook`` is called whenevever a node has to reconnect to twitch, for any reason. The node will wait for you to
+return a list of topics before reconnecting. Any modifications to the topics will be applied to the node.
+
+.. code-block:: python3
+
+    from typing import List
+    from twitchio.ext import pubsub
+
+    class MyPool(pubsub.PubSubPool):
+        async def auth_fail_hook(self, topics: List[pubsub.Topic]) -> None:
+            fixed_topics = fix_my_auth_tokens(topics) # somehow fix your auth tokens
+            await self.subscribe_topics(topics)
+
+        async def reconnect_hook(self, node: pubsub.PubSubWebsocket, topics: List[pubsub.Topic]) -> List[pubsub.Topic]:
+            return topics
+
+
 Api Reference
 --------------
 

docs/index.rst

@@ -67,7 +67,7 @@
    Consider joining the Official Discord server for a fast response to help.<br>
    <a href="https://discord.gg/RAKc3HF"><img src="https://discordapp.com/api/guilds/490948346773635102/widget.png?style=banner2"></a><br><br>
 
-   <b>For issues and contributing with the library, visit:</b> <a href"https://github.com/TwitchIO/TwitchIO">GitHub</a>
+   <b>For issues and contributing with the library, visit:</b> <a href="https://github.com/TwitchIO/TwitchIO">GitHub</a>
 
 
 .. rst-class:: index-display-none

docs/installing.rst

@@ -25,3 +25,55 @@ Make sure you have the latest version of Python installed, or if you prefer, a P
 
 If you have have any other issues feel free to search for duplicates and then create a new issue on GitHub with as much detail as
 possible. Including providing the output of pip, your OS details and Python version.
+
+
+Extras
+-------
+Twitchio has some extra downloaders available to modify the library.
+Due to some outdated binaries on the pypi package index, when using Python 3.11+, you'll want to make use of our custom pypi
+index for these extras. You can access this index by doing the following (replace your-extra with the extra you want to use):
+
+.. code:: sh
+
+    python3 -m pip install -U twitchio[your-extra] --extra-index-url https://pip.twitchio.dev/
+
+Or, on windows:
+
+.. code:: sh
+
+    py -3.11 -m pip install -U twitchio[your-extra] --extra-index-url https://pip.twitchio.dev/
+
+
+If you do not wish to use our custom index, you can build the wheels yourself by installing cython through pip prior to installing the extra.
+Note that you will need C build tools installed to be able to do this.
+
+Extra: speed
+++++++++++++++
+The speed extra will install dependancies built in C that are considerably faster than their pure-python equivalents.
+You can install the speed extra by doing:
+
+.. code:: sh
+
+    python3 -m pip install -U twitchio[speed] --extra-index-url https://pip.twitchio.dev/
+
+Or, on windows:
+
+.. code:: sh
+
+    py -3.11 -m pip install -U twitchio[speed] --extra-index-url https://pip.twitchio.dev/
+
+Extra: sounds
++++++++++++++++
+The sounds extra installs extra dependancies for using the sounds ext.
+If you wish to use the sounds ext, you will need to install this extra, which you can do by doing the following:
+
+
+.. code:: sh
+
+    python3 -m pip install -U twitchio[sounds] --extra-index-url https://pip.twitchio.dev/
+
+Or, on windows:
+
+.. code:: sh
+
+    py -3.11 -m pip install -U twitchio[sounds] --extra-index-url https://pip.twitchio.dev/

docs/reference.rst

@@ -324,6 +324,13 @@ SearchUser
 .. autoclass:: SearchUser
     :members:
 
+ShieldStatus
+------------
+.. attributetable:: ShieldStatus
+
+.. autoclass:: ShieldStatus
+    :members:
+
 Stream
 ----------
 .. attributetable:: Stream

examples/eventsub.py

@@ -12,7 +12,7 @@ def __init__(self):
     async def __ainit__(self) -> None:
         self.loop.create_task(esclient.listen(port=4000))
         try:
-            await esclient.subscribe_channel_follows(broadcaster=channel_ID)
+            await esclient.subscribe_channel_follows_v2(broadcaster=channel_id, moderator=moderator_id)
         except twitchio.HTTPException:
             pass
 
@@ -25,7 +25,7 @@ async def event_ready(self):
 
 
 @esbot.event()
-async def event_eventsub_notification_follow(payload: eventsub.ChannelFollowData) -> None:
+async def event_eventsub_notification_followV2(payload: eventsub.ChannelFollowData) -> None:
     print("Received event!")
     channel = bot.get_channel("channel")
     await channel.send(f"{payload.data.user.name} followed woohoo!")

setup.py

@@ -52,7 +52,12 @@
     "yt-dlp>=2022.2.4",
     'pyaudio==0.2.11; platform_system!="Windows"',
 ]
-extras_require = {"sounds": sounds}
+speed = [
+    "ujson>=5.2,<6",
+    "ciso8601>=2.2,<3",
+    "cchardet>=2.1,<3"
+]
+extras_require = {"sounds": sounds, "speed": speed}
 
 setup(
     name="twitchio",
@@ -81,6 +86,8 @@
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
         "Topic :: Internet",
         "Topic :: Software Development :: Libraries",
         "Topic :: Software Development :: Libraries :: Python Modules",

twitchio/__init__.py

@@ -28,7 +28,7 @@
 __author__ = "TwitchIO, PythonistaGuild"
 __license__ = "MIT"
 __copyright__ = "Copyright 2017-2022 (c) TwitchIO"
-__version__ = "2.5.0"
+__version__ = "2.6.0"
 
 from .client import Client
 from .user import *