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

Author: EvieePy

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,47 @@
+---
+name: 🐛 Bug Report
+description: Submit a bug report for TwitchIO
+title: "[Bug]: "
+labels: ["Unconfirmed Bug", "Needs Verification"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: "What actually happened?"
+      description: "Please enter details about the issue, including tracebacks if applicable (in codeblocks)."
+      placeholder: "My Bot will not start!"
+    validations:
+      required: true
+  - type: textarea
+    id: expected-outcome
+    attributes:
+      label: "What did you expect to happen instead?"
+      description: "Please enter what you hoped or expected to happen instead of the issue that occurred."
+      placeholder: "My Bot started successfully!"
+    validations:
+      required: true
+  - type: textarea
+    id: mre
+    attributes:
+      label: "Minimum reproducible example:"
+      description: "Please provide the minimum necessary code to reproduce your issue, if relevant."
+      render: python
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: "Steps to reproduce the problem"
+      description: "It may not be obvious how to *cause* the issue, so please explain below."
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: "Additional logs:"
+      description: "If there is any logging output that may be relevant, please add it here."
+  - type: textarea
+    id: environment-details
+    attributes:
+      label: "System and Environment information"
+      description: "Please put the output of `python -m twitchio --version` here:"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: TwitchIO Documentation
+    url: https://twitchio.dev/en/latest/index.html
+    about: Official TwitchIO documentation - please check here before opening an issue.
+  - name: Discord
+    url: https://discord.gg/RAKc3HF
+    about: Join our Discord community to chat or receive help, or get in touch with the maintainers.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,38 @@
+name: "Feature Request"
+description: Create an issue for a new feature request
+title: "Enhancement: <title>"
+labels:
+  - "Enhancement"
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: "Summary"
+      description: Provide a brief summary of your feature request
+      placeholder: Describe in a few lines your feature request
+    validations:
+      required: true
+  - type: textarea
+    id: basic_example
+    attributes:
+      label: "Basic Examples"
+      description: Indicate here some basic examples of your feature.
+      placeholder: Provide some basic example of your feature request
+    validations:
+      required: false
+  - type: textarea
+    id: drawbacks
+    attributes:
+      label: "Drawbacks and Impact"
+      description: What are the drawbacks or impacts of your feature request?
+      placeholder: Describe any of the drawbacks or impacts of your feature request
+    validations:
+      required: false
+  - type: textarea
+    id: unresolved_question
+    attributes:
+      label: "Unresolved questions"
+      description: What, if any, unresolved questions do you have about your feature request?
+      placeholder: Identify any unresolved issues.
+    validations:
+      required: false

docs/getting-started/faq.rst

@@ -83,3 +83,28 @@ You can also create a :class:`~twitchio.PartialUser` with :meth:`~twitchio.Clien
 If you are using :class:`~twitchio.ext.commands.Command`'s or anywhere :class:`~twitchio.ext.commands.Context` is available,
 or are receiving a :class:`~twitchio.ChatMessage`, consider looking at :class:`~twitchio.Chatter` for a more complete object
 with more information and helpers.
+
+.. _bot-id-owner-id:
+
+How do I get the user IDs for BOT_ID and OWNER_ID?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you do not know your user ID you can quickly fetch it using the :meth:`~twitchio.Client.fetch_users` method.
+
+.. code:: python3
+
+    import asyncio
+    import twitchio
+
+    CLIENT_ID: str = "..."
+    CLIENT_SECRET: str = "..."
+
+    async def main() -> None:
+        async with twitchio.Client(client_id=CLIENT_ID, client_secret=CLIENT_SECRET) as client:
+            await client.login()
+            user = await client.fetch_users(logins=["chillymosh", "my_bot"])
+            for u in user:
+                print(f"User: {u.name} - ID: {u.id}")
+
+    if __name__ == "__main__":
+        asyncio.run(main())

docs/getting-started/quickstart.rst

@@ -37,6 +37,9 @@ Before running the code below, there just a couple more steps we need to take.
 #. Stop the bot and uncomment everything in ``setup_hook``.
 #. Start the bot.
 
+.. note::
+    If you are unsure how to get the user IDs for BOT_ID and OWNER_ID, please check :ref:`bot-id-owner-id`
+
 **You only have to do this sequence of steps once. Or if the scopes need to change.**
 
 .. code:: python3

twitchio/client.py

@@ -59,7 +59,7 @@
     from .http import HTTPAsyncIterator
     from .models.clips import Clip
     from .models.entitlements import Entitlement, EntitlementStatus
-    from .models.eventsub_ import EventsubSubscriptions
+    from .models.eventsub_ import EventsubSubscription, EventsubSubscriptions
     from .models.search import SearchChannel
     from .models.streams import Stream, VideoMarkers
     from .models.videos import Video
@@ -1660,6 +1660,56 @@ async def fetch_users(
         data = await self._http.get_users(ids=ids, logins=logins, token_for=token_for)
         return [User(d, http=self._http) for d in data["data"]]
 
+    async def fetch_user(
+        self,
+        *,
+        id: str | int | None = None,
+        login: str | None = None,
+        token_for: str | PartialUser | None = None,
+    ) -> User | None:
+        """|coro|
+
+        Fetch information about one user.
+
+        .. note::
+
+            You may look up a specific user using their user ID or login name.
+
+            If you don't specify an ID or login name but provide the `token_for` parameter,
+            the request returns information about the user associated with the access token.
+
+            To include the user's verified email address in the response,
+            you must have a user access token that includes the `user:read:email` scope.
+
+        Parameters
+        ----------
+        id: str | int | None
+            The id of the user to fetch information about.
+        login: str | None
+            The login name of the user to fetch information about.
+        token_for: str | PartialUser | None
+            |token_for|
+
+            If this parameter is provided, the token must have the `user:read:email` scope
+            in order to request the user's verified email address.
+
+        Returns
+        -------
+        :class:`twitchio.User`
+            A :class:`twitchio.User` object.
+
+        Raises
+        ------
+        ValueError
+            Please provide only one of `id` or `login`.
+        """
+
+        if id is not None and login is not None:
+            raise ValueError("Please provide only one of `id` or `login`.")
+
+        data = await self._http.get_users(ids=id, logins=login, token_for=token_for)
+        return User(data["data"][0], http=self._http) if data["data"] else None
+
     def search_categories(
         self,
         query: str,
@@ -2363,6 +2413,7 @@ async def fetch_eventsub_subscriptions(
         token_for: str | PartialUser | None = None,
         type: str | None = None,
         user_id: str | PartialUser | None = None,
+        subscription_id: str | None = None,
         status: Literal[
             "enabled",
             "webhook_callback_verification_pending",
@@ -2389,7 +2440,7 @@ async def fetch_eventsub_subscriptions(
         Fetches Eventsub Subscriptions for either webhook or websocket.
 
         .. note::
-            type, status and user_id are mutually exclusive and only one can be passed, otherwise ValueError will be raised.
+            type, status, user_id, and subscription_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.
 
@@ -2403,6 +2454,8 @@ async def fetch_eventsub_subscriptions(
             Filter subscriptions by subscription type. e.g. ``channel.follow`` For a list of subscription types, see `Subscription Types <https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#subscription-types>`_.
         user_id: str | PartialUser | None
             Filter subscriptions by user ID, or PartialUser. The response contains subscriptions where this ID matches a user ID that you specified in the Condition object when you created the subscription.
+        subscription_id: str | None
+            The specific subscription ID to fetch.
         status: str | None = None
             Filter subscriptions by its status. Possible values are:
 
@@ -2457,18 +2510,58 @@ async def fetch_eventsub_subscriptions(
         Raises
         ------
         ValueError
-            Only one of 'status', 'user_id', or 'type' can be provided.
+            Only one of 'status', 'user_id', 'subscription_id', or 'type' can be provided.
         """
 
-        provided: int = len([v for v in (type, user_id, status) if v])
+        provided: int = len([v for v in (type, user_id, status, subscription_id) if v])
         if provided > 1:
-            raise ValueError("Only one of 'status', 'user_id', or 'type' can be provided.")
+            raise ValueError("Only one of 'status', 'user_id', 'subscription_id', or 'type' can be provided.")
 
         return await self._http.get_eventsub_subscription(
             type=type,
             max_results=max_results,
             token_for=token_for,
+            subscription_id=subscription_id,
+            user_id=user_id,
+            status=status,
+        )
+
+    async def fetch_eventsub_subscription(
+        self,
+        subscription_id: str,
+        *,
+        token_for: str | PartialUser | None = None,
+    ) -> EventsubSubscription | None:
+        """|coro|
+
+        Fetches a specific Eventsub Subscription for either webhook or websocket.
+
+        .. note::
+            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
+        -----------
+        subscription_id: str
+            The specific subscription ID to fetch.
+        token_for: str | PartialUser | None
+            By default, if this is ignored or set to None then the App Token is used. This is the case when you want to fetch webhook events.
+
+            Provide a user ID here for when you want to fetch websocket events tied to a user.
+
+        Returns
+        --------
+        EventsubSubscription | None
+        """
+
+        data = await self._http.get_eventsub_subscription(
+            type=None,
+            max_results=None,
+            token_for=token_for,
+            subscription_id=subscription_id,
+            user_id=None,
+            status=None,
         )
+        return await anext(data.subscriptions, None)
 
     async def delete_eventsub_subscription(self, id: str, *, token_for: str | PartialUser | None = None) -> None:
         """|coro|

twitchio/eventsub/subscriptions.py

@@ -427,6 +427,7 @@ class ChannelBitsUseSubscription(SubscriptionPayload):
     - Cheers in a channel
     - Uses a Power-up
         - Will not emit when a streamer uses a Power-up for free in their own channel.
+    - Sends Combos
 
     .. important::
         Requires a user access token that includes the ``bits:read`` scope. This must be the broadcaster's token.

twitchio/http.py

@@ -1486,6 +1486,7 @@ async def get_eventsub_subscription(
         ]
         | None = None,
         user_id: str | PartialUser | None = None,
+        subscription_id: str | None = None,
         type: str | None = None,
         max_results: int | None = None,
         token_for: str | PartialUser | None = None,
@@ -1498,6 +1499,8 @@ async def get_eventsub_subscription(
             params["status"] = status
         if user_id is not None:
             params["user_id"] = str(user_id)
+        if subscription_id is not None:
+            params["subscription_id"] = subscription_id
 
         route: Route = Route("GET", "eventsub/subscriptions", params=params, token_for=token_for)
 

twitchio/user.py

@@ -88,7 +88,7 @@ class PartialUser:
     id: str | int
         The user's ID.
     name: str | None
-        The user's name. In most cases, this is provided. There are however, rare cases where it is not.
+        The user's name. Also known as *username* or *login name*. In most cases, this is provided. There are however, rare cases where it is not.
     display_name: str | None
         The user's display name in chat. In most cases, this is provided otherwise fallsback to `name`. There are however, rare cases where it is not.
     """
@@ -3459,7 +3459,7 @@ class User(PartialUser):
     id: str
         The user's ID.
     name: str | None
-        The user's name. In most cases, this is provided. There are however, rare cases where it is not.
+        The user's name. Also known as *username* or *login name*. In most cases, this is provided. There are however, rare cases where it is not.
     display_name: str
         The display name of the user.
     type: Literal["admin", "global_mod", "staff", ""]