Merge branch 'main' of https://github.com/PythonistaGuild/TwitchIO

Author: EvieePy

docs/references/events.rst

@@ -44,6 +44,10 @@ Events Reference
      - :meth:`~eventsub.AdBreakBeginSubscription`
      - :func:`~twitchio.event_ad_break()`
      - :class:`~models.eventsub_.ChannelAdBreakBegin`
+   * - Channel Bits Use
+     - :meth:`~eventsub.ChannelBitsUseSubscription`
+     - :func:`~twitchio.event_bits_use()`
+     - :class:`~models.eventsub_.ChannelBitsUse`
    * - Channel Chat Clear
      - :meth:`~eventsub.ChatClearSubscription`
      - :func:`~twitchio.event_chat_clear()`
@@ -794,6 +798,18 @@ Chat / Messages
 
   :param twitchio.Whisper payload: The EventSub payload for this event.
 
+.. py:function:: event_bits_use(payload: twitchio.ChannelBitsUse) -> None
+  :async:
+
+  Event dispatched whenever Bits are used on a channel.
+    
+  Corresponds to the Twitch EventSub subscription :es-docs:`Channel Bits Use <channelbitsuse>`.
+    
+  You must subscribe to EventSub with :class:`~twitchio.eventsub.ChannelBitsUseSubscription` for each required user
+  to receive this event.
+
+  :param twitchio.ChannelBitsUse payload: The EventSub payload for this event.
+
 Goals
 -----
 

docs/references/eventsub_models.rst

@@ -48,6 +48,11 @@ Eventsub
 .. autoclass:: twitchio.ChannelAdBreakBegin()
     :members:
 
+.. attributetable:: twitchio.ChannelBitsUse
+
+.. autoclass:: twitchio.ChannelBitsUse()
+    :members:
+
 .. attributetable:: twitchio.ChannelChatClear
 
 .. autoclass:: twitchio.ChannelChatClear()
@@ -476,6 +481,16 @@ Eventsub
 .. autoclass:: twitchio.HypeTrainEnd()
     :members:
 
+.. attributetable:: twitchio.PowerUp
+
+.. autoclass:: twitchio.PowerUp()
+    :members:
+
+.. attributetable:: twitchio.PowerUpEmote
+
+.. autoclass:: twitchio.PowerUpEmote()
+    :members:
+
 .. attributetable:: twitchio.ShieldModeBegin
 
 .. autoclass:: twitchio.ShieldModeBegin()

docs/references/eventsub_subscriptions.rst

@@ -34,6 +34,11 @@ Eventsub Subscriptions
 .. autoclass:: AutomodTermsUpdateSubscription
     :members:
 
+.. attributetable:: ChannelBitsUseSubscription
+
+.. autoclass:: ChannelBitsUseSubscription
+    :members:
+
 .. attributetable:: ChannelUpdateSubscription
 
 .. autoclass:: ChannelUpdateSubscription

twitchio/client.py

@@ -334,7 +334,7 @@ async def login(self, *, token: str | None = None, load_tokens: bool = True, sav
         if self._bot_id:
             logger.debug("Fetching Clients self user for %r", self)
             partial = PartialUser(id=self._bot_id, http=self._http)
-            self._user = partial if not self._fetch_self else await partial.user()
+            self._user = await partial.user() if self._fetch_self else partial
 
         await self.setup_hook()
 
@@ -2311,6 +2311,8 @@ async def fetch_eventsub_subscriptions(
         .. note::
             type, status and user_id are mutually exclusive and only one can be passed, otherwise ValueError will be raised.
 
+            This endpoint returns disabled WebSocket subscriptions for a minimum of 1 minute as compared to webhooks which returns disabled subscriptions for a minimum of 10 days.
+
         Parameters
         -----------
         token_for: str | PartialUser | None

twitchio/events.pyi

@@ -76,6 +76,7 @@ async def event_chat_clear_user(payload: twitchio.ChannelChatClearUserMessages)
 async def event_chat_settings_update(payload: twitchio.ChatSettingsUpdate) -> None: ...
 async def event_chat_user_message_hold(payload: twitchio.ChatUserMessageHold) -> None: ...
 async def event_chat_user_message_update(payload: twitchio.ChatUserMessageUpdate) -> None: ...
+async def event_bits_use(payload: twitchio.ChannelBitsUse) -> None: ...
 
 # Shared Chat
 async def event_shared_chat_begin(payload: twitchio.SharedChatSessionBegin) -> None: ...

twitchio/eventsub/enums.py

@@ -99,6 +99,7 @@ class SubscriptionType(enum.Enum):
     ChannelUpdate: Literal["channel.update"]
     ChannelFollow: Literal["channel.follow"]
     ChannelAdBreakBegin: Literal["channel.ad_break.begin"]
+    ChannelBitsUseSubscription: Literal["channel.bits.use"]
     ChannelChatClear: Literal["channel.chat.clear"]
     ChannelChatClearUserMessages: Literal["channel.chat.clear_user_messages"]
     ChannelChatMessage: Literal["channel.chat.message"]
@@ -172,6 +173,7 @@ class SubscriptionType(enum.Enum):
     AutomodMessageUpdate = "automod.message.update"
     AutomodSettingsUpdate = "automod.settings.update"
     AutomodTermsUpdate = "automod.terms.update"
+    ChannelBitsUse = "channel.bits.use"
     ChannelUpdate = "channel.update"
     ChannelFollow = "channel.follow"
     ChannelAdBreakBegin = "channel.ad_break.begin"

twitchio/eventsub/subscriptions.py

@@ -43,6 +43,7 @@
     "AutomodSettingsUpdateSubscription",
     "AutomodTermsUpdateSubscription",
     "ChannelBanSubscription",
+    "ChannelBitsUseSubscription",
     "ChannelCheerSubscription",
     "ChannelFollowSubscription",
     "ChannelModerateSubscription",
@@ -115,6 +116,7 @@
 # Short names: Only map names that require shortening...
 _SUB_MAPPING: dict[str, str] = {
     "channel.ad_break.begin": "ad_break",
+    "channel.bits.use": "bits_use",
     "channel.chat.clear_user_messages": "chat_clear_user",
     "channel.chat.message": "message",  # Sub events?
     "channel.chat.message_delete": "message_delete",
@@ -404,6 +406,51 @@ def condition(self) -> Condition:
         return {"broadcaster_user_id": self.broadcaster_user_id, "moderator_user_id": self.moderator_user_id}
 
 
+class ChannelBitsUseSubscription(SubscriptionPayload):
+    """The ``channel.bits.use`` subscription type sends a notification whenever Bits are used on a channel.
+
+    This event is designed to be an all-purpose event for when Bits are used in a channel and might be updated in the future as more Twitch features use Bits.
+
+    Currently, this event will be sent when a user:
+
+    - Cheers in a channel
+    - Uses a Power-up
+        - Will not emit when a streamer uses a Power-up for free in their own channel.
+
+    .. important::
+        Requires a user access token that includes the ``bits:read`` scope. This must be the broadcaster's token.
+
+        Bits transactions via Twitch Extensions are not included in this subscription type.
+
+    One attribute ``.condition`` can be accessed from this class, which returns a mapping of the subscription
+    parameters provided.
+
+    Parameters
+    ----------
+    broadcaster_user_id: str | PartialUser
+        The ID, or PartialUser, of the broadcaster to subscribe to.
+
+    Raises
+    ------
+    ValueError
+        The parameters "broadcaster_user_id" must be passed.
+    """
+
+    type: ClassVar[Literal["channel.bits.use"]] = "channel.bits.use"
+    version: ClassVar[Literal["1"]] = "1"
+
+    @handle_user_ids()
+    def __init__(self, **condition: Unpack[Condition]) -> None:
+        self.broadcaster_user_id: str = condition.get("broadcaster_user_id", "")
+
+        if not self.broadcaster_user_id:
+            raise ValueError('The parameter "broadcaster_user_id" must be passed.')
+
+    @property
+    def condition(self) -> Condition:
+        return {"broadcaster_user_id": self.broadcaster_user_id}
+
+
 class ChannelUpdateSubscription(SubscriptionPayload):
     """The ``channel.update`` subscription type sends notifications when a broadcaster updates the category, title, content classification labels, or broadcast language for their channel.
 

twitchio/eventsub/websockets.py

@@ -34,16 +34,6 @@
 from ..backoff import Backoff
 from ..exceptions import HTTPException, WebsocketConnectionException
 from ..models.eventsub_ import SubscriptionRevoked, create_event_instance
-from ..types_.conduits import (
-    MessageTypes,
-    MetaData,
-    NotificationMessage,
-    ReconnectMessage,
-    RevocationMessage,
-    WebsocketMessages,
-    WelcomeMessage,
-    WelcomePayload,
-)
 from ..utils import (
     MISSING,
     _from_json,  # type: ignore
@@ -54,7 +44,17 @@
 if TYPE_CHECKING:
     from ..authentication.tokens import ManagedHTTPClient
     from ..client import Client
-    from ..types_.conduits import Condition
+    from ..types_.conduits import (
+        Condition,
+        MessageTypes,
+        MetaData,
+        NotificationMessage,
+        ReconnectMessage,
+        RevocationMessage,
+        WebsocketMessages,
+        WelcomeMessage,
+        WelcomePayload,
+    )
     from ..types_.eventsub import SubscriptionResponse, _SubscriptionData
 
 
@@ -327,7 +327,7 @@ async def _listen(self) -> None:
             self._last_keepalive = datetime.datetime.now()
 
             try:
-                data: WebsocketMessages = cast(WebsocketMessages, _from_json(message.data))
+                data: WebsocketMessages = cast("WebsocketMessages", _from_json(message.data))
             except Exception:
                 logger.warning("Unable to parse JSON in eventsub websocket: <%s>", self)
                 continue
@@ -336,13 +336,13 @@ async def _listen(self) -> None:
             message_type: MessageTypes = metadata["message_type"]
 
             if message_type == "session_welcome":
-                welcome_data: WelcomeMessage = cast(WelcomeMessage, data)
+                welcome_data: WelcomeMessage = cast("WelcomeMessage", data)
 
                 await self._process_welcome(welcome_data)
 
             elif message_type == "session_reconnect":
                 logger.debug('Received "session_reconnect" message from eventsub websocket: <%s>', self)
-                reconnect_data: ReconnectMessage = cast(ReconnectMessage, data)
+                reconnect_data: ReconnectMessage = cast("ReconnectMessage", data)
 
                 await self._process_reconnect(reconnect_data)
 
@@ -352,12 +352,12 @@ async def _listen(self) -> None:
             elif message_type == "revocation":
                 logger.debug('Received "revocation" message from eventsub websocket: <%s>', self)
 
-                revocation_data: RevocationMessage = cast(RevocationMessage, data)
+                revocation_data: RevocationMessage = cast("RevocationMessage", data)
                 await self._process_revocation(revocation_data)
 
             elif message_type == "notification":
                 logger.debug('Received "notification" message from eventsub websocket: <%s>. %s', self, data)
-                notification_data: NotificationMessage = cast(NotificationMessage, data)
+                notification_data: NotificationMessage = cast("NotificationMessage", data)
 
                 try:
                     await self._process_notification(notification_data)

twitchio/ext/commands/core.py

@@ -168,7 +168,7 @@ def __str__(self) -> str:
 
     async def __call__(self, context: Context) -> Any:
         callback = self._callback(self._injected, context) if self._injected else self._callback(context)  # type: ignore
-        return await callback
+        return await callback  # type: ignore will fix later
 
     @property
     def component(self) -> Component_T | None:
@@ -197,7 +197,7 @@ def relative_name(self) -> str:
 
         If this command has no parent, this simply returns the name.
         """
-        return self._name if not self._parent else f"{self._parent._name} {self._name}"
+        return f"{self._parent._name} {self._name}" if self._parent else self._name
 
     @property
     def full_parent_name(self) -> str:

twitchio/models/ads.py

@@ -24,14 +24,13 @@
 
 from __future__ import annotations
 
+import datetime
 from typing import TYPE_CHECKING
 
 from twitchio.utils import parse_timestamp
 
 
 if TYPE_CHECKING:
-    import datetime
-
     from twitchio.types_.responses import AdScheduleResponseData, SnoozeNextAdResponseData, StartCommercialResponseData
 
 
@@ -70,7 +69,7 @@ class AdSchedule:
     -----------
     snooze_count: int
         The number of snoozes available for the broadcaster.
-    snooze_refresh_at: datetime.datetime
+    snooze_refresh_at: datetime.datetime | None
         The UTC datetime when the broadcaster will gain an additional snooze.
     duration: int
         The length in seconds of the scheduled upcoming ad break.
@@ -86,10 +85,12 @@ class AdSchedule:
 
     def __init__(self, data: AdScheduleResponseData) -> None:
         self.snooze_count: int = int(data["snooze_count"])
-        self.snooze_refresh_at: datetime.datetime = parse_timestamp(data["snooze_refresh_at"])
+        self.snooze_refresh_at: datetime.datetime | None = (
+            _parse_timestamp(data["snooze_refresh_at"]) if data["snooze_refresh_at"] else None
+        )
         self.duration: int = int(data["duration"])
-        self.next_ad_at: datetime.datetime | None = parse_timestamp(data["next_ad_at"]) if data["next_ad_at"] else None
-        self.last_ad_at: datetime.datetime | None = parse_timestamp(data["last_ad_at"]) if data["last_ad_at"] else None
+        self.next_ad_at: datetime.datetime | None = _parse_timestamp(data["next_ad_at"]) if data["next_ad_at"] else None
+        self.last_ad_at: datetime.datetime | None = _parse_timestamp(data["last_ad_at"]) if data["last_ad_at"] else None
         self.preroll_free_time: int = int(data["preroll_free_time"])
 
     def __repr__(self) -> str:
@@ -104,7 +105,7 @@ class SnoozeAd:
     -----------
     snooze_count: int
         The number of snoozes available for the broadcaster.
-    snooze_refresh_at: datetime.datetime
+    snooze_refresh_at: datetime.datetime | None
         The UTC datetime when the broadcaster will gain an additional snooze.
     next_ad_at: datetime.datetime | None
         The UTC datetime of the broadcaster's next scheduled ad. None if channel has no ad scheduled.
@@ -114,8 +115,19 @@ class SnoozeAd:
 
     def __init__(self, data: SnoozeNextAdResponseData) -> None:
         self.snooze_count: int = int(data["snooze_count"])
-        self.snooze_refresh_at: datetime.datetime = parse_timestamp(data["snooze_refresh_at"])
-        self.next_ad_at: datetime.datetime | None = parse_timestamp(data["next_ad_at"]) if data["next_ad_at"] else None
+        self.snooze_refresh_at: datetime.datetime | None = (
+            _parse_timestamp(data["snooze_refresh_at"]) if data["snooze_refresh_at"] else None
+        )
+        self.next_ad_at: datetime.datetime | None = _parse_timestamp(data["next_ad_at"]) if data["next_ad_at"] else None
 
     def __repr__(self) -> str:
         return f"<SnoozeAd snooze_count={self.snooze_count} snooze_refresh_at={self.snooze_refresh_at} next_ad_at={self.next_ad_at}>"
+
+
+def _parse_timestamp(timestamp: str | int) -> datetime.datetime:
+    """Helper function for Ads due to incorrect Twitch documention and a known issue with the return format.
+    This may be incorporated into the main `parse_timestamp` utility function in the future.
+    """
+    if isinstance(timestamp, str):
+        return parse_timestamp(timestamp)
+    return datetime.datetime.fromtimestamp(timestamp, tz=datetime.UTC)