Add user emote endpoint

Author: IAmTomahawkx

docs/changelog.rst

@@ -4,10 +4,11 @@
 =======
 - TwitchIO
     - Additions
-        - Added :class:`~twitchio.AdSchedule`
+        - Added :class:`~twitchio.AdSchedule` and :class:`~twitchio.Emote`
         - Added the new ad-related methods for :class:`~twitchio.PartialUser`:
             - :func:`~twitchio.PartialUser.fetch_ad_schedule`
             - :func:`~twitchio.PartialUser.snooze_ad`
+        - Added new method :func:`~twitchio.PartialUser.fetch_user_emotes` to :class:`~twitchio.PartialUser`
         - Added :func:`~twitchio.PartialUser.fetch_moderated_channels` to :class:`~twitchio.PartialUser`
 
     - Bug fixes

docs/reference.rst

@@ -220,6 +220,13 @@ CustomRewardRedemption
     :members:
     :inherited-members:
 
+Emote
+------
+.. attributetable:: Emote
+
+.. autoclass:: Emote
+    :members:
+
 Extension
 -----------
 .. attributetable:: Extension

twitchio/http.py

@@ -705,6 +705,13 @@ async def get_search_channels(self, query: str, token: str = None, live: bool =
             Route("GET", "search/channels", query=[("query", query), ("live_only", str(live))], token=token)
         )
 
+    async def get_user_emotes(self, user_id: str, broadcaster_id: Optional[str], token: str):
+        q: List = [("user_id", user_id)]
+        if broadcaster_id:
+            q.append(("broadcaster_id", broadcaster_id))
+        
+        return await self.request(Route("GET", "chat/emotes/user", query=q, token=token))
+
     async def get_stream_key(self, token: str, broadcaster_id: str):
         return await self.request(
             Route("GET", "streams/key", query=[("broadcaster_id", broadcaster_id)], token=token), paginate=False

twitchio/models.py

@@ -31,13 +31,16 @@
 from .user import BitLeaderboardUser, PartialUser, User
 
 if TYPE_CHECKING:
+    from typing_extensions import Literal
     from .http import TwitchHTTP
+
 __all__ = (
     "AdSchedule",
     "BitsLeaderboard",
     "Clip",
     "CheerEmote",
     "CheerEmoteTier",
+    "Emote",
     "GlobalEmote",
     "ChannelEmote",
     "HypeTrainContribution",
@@ -651,6 +654,104 @@ def __repr__(self):
         )
 
 
+class Emote:
+    """
+    Represents an Emote.
+
+    .. note::
+    
+        It seems twitch is sometimes returning duplicate information from the emotes endpoint.
+        To deduplicate your emotes, you can call ``set()`` on the list of emotes (or any other hashmap), which will remove the duplicates.
+
+        .. code-block:: python
+
+            my_list_of_emotes = await user.get_user_emotes(...)
+            deduplicated_emotes = set(my_list_of_emotes)
+    
+    Attributes
+    -----------
+    id: :class:`str`
+        The unique ID of the emote.
+    set_id: Optional[:class:`str`]
+        The ID of the set this emote belongs to.
+        Will be ``None`` if the emote doesn't belong to a set.
+    owner_id: Optional[:class:`str`]
+        The ID of the channel this emote belongs to.
+    name: :class:`str`
+        The name of this emote, as the user sees it.
+    type: :class:`str`
+        The reason this emote is available to the user.
+        Some available values (twitch hasn't documented this properly, there might be more):
+
+        - follower
+        - subscription
+        - bitstier
+        - hypetrain
+        - globals (global emotes)
+
+    scales: list[:class:`str`]
+        The available scaling for this emote. These are typically floats (ex. "1.0", "2.0").
+    format_static: :class:`bool`
+        Whether this emote is available as a static (PNG) file.
+    format_animated: :class:`bool`
+        Whether this emote is available as an animated (GIF) file.
+    theme_light: :class:`bool`
+        Whether this emote is available in light theme background mode.
+    theme_dark: :class:`bool`
+        Whether this emote is available in dark theme background mode.
+    """
+
+    __slots__ = "id", "set_id", "owner_id", "name", "type", "scales", "format_static", "format_animated", "theme_light", "theme_dark"
+
+    def __init__(self, data: dict) -> None:
+        self.id: str = data["id"]
+        self.set_id: Optional[str] = data["emote_set_id"] and None
+        self.owner_id: Optional[str] = data["owner_id"] and None
+        self.name: str = data["name"]
+        self.type: str = data["emote_type"]
+        self.scales: List[str] = data["scale"]
+        self.theme_dark: bool = "dark" in data["theme_mode"]
+        self.theme_light: bool = "light" in data["theme_mode"]
+        self.format_static: bool = "static" in data["format"]
+        self.format_animated: bool = "animated" in data["format"]
+    
+    def url_for(self, format: Literal["static", "animated"], theme: Literal["dark", "light"], scale: str) -> str:
+        """
+        Returns a cdn url that can be used to download or serve the emote on a website.
+        This function validates that the arguments passed are possible values to serve the emote.
+
+        Parameters
+        -----------
+        format: Literal["static", "animated"]
+            The format of the emote. You can check what formats are available using :attr:`~.format_static` and :attr:`~.format_animated`.
+        theme: Literal["dark", "light"]
+            The theme of the emote. You can check what themes are available using :attr:`~.format_dark` and :attr:`~.format_light`.
+        scale: :class:`str`
+            The scale of the emote. This should be formatted in this format: ``"1.0"``.
+            The scales available for this emote can be checked via :attr:`~.scales`.
+        
+        Returns
+        --------
+        :class:`str`
+        """
+        if scale not in self.scales:
+            raise ValueError(f"scale for this emote must be one of {', '.join(self.scales)}, not {scale}")
+        
+        if (theme == "dark" and not self.theme_dark) or (theme == "light" and not self.theme_light):
+            raise ValueError(f"theme {theme} is not an available value for this emote")
+
+        if (format == "static" and not self.format_static) or (format == "animated" and not self.format_animated):
+            raise ValueError(f"format {format} is not an available value for this emote")
+        
+        return f"https://static-cdn.jtvnw.net/emoticons/v2/{self.id}/{format}/{theme}/{scale}"
+    
+    def __repr__(self) -> str:
+        return f"<Emote id={self.id} name={self.name}>"
+
+    def __hash__(self) -> int: # this exists so we can do set(list of emotes) to get rid of duplicates
+        return hash(self.id)
+
+
 class Marker:
     """
     Represents a stream Marker

twitchio/user.py

@@ -40,6 +40,7 @@
         AdSchedule,
         BitsLeaderboard,
         Clip,
+        Emote,
         ExtensionBuilder,
         Tag,
         FollowEvent,
@@ -638,6 +639,32 @@ async def fetch_channel_emotes(self):
 
         data = await self._http.get_channel_emotes(str(self.id))
         return [ChannelEmote(self._http, x) for x in data]
+    
+    async def fetch_user_emotes(self, token: str, broadcaster: Optional[PartialUser] = None) -> List[Emote]:
+        """|coro|
+        
+        Fetches emotes the user has access to. Optionally, you can filter by a broadcaster.
+
+        .. note::
+
+            As of writing, this endpoint seems extrememly unoptimized by twitch, and may (read: will) take a lot of API requests to load.
+            See https://github.com/twitchdev/issues/issues/921 .
+        
+        Parameters
+        -----------
+        token: :class:`str`
+            An OAuth token belonging to this user with the ``user:read:emotes`` scope.
+        broadcaster: Optional[:class:`~twitchio.PartialUser`]
+            A channel to filter the results with.
+            Filtering will return all emotes available to the user on that channel, including global emotes.
+
+        Returns
+        --------
+        List[:class:`~twitchio.Emote`]
+        """
+        from .models import Emote
+        data = await self._http.get_user_emotes(str(self.id), broadcaster and str(broadcaster.id), token)
+        return [Emote(d) for d in data]
 
     async def follow(self, userid: int, token: str, *, notifications=False):
         """|coro|
@@ -666,6 +693,10 @@ async def unfollow(self, userid: int, token: str):
 
         Unfollows the user
 
+        .. warning::
+
+            This method is obsolete as Twitch removed the endpoint.
+
         Parameters
         -----------
         userid: :class:`int`