Add Shoutout events

Add Shoutout events
Also correct Shield names before release.

Author: chillymosh

docs/changelog.rst

@@ -15,6 +15,7 @@ Master
         - 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`
 
     - Bug fixes
         - Fix :func:`~twitchio.PartialUser.fetch_bits_leaderboard` not handling ``started_at`` and :class:`~twitchio.BitsLeaderboard` not correctly parsing
@@ -27,6 +28,9 @@ Master
         - 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`
 
 2.5.0
 ======

docs/exts/eventsub.rst

@@ -192,14 +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: ShieldModeBegin)
+.. 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: ShieldModeEnd)
+.. 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
 --------------
 
@@ -227,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
@@ -395,18 +427,6 @@ API Reference
     :members:
     :inherited-members:
 
-.. attributetable::: ShieldModeBegin
-
-.. autoclass:: ShieldModeBegin
-    :members:
-    :inherited-members:
-
-.. attributetable::: ShieldModeEnd
-
-.. autoclass:: ShieldModeEnd
-    :members:
-    :inherited-members:
-
 .. attributetable::: StreamOnlineData
 
 .. autoclass:: StreamOnlineData

twitchio/ext/eventsub/models.py

@@ -1314,7 +1314,7 @@ def __init__(self, client: EventSubClient, data: dict):
         self.ended_at: datetime.datetime = _parse_datetime(data["ended_at"])
 
 
-class ShieldModeBegin:
+class ChannelShieldModeBeginData(EventData):
     """
     Represents a Shield Mode activation status.
 
@@ -1336,7 +1336,7 @@ def __init__(self, client: EventSubClient, data: dict):
         self.started_at: datetime.datetime = _parse_datetime(data["started_at"])
 
 
-class ShieldModeEnd:
+class ChannelShieldModeEndData(EventData):
     """
     Represents a Shield Mode activation status.
 
@@ -1358,6 +1358,77 @@ def __init__(self, client: EventSubClient, data: dict):
         self.ended_at: datetime.datetime = _parse_datetime(data["ended_at"])
 
 
+class ChannelShoutoutCreateData(EventData):
+    """
+    Represents a Shoutout event being sent.
+
+    Requires the ``moderator:read:shoutouts`` or ``moderator:manage:shoutouts`` scope.
+
+    Attributes
+    -----------
+    broadcaster: :class:`~twitchio.PartialUser`
+        The broadcaster from who sent the shoutout event.
+    moderator: :class:`~twitchio.PartialUser`
+        The moderator who sent the shoutout event.
+    to_broadcaster: :class:`~twitchio.PartialUser`
+        The broadcaster who the shoutout was sent to.
+    started_at: :class:`datetime.datetime`
+        The datetime the shoutout was sent.
+    viewer_count: :class:`int`
+        The viewer count at the time of the shoutout
+    cooldown_ends_at: :class:`datetime.datetime`
+        The datetime the broadcaster can send another shoutout.
+    target_cooldown_ends_at: :class:`datetime.datetime`
+        The datetime the broadcaster can send another shoutout to the same broadcaster.
+    """
+
+    __slots__ = (
+        "broadcaster",
+        "moderator",
+        "to_broadcaster",
+        "started_at",
+        "viewer_count",
+        "cooldown_ends_at",
+        "target_cooldown_ends_at",
+    )
+
+    def __init__(self, client: EventSubClient, data: dict):
+        self.broadcaster: PartialUser = _transform_user(client, data, "broadcaster_user")
+        self.moderator: PartialUser = _transform_user(client, data, "moderator_user")
+        self.to_broadcaster: PartialUser = _transform_user(client, data, "to_broadcaster_user")
+        self.started_at: datetime.datetime = _parse_datetime(data["started_at"])
+        self.viewer_count: int = data["viewer_count"]
+        self.cooldown_ends_at: datetime.datetime = _parse_datetime(data["cooldown_ends_at"])
+        self.target_cooldown_ends_at: datetime.datetime = _parse_datetime(data["target_cooldown_ends_at"])
+
+
+class ChannelShoutoutReceiveData(EventData):
+    """
+    Represents a Shoutout event being received.
+
+    Requires the ``moderator:read:shoutouts`` or ``moderator:manage:shoutouts`` scope.
+
+    Attributes
+    -----------
+    broadcaster: :class:`~twitchio.PartialUser`
+        The broadcaster receiving shoutout event.
+    from_broadcaster: :class:`~twitchio.PartialUser`
+        The broadcaster who sent the shoutout.
+    started_at: :class:`datetime.datetime`
+        The datetime the shoutout was sent.
+    viewer_count: :class:`int`
+        The viewer count at the time of the shoutout
+    """
+
+    __slots__ = ("broadcaster", "from_broadcaster", "started_at", "viewer_count")
+
+    def __init__(self, client: EventSubClient, data: dict):
+        self.broadcaster: PartialUser = _transform_user(client, data, "broadcaster_user")
+        self.from_broadcaster: PartialUser = _transform_user(client, data, "to_broadcaster_user")
+        self.started_at: datetime.datetime = _parse_datetime(data["started_at"])
+        self.viewer_count: int = data["viewer_count"]
+
+
 _DataType = Union[
     ChannelBanData,
     ChannelUnbanData,
@@ -1386,8 +1457,10 @@ def __init__(self, client: EventSubClient, data: dict):
     UserAuthorizationGrantedData,
     UserAuthorizationRevokedData,
     UserUpdateData,
-    ShieldModeBegin,
-    ShieldModeEnd,
+    ChannelShieldModeBeginData,
+    ChannelShieldModeEndData,
+    ChannelShoutoutCreateData,
+    ChannelShoutoutReceiveData,
 ]
 
 
@@ -1433,8 +1506,11 @@ class _SubscriptionTypes(metaclass=_SubTypesMeta):
     channel_goal_progress = "channel.goal.progress", 1, ChannelGoalBeginProgressData
     channel_goal_end = "channel.goal.end", 1, ChannelGoalEndData
 
-    channel_shield_mode_begin = "channel.shield_mode.begin", 1, ShieldModeBegin
-    channel_shield_mode_end = "channel.shield_mode.end", 1, ShieldModeEnd
+    channel_shield_mode_begin = "channel.shield_mode.begin", 1, ChannelShieldModeBeginData
+    channel_shield_mode_end = "channel.shield_mode.end", 1, ChannelShieldModeEndData
+
+    channel_shoutout_create = "channel.shoutout.create", 1, ChannelShoutoutCreateData
+    channel_shoutout_receive = "channel.shoutout.receive", 1, ChannelShoutoutReceiveData
 
     hypetrain_begin = "channel.hype_train.begin", 1, HypeTrainBeginProgressData
     hypetrain_progress = "channel.hype_train.progress", 1, HypeTrainBeginProgressData

twitchio/ext/eventsub/server.py

@@ -245,6 +245,20 @@ def subscribe_channel_shield_mode_end(
             models.SubscriptionTypes.channel_shield_mode_end, broadcaster, moderator
         )
 
+    def subscribe_channel_shoutout_create(
+        self, broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int]
+    ):
+        return self._subscribe_with_broadcaster_moderator(
+            models.SubscriptionTypes.channel_shield_mode_end, broadcaster, moderator
+        )
+
+    def subscribe_channel_shoutout_receive(
+        self, broadcaster: Union[PartialUser, str, int], moderator: Union[PartialUser, str, int]
+    ):
+        return self._subscribe_with_broadcaster_moderator(
+            models.SubscriptionTypes.channel_shield_mode_end, broadcaster, moderator
+        )
+
     async def subscribe_user_authorization_granted(self):
         return await self._http.create_subscription(
             models.SubscriptionTypes.user_authorization_grant, {"client_id": self.client._http.client_id}

twitchio/user.py

@@ -1582,7 +1582,7 @@ async def shoutout(self, token: str, to_broadcaster_id: int, moderator_id: int):
         Parameters
         -----------
         token: :class:`str`
-            An oauth user token with the ``moderator:manage:shoutouts``scope.
+            An oauth user token with the ``moderator:manage:shoutouts`` scope.
         to_broadcaster: :class:`int`
             The ID of the broadcaster that is recieving the shoutout.
         moderator_id: :class:`int`