Merge branch 'main' into feature/conduits

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

@@ -172,6 +172,33 @@ def __init__(
 
         self.__waiter: asyncio.Event = asyncio.Event()
 
+    @property
+    def adapter(self) -> BaseAdapter:
+        """Property returning the :class:`~twitchio.AiohttpAdapter` or :class:`~twitchio.StarlettepAdapter` the bot is
+        currently running."""
+        return self._adapter
+
+    async def set_adapter(self, adapter: BaseAdapter) -> None:
+        """|async|
+
+        Method which sets and starts a new web adapter which inherits from either :class:`~twitchio.AiohttpAdapter` or
+        :class:`~twitchio.StarlettepAdapter` or implements the :class:`~twitchio.BaseAdapter` specifications.
+
+        Parameters
+        ----------
+        adapter: :class:`~twitchio.BaseAdapter`
+            The new adapter to assign and start.
+
+        Returns
+        -------
+        None
+        """
+        if self._adapter:
+            await self._adapter.close()
+
+        self._adapter = adapter
+        await self._adapter.run()
+
     @property
     def tokens(self) -> MappingProxyType[str, TokenMappingData]:
         """Property which returns a read-only mapping of the tokens that are managed by the `Client`.
@@ -1643,6 +1670,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,
@@ -2459,6 +2536,43 @@ async def fetch_eventsub_subscriptions(
             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/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", ""]