<reponame>StockerMC/discord.py_<filename>discord/client.py
"""
The MIT License (MIT)

Copyright (c) 2015-present Rapptz

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
"""

from __future__ import annotations

import asyncio
import logging
import signal
import sys
import traceback
import inspect
import collections
import collections.abc
import types
import importlib.util

from typing import (
    Any,
    Callable,
    Coroutine,
    Dict,
    Generator,
    List,
    Optional,
    Sequence,
    TYPE_CHECKING,
    Tuple,
    TypeVar,
    Union,
    Type,
    Mapping,
)

import aiohttp

from .user import User, ClientUser
from .invite import Invite
from .template import Template
from .widget import Widget
from .guild import Guild
from .emoji import Emoji
from .channel import _threaded_channel_factory, PartialMessageable
from .enums import ChannelType
from .mentions import AllowedMentions
from .errors import *
from .enums import Status, VoiceRegion
from .flags import ApplicationFlags, Intents
from .gateway import *
from .activity import ActivityTypes, BaseActivity, create_activity
from .voice_client import VoiceClient
from .http import HTTPClient
from .state import ConnectionState
from . import utils
from .utils import MISSING
from .object import Object
from .backoff import ExponentialBackoff
from .webhook import Webhook
from .iterators import GuildIterator
from .appinfo import AppInfo
from .ui.view import View
from .stage_instance import StageInstance
from .threads import Thread
from .sticker import GuildSticker, StandardSticker, StickerPack, _sticker_factory
from .application_commands import (
    SlashCommand,
    MessageCommand,
    UserCommand,
    SlashCommandResponse,
    MessageCommandResponse,
    UserCommandResponse
)

if TYPE_CHECKING:
    import importlib.machinery

    from typing_extensions import ParamSpec

    from .ext.commands._types import CoroFunc

    from .abc import SnowflakeTime, PrivateChannel, GuildChannel, Snowflake
    from .channel import DMChannel
    from .message import Message
    from .member import Member
    from .voice_client import VoiceProtocol
    from .cog import Cog

    T = TypeVar('T')
    P = ParamSpec('P')

    ApplicationCommand = Union[SlashCommand, MessageCommand, UserCommand]
    AT = TypeVar('AT', bound=ApplicationCommand)

    Check = Union[
        Callable[[SlashCommandResponse[Any]], Union[bool, Coroutine[Any, Any, bool]]],
        Callable[[UserCommandResponse[Any]], Union[bool, Coroutine[Any, Any, bool]]],
        Callable[[MessageCommandResponse[Any]], Union[bool, Coroutine[Any, Any, bool]]],
    ]
    ApplicationCommandKey = Tuple[str, int, Optional['ApplicationCommandKey']]  # name, type, parent

__all__ = (
    'Client',
)

CFT = TypeVar('CFT', bound='CoroFunc')

_log = logging.getLogger(__name__)
_valid_application_command_types = (SlashCommand, MessageCommand, UserCommand)

def _cancel_tasks(loop: asyncio.AbstractEventLoop) -> None:
    tasks = {t for t in asyncio.all_tasks(loop=loop) if not t.done()}

    if not tasks:
        return

    _log.info('Cleaning up after %d tasks.', len(tasks))
    for task in tasks:
        task.cancel()

    loop.run_until_complete(asyncio.gather(*tasks, return_exceptions=True))
    _log.info('All tasks finished cancelling.')

    for task in tasks:
        if task.cancelled():
            continue
        if task.exception() is not None:
            loop.call_exception_handler({
                'message': 'Unhandled exception during Client.run shutdown.',
                'exception': task.exception(),
                'task': task
            })

def _cleanup_loop(loop: asyncio.AbstractEventLoop) -> None:
    try:
        _cancel_tasks(loop)
        loop.run_until_complete(loop.shutdown_asyncgens())
    finally:
        _log.info('Closing the event loop.')
        loop.close()

def _is_submodule(parent: str, child: str) -> bool:
    return parent == child or child.startswith(parent + ".")

class Client:
    r"""Represents a client connection that connects to Discord.
    This class is used to interact with the Discord WebSocket and API.

    A number of options can be passed to the :class:`Client`.

    Parameters
    -----------
    application_id: :class:`int`
        The client's application ID.
    max_messages: Optional[:class:`int`]
        The maximum number of messages to store in the internal message cache.
        This defaults to ``1000``. Passing in ``None`` disables the message cache.

        .. versionchanged:: 1.3
            Allow disabling the message cache and change the default size to ``1000``.
    loop: Optional[:class:`asyncio.AbstractEventLoop`]
        The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
        Defaults to ``None``, in which case the default event loop is used via
        :func:`asyncio.get_event_loop()`.
    connector: Optional[:class:`aiohttp.BaseConnector`]
        The connector to use for connection pooling.
    proxy: Optional[:class:`str`]
        Proxy URL.
    proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
        An object that represents proxy HTTP Basic Authorization.
    shard_id: Optional[:class:`int`]
        Integer starting at ``0`` and less than :attr:`.shard_count`.
    shard_count: Optional[:class:`int`]
        The total number of shards.
    intents: :class:`Intents`
        The intents that you want to enable for the session. This is a way of
        disabling and enabling certain gateway events from triggering and being sent.
        If not given, defaults to a regularly constructed :class:`Intents` class.

        .. versionadded:: 1.5
    member_cache_flags: :class:`MemberCacheFlags`
        Allows for finer control over how the library caches members.
        If not given, defaults to cache as much as possible with the
        currently selected intents.

        .. versionadded:: 1.5
    chunk_guilds_at_startup: :class:`bool`
        Indicates if :func:`.on_ready` should be delayed to chunk all guilds
        at start-up if necessary. This operation is incredibly slow for large
        amounts of guilds. The default is ``True`` if :attr:`Intents.members`
        is ``True``.

        .. versionadded:: 1.5
    status: Optional[:class:`.Status`]
        A status to start your presence with upon logging on to Discord.
    activity: Optional[:class:`.BaseActivity`]
        An activity to start your presence with upon logging on to Discord.
    allowed_mentions: Optional[:class:`AllowedMentions`]
        Control how the client handles mentions by default on every message sent.

        .. versionadded:: 1.4
    heartbeat_timeout: :class:`float`
        The maximum numbers of seconds before timing out and restarting the
        WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if
        processing the initial packets take too long to the point of disconnecting
        you. The default timeout is 60 seconds.
    guild_ready_timeout: :class:`float`
        The maximum number of seconds to wait for the GUILD_CREATE stream to end before
        preparing the member cache and firing READY. The default timeout is 2 seconds.

        .. versionadded:: 1.4
    assume_unsync_clock: :class:`bool`
        Whether to assume the system clock is unsynced. This applies to the ratelimit handling
        code. If this is set to ``True``, the default, then the library uses the time to reset
        a rate limit bucket given by Discord. If this is ``False`` then your system clock is
        used to calculate how long to sleep for. If this is set to ``False`` it is recommended to
        sync your system clock to Google's NTP server.

        .. versionadded:: 1.3
    enable_debug_events: :class:`bool`
        Whether to enable events that are useful only for debugging gateway related information.

        Right now this involves :func:`on_socket_raw_receive` and :func:`on_socket_raw_send`. If
        this is ``False`` then those events will not be dispatched (due to performance considerations).
        To enable these events, this must be set to ``True``. Defaults to ``False``.

        .. versionadded:: 2.0
    application_command_guild_ids: Optional[List[:class:`int`]]
        The IDs of the guilds to upload all application commands to that do not have guild IDs set.
        It is recommended to set this while testing to speed up the registering of the commands.

        .. versionadded:: 2.0
    register_application_commands_at_startup: :class:`bool`
        Whether :meth:`register_application_commands` should be called in :meth:`login`.
        It is recommended to set this to ``False`` when the application commands
        added to the client are the same (having the exact same name and options) as the previous
        time they were added. Defaults to ``True``.

        .. note::

            If this is set to ``True``, :meth:`register_application_commands` will be created as a task,
            which means that the client may connect to the gateway before all application commands are registered.
            :func:`on_ready` and :meth:`wait_until_ready` will be delayed to wait for
            :meth:`Client.register_application_commands` to finish, regardless of whether an error was raised in it or not.

        .. versionadded:: 2.0

    Attributes
    -----------
    ws
        The websocket gateway the client is currently connected to. Could be ``None``.
    loop: :class:`asyncio.AbstractEventLoop`
        The event loop that the client uses for asynchronous operations.
    """
    def __init__(
        self,
        *,
        loop: Optional[asyncio.AbstractEventLoop] = None,
        **options: Any,
    ):
        # self.ws is set in the connect method
        self.ws: DiscordWebSocket = None  # type: ignore
        self.loop: asyncio.AbstractEventLoop = asyncio.get_event_loop() if loop is None else loop
        self._listeners: Dict[str, List[Tuple[asyncio.Future, Callable[..., bool]]]] = {}
        self.shard_id: Optional[int] = options.get('shard_id')
        self.shard_count: Optional[int] = options.get('shard_count')
        self.owner_id: Optional[int] = options.get('owner_id')
        self.owner_ids: Optional[collections.abc.Collection[int]] = options.get('owner_ids', set())
        self.application_command_guild_ids: Optional[List[int]] = options.get('application_command_guild_ids')
        self.extra_events: Dict[str, List[CoroFunc]] = {}
        self.register_application_commands_at_startup: bool = options.get('register_application_commands_at_startup', True)

        if self.owner_id and self.owner_ids:
            raise TypeError('Both owner_id and owner_ids are set.')

        if self.owner_ids and not isinstance(self.owner_ids, collections.abc.Collection):
            raise TypeError(f'owner_ids must be a collection not {self.owner_ids.__class__!r}')

        connector: Optional[aiohttp.BaseConnector] = options.pop('connector', None)
        proxy: Optional[str] = options.pop('proxy', None)
        proxy_auth: Optional[aiohttp.BasicAuth] = options.pop('proxy_auth', None)
        unsync_clock: bool = options.pop('assume_unsync_clock', True)
        self.http: HTTPClient = HTTPClient(connector, proxy=proxy, proxy_auth=proxy_auth, unsync_clock=unsync_clock, loop=self.loop)

        self._handlers: Dict[str, Callable[..., None]] = {
            'ready': self._handle_ready
        }

        self._hooks: Dict[str, Callable[..., Coroutine[Any, Any, None]]] = {
            'before_identify': self._call_before_identify_hook
        }

        self._enable_debug_events: bool = options.pop('enable_debug_events', False)
        self._connection: ConnectionState = self._get_state(**options)
        self._connection.shard_count = self.shard_count
        self._closed: bool = False
        self._ready: asyncio.Event = asyncio.Event()
        self._connection._get_websocket = self._get_websocket
        self._connection._get_client = lambda: self
        self._application_commands: Dict[ApplicationCommandKey, ApplicationCommand] = {}
        self._application_command_checks: List[Check] = []
        self.__extensions: Dict[str, types.ModuleType] = {}
        self.__cogs: Dict[str, Cog] = {}

        if VoiceClient.warn_nacl:
            VoiceClient.warn_nacl = False
            _log.warning("PyNaCl is not installed, voice will NOT be supported")

    # internals

    def _get_websocket(self, guild_id: Optional[int] = None, *, shard_id: Optional[int] = None) -> DiscordWebSocket:
        return self.ws

    def _get_state(self, **options: Any) -> ConnectionState:
        return ConnectionState(dispatch=self.dispatch, handlers=self._handlers,
                               hooks=self._hooks, http=self.http, loop=self.loop, **options)

    def _handle_ready(self) -> None:
        self._ready.set()

    @property
    def latency(self) -> float:
        """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

        This could be referred to as the Discord WebSocket protocol latency.
        """
        ws = self.ws
        return float('nan') if not ws else ws.latency

    def is_ws_ratelimited(self) -> bool:
        """:class:`bool`: Whether the websocket is currently rate limited.

        This can be useful to know when deciding whether you should query members
        using HTTP or via the gateway.

        .. versionadded:: 1.6
        """
        if self.ws:
            return self.ws.is_ratelimited()
        return False

    @property
    def user(self) -> Optional[ClientUser]:
        """Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in."""
        return self._connection.user

    @property
    def guilds(self) -> List[Guild]:
        """List[:class:`.Guild`]: The guilds that the connected client is a member of."""
        return self._connection.guilds

    @property
    def emojis(self) -> List[Emoji]:
        """List[:class:`.Emoji`]: The emojis that the connected client has."""
        return self._connection.emojis

    @property
    def stickers(self) -> List[GuildSticker]:
        """List[:class:`.GuildSticker`]: The stickers that the connected client has.

        .. versionadded:: 2.0
        """
        return self._connection.stickers

    @property
    def cached_messages(self) -> Sequence[Message]:
        """Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached.

        .. versionadded:: 1.1
        """
        return utils.SequenceProxy(self._connection._messages or [])

    @property
    def private_channels(self) -> List[PrivateChannel]:
        """List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on.

        .. note::

            This returns only up to 128 most recent private channels due to an internal working
            on how Discord deals with private channels.
        """
        return self._connection.private_channels

    @property
    def voice_clients(self) -> List[VoiceProtocol]:
        """List[:class:`.VoiceProtocol`]: Represents a list of voice connections.

        These are usually :class:`.VoiceClient` instances.
        """
        return self._connection.voice_clients

    @property
    def application_id(self) -> Optional[int]:
        """Optional[:class:`int`]: The client's application ID.

        If this is not passed via ``__init__`` then this is retrieved
        through the gateway when an event contains the data. Usually
        after :func:`~discord.on_connect` is called.
        
        .. versionadded:: 2.0
        """
        return self._connection.application_id

    @property
    def application_flags(self) -> ApplicationFlags:
        """:class:`~discord.ApplicationFlags`: The client's application flags.

        .. versionadded:: 2.0
        """
        return self._connection.application_flags

    def is_ready(self) -> bool:
        """:class:`bool`: Specifies if the client's internal cache is ready for use."""
        return self._ready.is_set()

    async def _run_event(self, coro: Callable[..., Coroutine[Any, Any, Any]], event_name: str, *args: Any, **kwargs: Any) -> None:
        try:
            await coro(*args, **kwargs)
        except asyncio.CancelledError:
            pass
        except Exception:
            try:
                await self.on_error(event_name, *args, **kwargs)
            except asyncio.CancelledError:
                pass

    def _schedule_event(self, coro: Callable[..., Coroutine[Any, Any, Any]], event_name: str, *args: Any, **kwargs: Any) -> asyncio.Task:
        wrapped = self._run_event(coro, event_name, *args, **kwargs)
        # Schedules the task
        return asyncio.create_task(wrapped, name=f'discord.py: {event_name}')

    def dispatch(self, event_name: str, *args: Any, **kwargs: Any) -> None:
        _log.debug('Dispatching event %s', event_name)
        method = 'on_' + event_name

        listeners = self._listeners.get(event_name)
        if listeners:
            removed = []
            for i, (future, condition) in enumerate(listeners):
                if future.cancelled():
                    removed.append(i)
                    continue

                try:
                    result = condition(*args)
                except Exception as exc:
                    future.set_exception(exc)
                    removed.append(i)
                else:
                    if result:
                        if len(args) == 0:
                            future.set_result(None)
                        elif len(args) == 1:
                            future.set_result(args[0])
                        else:
                            future.set_result(args)
                        removed.append(i)

            if len(removed) == len(listeners):
                self._listeners.pop(event_name)
            else:
                for idx in reversed(removed):
                    del listeners[idx]

        try:
            coro = getattr(self, method)
        except AttributeError:
            pass
        else:
            self._schedule_event(coro, method, *args, **kwargs)

        for event in self.extra_events.get(method, []):
            self._schedule_event(event, method, *args, **kwargs)

    async def on_error(self, event_method: str, *args: Any, **kwargs: Any) -> None:
        """|coro|

        The default error handler provided by the client.

        By default this prints to :data:`sys.stderr` however it could be
        overridden to have a different implementation.
        Check :func:`~discord.on_error` for more details.
        """
        print(f'Ignoring exception in {event_method}', file=sys.stderr)
        traceback.print_exc()

    async def on_application_command_error(
        self, response: Union[SlashCommandResponse[Any], MessageCommandResponse[Any], UserCommandResponse[Any]], exception: Exception
    ) -> None:
        """|coro|

        The default application command error handler provided by the client.

        By default this prints to :data:`sys.stderr` however it could be
        overridden to have a different implementation.
        Check :func:`~discord.on_application_command_error` for more details.
        """
        print(f'Ignoring exception in application command {response.command}:', file=sys.stderr)
        traceback.print_exception(type(exception), exception, exception.__traceback__, file=sys.stderr)

    # hooks

    async def _call_before_identify_hook(self, shard_id: Optional[int], *, initial: bool = False) -> None:
        # This hook is an internal hook that actually calls the public one.
        # It allows the library to have its own hook without stepping on the
        # toes of those who need to override their own hook.
        await self.before_identify_hook(shard_id, initial=initial)

    async def before_identify_hook(self, shard_id: Optional[int], *, initial: bool = False) -> None:
        """|coro|

        A hook that is called before IDENTIFYing a session. This is useful
        if you wish to have more control over the synchronization of multiple
        IDENTIFYing clients.

        The default implementation sleeps for 5 seconds.

        .. versionadded:: 1.4

        Parameters
        ------------
        shard_id: :class:`int`
            The shard ID that requested being IDENTIFY'd
        initial: :class:`bool`
            Whether this IDENTIFY is the first initial IDENTIFY.
        """

        if not initial:
            await asyncio.sleep(5.0)

    # login state management

    async def login(self, token: str) -> None:
        """|coro|

        Logs in the client with the specified credentials.


        Parameters
        -----------
        token: :class:`str`
            The authentication token. Do not prefix this token with
            anything as the library will do it for you.

        Raises
        ------
        :exc:`.LoginFailure`
            The wrong credentials are passed.
        :exc:`.HTTPException`
            An unknown HTTP related error occurred,
            usually when it isn't 200 or the known incorrect credentials
            passing status code.
        """

        _log.info('logging in using static token')

        data = await self.http.static_login(token.strip())
        self._connection.user = ClientUser(state=self._connection, data=data)

        if self.register_application_commands_at_startup:
            self._connection._application_command_task = asyncio.create_task(
                self._connection._register_application_commands(), name='discord-register-application-commands'
            )

    async def connect(self, *, reconnect: bool = True) -> None:
        """|coro|

        Creates a websocket connection and lets the websocket listen
        to messages from Discord. This is a loop that runs the entire
        event system and miscellaneous aspects of the library. Control
        is not resumed until the WebSocket connection is terminated.

        Parameters
        -----------
        reconnect: :class:`bool`
            If we should attempt reconnecting, either due to internet
            failure or a specific failure on Discord's part. Certain
            disconnects that lead to bad state will not be handled (such as
            invalid sharding payloads or bad tokens).

        Raises
        -------
        :exc:`.GatewayNotFound`
            If the gateway to connect to Discord is not found. Usually if this
            is thrown then there is a Discord API outage.
        :exc:`.ConnectionClosed`
            The websocket connection has been terminated.
        """

        backoff = ExponentialBackoff()
        ws_params = {
            'initial': True,
            'shard_id': self.shard_id,
        }
        while not self.is_closed():
            try:
                coro = DiscordWebSocket.from_client(self, **ws_params)
                self.ws = await asyncio.wait_for(coro, timeout=60.0)
                ws_params['initial'] = False
                while True:
                    await self.ws.poll_event()
            except ReconnectWebSocket as e:
                _log.info('Got a request to %s the websocket.', e.op)
                self.dispatch('disconnect')
                ws_params.update(sequence=self.ws.sequence, resume=e.resume, session=self.ws.session_id)
                continue
            except (OSError,
                    HTTPException,
                    GatewayNotFound,
                    ConnectionClosed,
                    aiohttp.ClientError,
                    asyncio.TimeoutError) as exc:

                self.dispatch('disconnect')
                if not reconnect:
                    await self.close()
                    if isinstance(exc, ConnectionClosed) and exc.code == 1000:
                        # clean close, don't re-raise this
                        return
                    raise

                if self.is_closed():
                    return

                # If we get connection reset by peer then try to RESUME
                if isinstance(exc, OSError) and exc.errno in (54, 10054):
                    ws_params.update(sequence=self.ws.sequence, initial=False, resume=True, session=self.ws.session_id)
                    continue

                # We should only get this when an unhandled close code happens,
                # such as a clean disconnect (1000) or a bad state (bad token, no sharding, etc)
                # sometimes, discord sends us 1000 for unknown reasons so we should reconnect
                # regardless and rely on is_closed instead
                if isinstance(exc, ConnectionClosed):
                    if exc.code == 4014:
                        raise PrivilegedIntentsRequired(exc.shard_id) from None
                    if exc.code != 1000:
                        await self.close()
                        raise

                retry = backoff.delay()
                _log.exception("Attempting a reconnect in %.2fs", retry)
                await asyncio.sleep(retry)
                # Always try to RESUME the connection
                # If the connection is not RESUME-able then the gateway will invalidate the session.
                # This is apparently what the official Discord client does.
                ws_params.update(sequence=self.ws.sequence, resume=True, session=self.ws.session_id)

    async def close(self) -> None:
        """|coro|

        Closes the connection to Discord.
        """
        if self._closed:
            return

        self._closed = True

        for extension in tuple(self.__extensions):
            try:
                self.unload_extension(extension)
            except Exception:
                pass
        
        for cog in tuple(self.__cogs):
            try:
                self.remove_cog(cog)
            except Exception:
                pass

        for voice in self.voice_clients:
            try:
                await voice.disconnect(force=True)
            except Exception:
                # if an error happens during disconnects, disregard it.
                pass

        if self.ws is not None and self.ws.open:
            await self.ws.close(code=1000)

        await self.http.close()
        self._ready.clear()

    def clear(self) -> None:
        """Clears the internal state of the bot.

        After this, the bot can be considered "re-opened", i.e. :meth:`is_closed`
        and :meth:`is_ready` both return ``False`` along with the bot's internal
        cache cleared.
        """
        self._closed = False
        self._ready.clear()
        self._connection.clear()
        self.http.recreate()

    async def start(self, token: str, *, reconnect: bool = True) -> None:
        """|coro|

        A shorthand coroutine for :meth:`login` + :meth:`connect`.

        Raises
        -------
        TypeError
            An unexpected keyword argument was received.
        """
        await self.login(token)
        await self.connect(reconnect=reconnect)

    def run(self, token: str, *, reconnect: bool = True) -> None:
        """A blocking call that abstracts away the event loop
        initialisation from you.

        If you want more control over the event loop then this
        function should not be used. Use :meth:`start` coroutine
        or :meth:`connect` + :meth:`login`.

        Roughly Equivalent to: ::

            try:
                loop.run_until_complete(start(*args, **kwargs))
            except KeyboardInterrupt:
                loop.run_until_complete(close())
                # cancel all tasks lingering
            finally:
                loop.close()

        .. warning::

            This function must be the last function to call due to the fact that it
            is blocking. That means that registration of events or anything being
            called after this function call will not execute until it returns.
        """
        loop = self.loop

        try:
            loop.add_signal_handler(signal.SIGINT, lambda: loop.stop())
            loop.add_signal_handler(signal.SIGTERM, lambda: loop.stop())
        except NotImplementedError:
            pass

        async def runner():
            try:
                await self.start(token, reconnect=reconnect)
            finally:
                if not self.is_closed():
                    await self.close()

        def stop_loop_on_completion(f):
            loop.stop()

        future = asyncio.ensure_future(runner(), loop=loop)
        future.add_done_callback(stop_loop_on_completion)
        try:
            loop.run_forever()
        except KeyboardInterrupt:
            _log.info('Received signal to terminate bot and event loop.')
        finally:
            future.remove_done_callback(stop_loop_on_completion)
            _log.info('Cleaning up tasks.')
            _cleanup_loop(loop)

        if not future.cancelled():
            try:
                return future.result()
            except KeyboardInterrupt:
                # I am unsure why this gets raised here but suppress it anyway
                return None

    # properties

    def is_closed(self) -> bool:
        """:class:`bool`: Indicates if the websocket connection is closed."""
        return self._closed

    @property
    def activity(self) -> Optional[ActivityTypes]:
        """Optional[:class:`.BaseActivity`]: The activity being used upon
        logging in.
        """
        return create_activity(self._connection._activity, self._connection)

    @activity.setter
    def activity(self, value: Optional[ActivityTypes]) -> None:
        if value is None:
            self._connection._activity = None
        elif isinstance(value, BaseActivity):
            # ConnectionState._activity is typehinted as ActivityPayload, we're passing Dict[str, Any]
            self._connection._activity = value.to_dict() # type: ignore
        else:
            raise TypeError('activity must derive from BaseActivity.')
    
    @property
    def status(self) -> Status:
        """:class:`.Status`:
        The status being used upon logging on to Discord.

        .. versionadded: 2.0
        """
        if self._connection._status in set(state.value for state in Status):
            return Status(self._connection._status)
        return Status.online

    @status.setter
    def status(self, value: Status) -> None:
        if value is Status.offline:
            self._connection._status = 'invisible'
        elif isinstance(value, Status):
            self._connection._status = str(value)
        else:
            raise TypeError('status must derive from Status.')

    @property
    def allowed_mentions(self) -> Optional[AllowedMentions]:
        """Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration.

        .. versionadded:: 1.4
        """
        return self._connection.allowed_mentions

    @allowed_mentions.setter
    def allowed_mentions(self, value: Optional[AllowedMentions]) -> None:
        if value is None or isinstance(value, AllowedMentions):
            self._connection.allowed_mentions = value
        else:
            raise TypeError(f'allowed_mentions must be AllowedMentions not {value.__class__!r}')

    @property
    def intents(self) -> Intents:
        """:class:`~discord.Intents`: The intents configured for this connection.

        .. versionadded:: 1.5
        """
        return self._connection.intents

    # helpers/getters

    @property
    def users(self) -> List[User]:
        """List[:class:`~discord.User`]: Returns a list of all the users the bot can see."""
        return list(self._connection._users.values())

    def get_channel(self, id: int, /) -> Optional[Union[GuildChannel, Thread, PrivateChannel]]:
        """Returns a channel or thread with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[Union[:class:`.abc.GuildChannel`, :class:`.Thread`, :class:`.abc.PrivateChannel`]]
            The returned channel or ``None`` if not found.
        """
        return self._connection.get_channel(id)

    def get_partial_messageable(self, id: int, *, type: Optional[ChannelType] = None) -> PartialMessageable:
        """Returns a partial messageable with the given channel ID.

        This is useful if you have a channel_id but don't want to do an API call
        to send messages to it.
        
        .. versionadded:: 2.0

        Parameters
        -----------
        id: :class:`int`
            The channel ID to create a partial messageable for.
        type: Optional[:class:`.ChannelType`]
            The underlying channel type for the partial messageable.

        Returns
        --------
        :class:`.PartialMessageable`
            The partial messageable
        """
        return PartialMessageable(state=self._connection, id=id, type=type)

    def get_stage_instance(self, id: int, /) -> Optional[StageInstance]:
        """Returns a stage instance with the given stage channel ID.

        .. versionadded:: 2.0

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`.StageInstance`]
            The returns stage instance of ``None`` if not found.
        """
        from .channel import StageChannel

        channel = self._connection.get_channel(id)

        if isinstance(channel, StageChannel):
            return channel.instance

    def get_guild(self, id: int, /) -> Optional[Guild]:
        """Returns a guild with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`.Guild`]
            The guild or ``None`` if not found.
        """
        return self._connection._get_guild(id)

    def get_user(self, id: int, /) -> Optional[User]:
        """Returns a user with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`~discord.User`]
            The user or ``None`` if not found.
        """
        return self._connection.get_user(id)

    def get_emoji(self, id: int, /) -> Optional[Emoji]:
        """Returns an emoji with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`.Emoji`]
            The custom emoji or ``None`` if not found.
        """
        return self._connection.get_emoji(id)

    def get_sticker(self, id: int, /) -> Optional[GuildSticker]:
        """Returns a guild sticker with the given ID.

        .. versionadded:: 2.0

        .. note::

            To retrieve standard stickers, use :meth:`.fetch_sticker`.
            or :meth:`.fetch_premium_sticker_packs`.

        Returns
        --------
        Optional[:class:`.GuildSticker`]
            The sticker or ``None`` if not found.
        """
        return self._connection.get_sticker(id)

    def get_all_channels(self) -> Generator[GuildChannel, None, None]:
        """A generator that retrieves every :class:`.abc.GuildChannel` the client can 'access'.

        This is equivalent to: ::

            for guild in client.guilds:
                for channel in guild.channels:
                    yield channel

        .. note::

            Just because you receive a :class:`.abc.GuildChannel` does not mean that
            you can communicate in said channel. :meth:`.abc.GuildChannel.permissions_for` should
            be used for that.

        Yields
        ------
        :class:`.abc.GuildChannel`
            A channel the client can 'access'.
        """

        for guild in self.guilds:
            yield from guild.channels

    def get_all_members(self) -> Generator[Member, None, None]:
        """Returns a generator with every :class:`.Member` the client can see.

        This is equivalent to: ::

            for guild in client.guilds:
                for member in guild.members:
                    yield member

        Yields
        ------
        :class:`.Member`
            A member the client can see.
        """
        for guild in self.guilds:
            yield from guild.members

    # listeners/waiters

    async def wait_until_ready(self) -> None:
        """|coro|

        Waits until the client's internal cache is all ready.
        """
        await self._ready.wait()

    def wait_for(
        self,
        event: str,
        *,
        check: Optional[Callable[..., bool]] = None,
        timeout: Optional[float] = None,
    ) -> Any:
        """|coro|

        Waits for a WebSocket event to be dispatched.

        This could be used to wait for a user to reply to a message,
        or to react to a message, or to edit a message in a self-contained
        way.

        The ``timeout`` parameter is passed onto :func:`asyncio.wait_for`. By default,
        it does not timeout. Note that this does propagate the
        :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for
        ease of use.

        In case the event returns multiple arguments, a :class:`tuple` containing those
        arguments is returned instead. Please check the
        :ref:`documentation <discord-api-events>` for a list of events and their
        parameters.

        This function returns the **first event that meets the requirements**.

        Examples
        ---------

        Waiting for a user reply: ::

            @client.event
            async def on_message(message):
                if message.content.startswith('$greet'):
                    channel = message.channel
                    await channel.send('Say hello!')

                    def check(m):
                        return m.content == 'hello' and m.channel == channel

                    msg = await client.wait_for('message', check=check)
                    await channel.send(f'Hello {msg.author}!')

        Waiting for a thumbs up reaction from the message author: ::

            @client.event
            async def on_message(message):
                if message.content.startswith('$thumb'):
                    channel = message.channel
                    await channel.send('Send me that \N{THUMBS UP SIGN} reaction, mate')

                    def check(reaction, user):
                        return user == message.author and str(reaction.emoji) == '\N{THUMBS UP SIGN}'

                    try:
                        reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
                    except asyncio.TimeoutError:
                        await channel.send('\N{THUMBS DOWN SIGN}')
                    else:
                        await channel.send('\N{THUMBS UP SIGN}')


        Parameters
        ------------
        event: :class:`str`
            The event name, similar to the :ref:`event reference <discord-api-events>`,
            but without the ``on_`` prefix, to wait for.
        check: Optional[Callable[..., :class:`bool`]]
            A predicate to check what to wait for. The arguments must meet the
            parameters of the event being waited for.
        timeout: Optional[:class:`float`]
            The number of seconds to wait before timing out and raising
            :exc:`asyncio.TimeoutError`.

        Raises
        -------
        asyncio.TimeoutError
            If a timeout is provided and it was reached.

        Returns
        --------
        Any
            Returns no arguments, a single argument, or a :class:`tuple` of multiple
            arguments that mirrors the parameters passed in the
            :ref:`event reference <discord-api-events>`.
        """

        future = self.loop.create_future()
        if check is None:
            def _check(*args):
                return True
            check = _check

        ev = event.lower()
        try:
            listeners = self._listeners[ev]
        except KeyError:
            listeners = []
            self._listeners[ev] = listeners

        listeners.append((future, check))
        return asyncio.wait_for(future, timeout)

    # event registration

    def event(self, coro: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, Coroutine[Any, Any, T]]:
        """A decorator that registers an event to listen to.

        You can find more info about the events on the :ref:`documentation below <discord-api-events>`.

        The events must be a :ref:`coroutine <coroutine>`, if not, :exc:`TypeError` is raised.

        Example
        ---------

        .. code-block:: python3

            @client.event
            async def on_ready():
                print('Ready!')

        Raises
        --------
        TypeError
            The coroutine passed is not actually a coroutine.
        """

        if not asyncio.iscoroutinefunction(coro):
            raise TypeError('event registered must be a coroutine function')

        setattr(self, coro.__name__, coro)
        _log.debug('%s has successfully been registered as an event', coro.__name__)
        return coro

    async def change_presence(
        self,
        *,
        activity: Optional[BaseActivity] = None,
        status: Optional[Status] = None,
    ) -> None:
        """|coro|

        Changes the client's presence.

        Example
        ---------

        .. code-block:: python3

            game = discord.Game("with the API")
            await client.change_presence(status=discord.Status.idle, activity=game)

        .. versionchanged:: 2.0
            Removed the ``afk`` keyword-only parameter.

        Parameters
        ----------
        activity: Optional[:class:`.BaseActivity`]
            The activity being done. ``None`` if no currently active activity is done.
        status: Optional[:class:`.Status`]
            Indicates what status to change to. If ``None``, then
            :attr:`.Status.online` is used.

        Raises
        ------
        :exc:`.InvalidArgument`
            If the ``activity`` parameter is not the proper type.
        """

        if status is None:
            status_str = 'online'
            status = Status.online
        elif status is Status.offline:
            status_str = 'invisible'
            status = Status.offline
        else:
            status_str = str(status)

        await self.ws.change_presence(activity=activity, status=status_str)

        for guild in self._connection.guilds:
            me = guild.me
            if me is None:
                continue

            if activity is not None:
                me.activities = (activity,)  # type: ignore
            else:
                me.activities = ()

            me.status = status

    # Guild stuff

    def fetch_guilds(
        self,
        *,
        limit: Optional[int] = 100,
        before: SnowflakeTime = None,
        after: SnowflakeTime = None
    ) -> GuildIterator:
        """Retrieves an :class:`.AsyncIterator` that enables receiving your guilds.

        .. note::

            Using this, you will only receive :attr:`.Guild.owner`, :attr:`.Guild.icon`,
            :attr:`.Guild.id`, and :attr:`.Guild.name` per :class:`.Guild`.

        .. note::

            This method is an API call. For general usage, consider :attr:`guilds` instead.

        Examples
        ---------

        Usage ::

            async for guild in client.fetch_guilds(limit=150):
                print(guild.name)

        Flattening into a list ::

            guilds = await client.fetch_guilds(limit=150).flatten()
            # guilds is now a list of Guild...

        All parameters are optional.

        Parameters
        -----------
        limit: Optional[:class:`int`]
            The number of guilds to retrieve.
            If ``None``, it retrieves every guild you have access to. Note, however,
            that this would make it a slow operation.
            Defaults to ``100``.
        before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
            Retrieves guilds before this date or object.
            If a datetime is provided, it is recommended to use a UTC aware datetime.
            If the datetime is naive, it is assumed to be local time.
        after: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
            Retrieve guilds after this date or object.
            If a datetime is provided, it is recommended to use a UTC aware datetime.
            If the datetime is naive, it is assumed to be local time.

        Raises
        ------
        :exc:`.HTTPException`
            Getting the guilds failed.

        Yields
        --------
        :class:`.Guild`
            The guild with the guild data parsed.
        """
        return GuildIterator(self, limit=limit, before=before, after=after)

    async def fetch_template(self, code: Union[Template, str]) -> Template:
        """|coro|

        Gets a :class:`.Template` from a discord.new URL or code.

        Parameters
        -----------
        code: Union[:class:`.Template`, :class:`str`]
            The Discord Template Code or URL (must be a discord.new URL).

        Raises
        -------
        :exc:`.NotFound`
            The template is invalid.
        :exc:`.HTTPException`
            Getting the template failed.

        Returns
        --------
        :class:`.Template`
            The template from the URL/code.
        """
        code = utils.resolve_template(code)
        data = await self.http.get_template(code)
        return Template(data=data, state=self._connection) # type: ignore

    async def fetch_guild(self, guild_id: int, /) -> Guild:
        """|coro|

        Retrieves a :class:`.Guild` from an ID.

        .. note::

            Using this, you will **not** receive :attr:`.Guild.channels`, :attr:`.Guild.members`,
            :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.

        .. note::

            This method is an API call. For general usage, consider :meth:`get_guild` instead.

        Parameters
        -----------
        guild_id: :class:`int`
            The guild's ID to fetch from.

        Raises
        ------
        :exc:`.Forbidden`
            You do not have access to the guild.
        :exc:`.HTTPException`
            Getting the guild failed.

        Returns
        --------
        :class:`.Guild`
            The guild from the ID.
        """
        data = await self.http.get_guild(guild_id)
        return Guild(data=data, state=self._connection)

    async def create_guild(
        self,
        *,
        name: str,
        region: Union[VoiceRegion, str] = VoiceRegion.us_west,
        icon: bytes = MISSING,
        code: str = MISSING,
    ) -> Guild:
        """|coro|

        Creates a :class:`.Guild`.

        Bot accounts in more than 10 guilds are not allowed to create guilds.

        Parameters
        ----------
        name: :class:`str`
            The name of the guild.
        region: :class:`.VoiceRegion`
            The region for the voice communication server.
            Defaults to :attr:`.VoiceRegion.us_west`.
        icon: Optional[:class:`bytes`]
            The :term:`py:bytes-like object` representing the icon. See :meth:`.ClientUser.edit`
            for more details on what is expected.
        code: :class:`str`
            The code for a template to create the guild with.

            .. versionadded:: 1.4

        Raises
        ------
        :exc:`.HTTPException`
            Guild creation failed.
        :exc:`.InvalidArgument`
            Invalid icon image format given. Must be PNG or JPG.

        Returns
        -------
        :class:`.Guild`
            The guild created. This is not the same guild that is
            added to cache.
        """
        if icon is not MISSING:
            icon_base64 = utils._bytes_to_base64_data(icon)
        else:
            icon_base64 = None

        region_value = str(region)

        if code:
            data = await self.http.create_from_template(code, name, region_value, icon_base64)
        else:
            data = await self.http.create_guild(name, region_value, icon_base64)
        return Guild(data=data, state=self._connection)

    async def fetch_stage_instance(self, channel_id: int, /) -> StageInstance:
        """|coro|

        Gets a :class:`.StageInstance` for a stage channel id.

        .. versionadded:: 2.0

        Parameters
        -----------
        channel_id: :class:`int`
            The stage channel ID.

        Raises
        -------
        :exc:`.NotFound`
            The stage instance or channel could not be found.
        :exc:`.HTTPException`
            Getting the stage instance failed.

        Returns
        --------
        :class:`.StageInstance`
            The stage instance from the stage channel ID.
        """
        data = await self.http.get_stage_instance(channel_id)
        guild = self.get_guild(int(data['guild_id']))
        return StageInstance(guild=guild, state=self._connection, data=data)  # type: ignore

    # Invite management

    async def fetch_invite(
        self, url: Union[Invite, str], *, with_counts: bool = True, with_expiration: bool = True, scheduled_event_id: Optional[int] = None
    ) -> Invite:
        """|coro|

        Gets an :class:`.Invite` from a discord.gg URL or ID.

        .. note::

            If the invite is for a guild you have not joined, the guild and channel
            attributes of the returned :class:`.Invite` will be :class:`.PartialInviteGuild` and
            :class:`.PartialInviteChannel` respectively.

        Parameters
        -----------
        url: Union[:class:`.Invite`, :class:`str`]
            The Discord invite ID or URL (must be a discord.gg URL).
        with_counts: :class:`bool`
            Whether to include count information in the invite. This fills the
            :attr:`.Invite.approximate_member_count` and :attr:`.Invite.approximate_presence_count`
            fields.
        with_expiration: :class:`bool`
            Whether to include the expiration date of the invite. This fills the
            :attr:`.Invite.expires_at` field.

            .. versionadded:: 2.0
        scheduled_event_id: Optional[:class:`int`]
            The ID of the scheduled event to include information about in the invite.
            This fills the :attr:`.Invite.scheduled_event` field. If the ID is invalid,
            the field will be ``None``.

        Raises
        -------
        :exc:`.NotFound`
            The invite has expired or is invalid.
        :exc:`.HTTPException`
            Getting the invite failed.

        Returns
        --------
        :class:`.Invite`
            The invite from the URL/ID.
        """

        invite_id = utils.resolve_invite(url)
        data = await self.http.get_invite(
            invite_id, with_counts=with_counts, with_expiration=with_expiration, scheduled_event_id=scheduled_event_id
        )
        return Invite.from_incomplete(state=self._connection, data=data)

    async def delete_invite(self, invite: Union[Invite, str]) -> None:
        """|coro|

        Revokes an :class:`.Invite`, URL, or ID to an invite.

        You must have the :attr:`~.Permissions.manage_channels` permission in
        the associated guild to do this.

        Parameters
        ----------
        invite: Union[:class:`.Invite`, :class:`str`]
            The invite to revoke.

        Raises
        -------
        :exc:`.Forbidden`
            You do not have permissions to revoke invites.
        :exc:`.NotFound`
            The invite is invalid or expired.
        :exc:`.HTTPException`
            Revoking the invite failed.
        """

        invite_id = utils.resolve_invite(invite)
        await self.http.delete_invite(invite_id)

    # Miscellaneous stuff

    async def fetch_widget(self, guild_id: int, /) -> Widget:
        """|coro|

        Gets a :class:`.Widget` from a guild ID.

        .. note::

            The guild must have the widget enabled to get this information.

        Parameters
        -----------
        guild_id: :class:`int`
            The ID of the guild.

        Raises
        -------
        :exc:`.Forbidden`
            The widget for this guild is disabled.
        :exc:`.HTTPException`
            Retrieving the widget failed.

        Returns
        --------
        :class:`.Widget`
            The guild's widget.
        """
        data = await self.http.get_widget(guild_id)

        return Widget(state=self._connection, data=data)

    async def application_info(self) -> AppInfo:
        """|coro|

        Retrieves the bot's application information.

        Raises
        -------
        :exc:`.HTTPException`
            Retrieving the information failed somehow.

        Returns
        --------
        :class:`.AppInfo`
            The bot's application information.
        """
        data = await self.http.application_info()
        if 'rpc_origins' not in data:
            data['rpc_origins'] = None
        return AppInfo(self._connection, data)

    async def fetch_user(self, user_id: int, /) -> User:
        """|coro|

        Retrieves a :class:`~discord.User` based on their ID.
        You do not have to share any guilds with the user to get this information,
        however many operations do require that you do.

        .. note::

            This method is an API call. If you have :attr:`discord.Intents.members` and member cache enabled, consider :meth:`get_user` instead.

        Parameters
        -----------
        user_id: :class:`int`
            The user's ID to fetch from.

        Raises
        -------
        :exc:`.NotFound`
            A user with this ID does not exist.
        :exc:`.HTTPException`
            Fetching the user failed.

        Returns
        --------
        :class:`~discord.User`
            The user you requested.
        """
        data = await self.http.get_user(user_id)
        return User(state=self._connection, data=data)

    async def fetch_channel(self, channel_id: int, /) -> Union[GuildChannel, PrivateChannel, Thread]:
        """|coro|

        Retrieves a :class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, or :class:`.Thread` with the specified ID.

        .. note::

            This method is an API call. For general usage, consider :meth:`get_channel` instead.

        .. versionadded:: 1.2

        Raises
        -------
        :exc:`.InvalidData`
            An unknown channel type was received from Discord.
        :exc:`.HTTPException`
            Retrieving the channel failed.
        :exc:`.NotFound`
            Invalid Channel ID.
        :exc:`.Forbidden`
            You do not have permission to fetch this channel.

        Returns
        --------
        Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, :class:`.Thread`]
            The channel from the ID.
        """
        data = await self.http.get_channel(channel_id)

        factory, ch_type = _threaded_channel_factory(data['type'])
        if factory is None:
            raise InvalidData('Unknown channel type {type} for channel ID {id}.'.format_map(data))

        if ch_type in (ChannelType.group, ChannelType.private):
            # the factory will be a DMChannel or GroupChannel here
            channel = factory(me=self.user, data=data, state=self._connection) # type: ignore
        else:
            # the factory can't be a DMChannel or GroupChannel here
            guild_id = int(data['guild_id']) # type: ignore
            guild = self.get_guild(guild_id) or Object(id=guild_id)
            # GuildChannels expect a Guild, we may be passing an Object
            channel = factory(guild=guild, state=self._connection, data=data) # type: ignore

        return channel

    async def fetch_webhook(self, webhook_id: int, /) -> Webhook:
        """|coro|

        Retrieves a :class:`.Webhook` with the specified ID.

        Raises
        --------
        :exc:`.HTTPException`
            Retrieving the webhook failed.
        :exc:`.NotFound`
            Invalid webhook ID.
        :exc:`.Forbidden`
            You do not have permission to fetch this webhook.

        Returns
        ---------
        :class:`.Webhook`
            The webhook you requested.
        """
        data = await self.http.get_webhook(webhook_id)
        return Webhook.from_state(data, state=self._connection)

    async def fetch_sticker(self, sticker_id: int, /) -> Union[StandardSticker, GuildSticker]:
        """|coro|

        Retrieves a :class:`.Sticker` with the specified ID.

        .. versionadded:: 2.0

        Raises
        --------
        :exc:`.HTTPException`
            Retrieving the sticker failed.
        :exc:`.NotFound`
            Invalid sticker ID.

        Returns
        --------
        Union[:class:`.StandardSticker`, :class:`.GuildSticker`]
            The sticker you requested.
        """
        data = await self.http.get_sticker(sticker_id)
        cls, _ = _sticker_factory(data['type'])  # type: ignore
        return cls(state=self._connection, data=data) # type: ignore

    async def fetch_premium_sticker_packs(self) -> List[StickerPack]:
        """|coro|

        Retrieves all available premium sticker packs.

        .. versionadded:: 2.0

        Raises
        -------
        :exc:`.HTTPException`
            Retrieving the sticker packs failed.

        Returns
        ---------
        List[:class:`.StickerPack`]
            All available premium sticker packs.
        """
        data = await self.http.list_premium_sticker_packs()
        return [StickerPack(state=self._connection, data=pack) for pack in data['sticker_packs']]

    async def create_dm(self, user: Snowflake) -> DMChannel:
        """|coro|

        Creates a :class:`.DMChannel` with this user.

        This should be rarely called, as this is done transparently for most
        people.

        .. versionadded:: 2.0

        Parameters
        -----------
        user: :class:`~discord.abc.Snowflake`
            The user to create a DM with.

        Returns
        -------
        :class:`.DMChannel`
            The channel that was created.
        """
        state = self._connection
        found = state._get_private_channel_by_user(user.id)
        if found:
            return found

        data = await state.http.start_private_message(user.id)
        return state.add_dm_channel(data)

    def add_view(self, view: View, *, message_id: Optional[int] = None) -> None:
        """Registers a :class:`~discord.ui.View` for persistent listening.

        This method should be used for when a view is comprised of components
        that last longer than the lifecycle of the program.
        
        .. versionadded:: 2.0

        Parameters
        ------------
        view: :class:`discord.ui.View`
            The view to register for dispatching.
        message_id: Optional[:class:`int`]
            The message ID that the view is attached to. This is currently used to
            refresh the view's state during message update events. If not given
            then message update events are not propagated for the view.

        Raises
        -------
        TypeError
            A view was not passed.
        ValueError
            The view is not persistent. A persistent view has no timeout
            and all their components have an explicitly provided custom_id.
        """

        if not isinstance(view, View):
            raise TypeError(f'expected an instance of View not {view.__class__!r}')

        if not view.is_persistent():
            raise ValueError('View is not persistent. Items need to have a custom_id set and View must have no timeout')

        self._connection.store_view(view, message_id)

    @property
    def persistent_views(self) -> Sequence[View]:
        """Sequence[:class:`.View`]: A sequence of persistent views added to the client.
        
        .. versionadded:: 2.0
        """
        return self._connection.persistent_views

    async def is_owner(self, user: Snowflake) -> bool:
        """|coro|

        Checks if a :class:`~discord.abc.Snowflake` is the owner of
        this bot.

        If an :attr:`owner_id` is not set, it is fetched automatically
        through the use of :meth:`~.Bot.application_info`.

        .. versionchanged:: 1.3
            The function also checks if the application is team-owned if
            :attr:`owner_ids` is not set.

        Parameters
        -----------
        user: :class:`.abc.Snowflake`
            The user to check for.

        Returns
        --------
        :class:`bool`
            Whether the user is the owner.
        """

        if self.owner_id:
            return user.id == self.owner_id
        elif self.owner_ids:
            return user.id in self.owner_ids
        else:
            app = await self.application_info()
            if app.team:
                self.owner_ids = ids = {m.id for m in app.team.members}
                return user.id in ids
            else:
                self.owner_id = owner_id = app.owner.id
                return user.id == owner_id

    # listener registration

    def add_listener(self, func: CoroFunc, name: str = MISSING) -> None:
        """The non decorator alternative to :meth:`.listen`.

        Parameters
        -----------
        func: :ref:`coroutine <coroutine>`
            The function to call.
        name: :class:`str`
            The name of the event to listen for. Defaults to ``func.__name__``.

        Example
        --------

        .. code-block:: python3

            async def on_ready(): pass
            async def my_message(message): pass

            bot.add_listener(on_ready)
            bot.add_listener(my_message, 'on_message')

        """
        name = func.__name__ if name is MISSING else name

        if not asyncio.iscoroutinefunction(func):
            raise TypeError('Listeners must be coroutines')

        if name in self.extra_events:
            self.extra_events[name].append(func)
        else:
            self.extra_events[name] = [func]

    def remove_listener(self, func: CoroFunc, name: str = MISSING) -> None:
        """Removes a listener from the pool of listeners.

        Parameters
        -----------
        func
            The function that was used as a listener to remove.
        name: :class:`str`
            The name of the event we want to remove. Defaults to
            ``func.__name__``.
        """

        name = func.__name__ if name is MISSING else name

        if name in self.extra_events:
            try:
                self.extra_events[name].remove(func)
            except ValueError:
                pass

    def listen(self, name: str = MISSING) -> Callable[[CFT], CFT]:
        """A decorator that registers another function as an external
        event listener. Basically this allows you to listen to multiple
        events from different places e.g. such as :func:`.on_ready`

        The functions being listened to must be a :ref:`coroutine <coroutine>`.

        Example
        --------

        .. code-block:: python3

            @client.listen()
            async def on_message(message):
                print('one')

            # in some other file...

            @client.listen('on_message')
            async def my_message(message):
                print('two')

        Would print one and two in an unspecified order.

        Raises
        -------
        TypeError
            The function being listened to is not a coroutine.
        """

        def decorator(func: CFT) -> CFT:
            self.add_listener(func, name)
            return func

        return decorator

    # cogs

    def add_cog(self, cog: Cog, *, override: bool = False) -> None:
        """Adds a "cog" client.

        A cog is a class that has its own event listeners and commands.

        .. versionchanged:: 2.0

            :exc:`.ClientException` is raised when a cog with the same name
            is already loaded.

        Parameters
        -----------
        cog: :class:`.Cog`
            The cog to register client.
        override: :class:`bool`
            If a previously loaded cog with the same name should be ejected
            instead of raising an error.

            .. versionadded:: 2.0

        Raises
        -------
        TypeError
            The cog does not inherit from :class:`.Cog`.
        CommandError
            An error happened during loading.
        .ClientException
            A cog with the same name is already loaded.
        """

        # circular import
        from .cog import Cog

        if not isinstance(cog, Cog):
            raise TypeError('cogs must derive from Cog')

        cog_name = cog.__cog_name__
        existing = self.__cogs.get(cog_name)

        if existing is not None:
            if not override:
                raise ClientException(f'Cog named {cog_name!r} already loaded')
            self.remove_cog(cog_name)

        cog = cog._inject(self)
        self.__cogs[cog_name] = cog

    def get_cog(self, name: str) -> Optional[Cog]:
        """Gets the cog instance requested.

        If the cog is not found, ``None`` is returned instead.

        Parameters
        -----------
        name: :class:`str`
            The name of the cog you are requesting.
            This is equivalent to the name passed via keyword
            argument in class creation or the class name if unspecified.

        Returns
        --------
        Optional[:class:`Cog`]
            The cog that was requested. If not found, returns ``None``.
        """
        return self.__cogs.get(name)

    def remove_cog(self, name: str) -> Optional[Cog]:
        """Removes a cog from the client and returns it.

        All registered commands and event listeners that the
        cog has registered will be removed as well.

        If no cog is found then this method has no effect.

        Parameters
        -----------
        name: :class:`str`
            The name of the cog to remove.

        Returns
        -------
        Optional[:class:`.Cog`]
            The cog that was removed. ``None`` if not found.
        """

        cog = self.__cogs.pop(name, None)
        if cog is None:
            return

        # circular import
        from .ext.commands.bot import Bot

        if isinstance(self, Bot):
            help_command = self._help_command
            if help_command and help_command.cog is cog:
                help_command.cog = None

        cog._eject(self)

        return cog

    @property
    def cogs(self) -> Mapping[str, Cog]:
        """Mapping[:class:`str`, :class:`Cog`]: A read-only mapping of cog name to cog."""
        return types.MappingProxyType(self.__cogs)

    # extensions

    def _remove_module_references(self, name: str) -> None:
        # find all references to the module
        # remove the cogs registered from the module
        for cogname, cog in self.__cogs.copy().items():
            if _is_submodule(name, cog.__module__):
                self.remove_cog(cogname)

        # circular imports
        from .ext.commands.bot import Bot
        from .ext.commands.core import GroupMixin

        # remove all the commands from the module
        if isinstance(self, Bot):
            for cmd in self.all_commands.copy().values():
                if cmd.module is not None and _is_submodule(name, cmd.module):
                    if isinstance(cmd, GroupMixin):
                        cmd.recursively_remove_all_commands()
                    self.remove_command(cmd.name)

        # remove all the listeners from the module
        for event_list in self.extra_events.copy().values():
            remove = []
            for index, event in enumerate(event_list):
                if event.__module__ is not None and _is_submodule(name, event.__module__):
                    remove.append(index)

            for index in reversed(remove):
                del event_list[index]

    def _call_module_finalizers(self, lib: types.ModuleType, key: str) -> None:
        try:
            func = getattr(lib, 'teardown')
        except AttributeError:
            pass
        else:
            try:
                func(self)
            except Exception:
                pass
        finally:
            self.__extensions.pop(key, None)
            sys.modules.pop(key, None)
            name = lib.__name__
            for module in list(sys.modules.keys()):
                if _is_submodule(name, module):
                    del sys.modules[module]

    def _load_from_module_spec(self, spec: importlib.machinery.ModuleSpec, key: str) -> None:
        # precondition: key not in self.__extensions
        lib = importlib.util.module_from_spec(spec)
        sys.modules[key] = lib
        try:
            spec.loader.exec_module(lib)  # type: ignore
        except Exception as e:
            del sys.modules[key]
            raise ExtensionFailed(key, e) from e

        try:
            setup = getattr(lib, 'setup')
        except AttributeError:
            del sys.modules[key]
            raise NoEntryPointError(key)

        try:
            setup(self)
        except Exception as e:
            del sys.modules[key]
            self._remove_module_references(lib.__name__)
            self._call_module_finalizers(lib, key)
            raise ExtensionFailed(key, e) from e
        else:
            self.__extensions[key] = lib

    def _resolve_name(self, name: str, package: Optional[str]) -> str:
        try:
            return importlib.util.resolve_name(name, package)
        except ImportError:
            raise ExtensionNotFound(name)

    def load_extension(self, name: str, *, package: Optional[str] = None) -> None:
        """Loads an extension.

        An extension is a python module that contains commands, cogs, or
        listeners.

        An extension must have a global function, ``setup`` defined as
        the entry point on what to do when the extension is loaded. This entry
        point must have a single argument, the ``client``.

        Parameters
        ------------
        name: :class:`str`
            The extension name to load. It must be dot separated like
            regular Python imports if accessing a sub-module. e.g.
            ``foo.test`` if you want to import ``foo/test.py``.
        package: Optional[:class:`str`]
            The package name to resolve relative imports with.
            This is required when loading an extension using a relative path, e.g ``.foo.test``.
            Defaults to ``None``.

            .. versionadded:: 1.7

        Raises
        --------
        ExtensionNotFound
            The extension could not be imported.
            This is also raised if the name of the extension could not
            be resolved using the provided ``package`` parameter.
        ExtensionAlreadyLoaded
            The extension is already loaded.
        NoEntryPointError
            The extension does not have a setup function.
        ExtensionFailed
            The extension or its setup function had an execution error.
        """

        name = self._resolve_name(name, package)
        if name in self.__extensions:
            raise ExtensionAlreadyLoaded(name)

        spec = importlib.util.find_spec(name)
        if spec is None:
            raise ExtensionNotFound(name)

        self._load_from_module_spec(spec, name)

    def unload_extension(self, name: str, *, package: Optional[str] = None) -> None:
        """Unloads an extension.

        When the extension is unloaded, all commands, listeners, and cogs are
        removed from the client and the module is un-imported.

        The extension can provide an optional global function, ``teardown``,
        to do miscellaneous clean-up if necessary. This function takes a single
        parameter, the ``client``, similar to ``setup`` from
        :meth:`.load_extension`.

        Parameters
        ------------
        name: :class:`str`
            The extension name to unload. It must be dot separated like
            regular Python imports if accessing a sub-module. e.g.
            ``foo.test`` if you want to import ``foo/test.py``.
        package: Optional[:class:`str`]
            The package name to resolve relative imports with.
            This is required when unloading an extension using a relative path, e.g ``.foo.test``.
            Defaults to ``None``.

            .. versionadded:: 1.7

        Raises
        -------
        ExtensionNotFound
            The name of the extension could not
            be resolved using the provided ``package`` parameter.
        ExtensionNotLoaded
            The extension was not loaded.
        """

        name = self._resolve_name(name, package)
        lib = self.__extensions.get(name)
        if lib is None:
            raise ExtensionNotLoaded(name)

        self._remove_module_references(lib.__name__)
        self._call_module_finalizers(lib, name)

    def reload_extension(self, name: str, *, package: Optional[str] = None) -> None:
        """Atomically reloads an extension.

        This replaces the extension with the same extension, only refreshed. This is
        equivalent to a :meth:`unload_extension` followed by a :meth:`load_extension`
        except done in an atomic way. That is, if an operation fails mid-reload then
        the client will roll-back to the prior working state.

        Parameters
        ------------
        name: :class:`str`
            The extension name to reload. It must be dot separated like
            regular Python imports if accessing a sub-module. e.g.
            ``foo.test`` if you want to import ``foo/test.py``.
        package: Optional[:class:`str`]
            The package name to resolve relative imports with.
            This is required when reloading an extension using a relative path, e.g ``.foo.test``.
            Defaults to ``None``.

            .. versionadded:: 1.7

        Raises
        -------
        ExtensionNotLoaded
            The extension was not loaded.
        ExtensionNotFound
            The extension could not be imported.
            This is also raised if the name of the extension could not
            be resolved using the provided ``package`` parameter.
        NoEntryPointError
            The extension does not have a setup function.
        ExtensionFailed
            The extension setup function had an execution error.
        """

        name = self._resolve_name(name, package)
        lib = self.__extensions.get(name)
        if lib is None:
            raise ExtensionNotLoaded(name)

        # get the previous module states from sys modules
        modules = {
            name: module
            for name, module in sys.modules.items()
            if _is_submodule(lib.__name__, name)
        }

        try:
            # Unload and then load the module...
            self._remove_module_references(lib.__name__)
            self._call_module_finalizers(lib, name)
            self.load_extension(name)
        except Exception:
            # if the load failed, the remnants should have been
            # cleaned from the load_extension function call
            # so let's load it from our old compiled library.
            lib.setup(self)  # type: ignore
            self.__extensions[name] = lib

            # revert sys.modules back to normal and raise back to caller
            sys.modules.update(modules)
            raise

    @property
    def extensions(self) -> Mapping[str, types.ModuleType]:
        """Mapping[:class:`str`, :class:`py:types.ModuleType`]: A read-only mapping of extension name to extension."""
        return types.MappingProxyType(self.__extensions)

    # application commands

    @property
    def application_commands(self) -> List[ApplicationCommand]:
        """List[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]: A list of application commands added to the client.

        .. versionadded:: 2.0
        """
        return list(self._application_commands.values())

    def add_application_command(self, application_command: ApplicationCommand) -> None:
        """Adds an application command to the client.

        Parameters
        -----------
        application_command: Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]
            The application command to add.

        Raises
        ------
        TypeError
            The application command passed is not an application command instance.
        """
        if not isinstance(application_command, _valid_application_command_types):
            raise TypeError(f'application_command must derive from SlashCommand, MessageCommand, or UserCommand')

        if application_command.__application_command_guild_ids__ is not None and self.application_command_guild_ids is not None:
            application_command.__application_command_guild_ids__ = self.application_command_guild_ids
            application_command.__application_command_global_command__ = False

        self._application_commands[application_command._get_key()] = application_command
        subcommands = list(application_command.__application_command_subcommands__.items())
        while subcommands:
            name, subcommand = subcommands.pop(0)
            subcommand.__application_command_parent__ = application_command  # type: ignore

            if inspect.isclass(subcommand):
                # parent won't be None
                application_command.__application_command_subcommands__[name] = subcommand()  # type: ignore

            subcommands.extend(subcommand.__application_command_subcommands__.items())  # type: ignore

    def remove_application_command(self, application_command: Union[ApplicationCommand, Type[ApplicationCommand]]) -> Optional[ApplicationCommand]:
        """Removes an application command from the client.

        Parameters
        -----------
        application_command: Union[
            :class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`,
            Type[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]
        ]
            The application command to remove. This can be an instance of the application command
            or its class.

        Raises
        ------
        TypeError
            The application command passed is not an application command.

        Returns
        -------
        Optional[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]
            The application command that was removed. ``None`` if not found.
        """

        if not hasattr(application_command, '__discord_application_command__'):
            raise TypeError('application_command must derive from SlashCommand, MessageCommand, or UserCommand')

        return self._application_commands.pop(application_command._get_key(), None)

    def add_application_command_check(self, func: Check) -> None:
        """Adds a global application command check client.

        This is the non-decorator interface to :meth:`.application_command_check`.

        Parameters
        -----------
        func
            The function that was used as a global check.
            This function can either be a regular function or a coroutine.
        """

        self._application_command_checks.append(func)

    def application_command_check(self, func: T) -> T:
        r"""A decorator that adds a global application command check to the client.

        A global check is similar to an application command's ``command_check`` method
        that is applied on a per command basis except it is run before any command checks
        have been run and applies to every application command the client has.

        .. note::

            This function can either be a regular function or a coroutine.

        This takes a single parameter, which is the response of the application command. The type of it can be
        :class:`SlashCommandResponse`, :class:`MessageCommandResponse` or :class:`UserCommandResponse`.

        Example
        ---------

        .. code-block:: python3

            @client.application_command_check
            async def check_commands(response):
                return await client.is_owner(response.user)

        """
        # T was used instead of Check to ensure the type matches on return
        self.add_application_command_check(func)  # type: ignore
        return func

    def application_command(self, cls: Type[AT]) -> Type[AT]:
        r"""A decorator that adds an application command to the client.

        The class being decorated must subclass :class:`SlashCommand`\, :class:`MessageCommand` or :class:`UserCommand`.

        This decorator is a shortcut method to :meth:`add_application_command` that passes an instantiated version
        of the decorated class.

        .. note::

            If you need to pass parameters to the ``__init__`` of the class\,
            call :meth:`add_application_command` yourself.

        Raises
        ------
        TypeError
            The application command passed does not derive from a valid application command class.
        """

        self.add_application_command(cls())
        return cls

    async def register_application_commands(self) -> None:
        """|coro|
        
        Registers all application commands added to the client. This will be called in
        :meth:`login` if :attr:`.register_application_commands_at_startup` is ``True``.

        .. note::

            This overwrites existing application commands. For example, if an existing
            slash command has the same name as the one you are registering, it will be
            overwritten.

        .. note::

            Global commands may take 1 hour to register in all guilds.

        Raises
        ------
        :exc:`.HTTPException`
            Registering the application commands failed.
        """

        application_commands = self._application_commands.values()
        if not application_commands:
            return

        application_id = self.application_id
        if application_id is None:
            app = await self.application_info()
            # cache the information from application_info
            self._connection.application_id = application_id = app.id
            if app.team and self.owner_ids is None:
                self.owner_ids = {m.id for m in app.team.members}
            elif self.owner_id is None:
                self.owner_id = app.owner.id

        guild_payloads = collections.defaultdict(list)
        global_payload = []
        for command in application_commands:
            command_payload = command.to_dict()
            guild_ids = command.__application_command_guild_ids__ or []
            for guild_id in guild_ids:
                guild_payloads[guild_id].append(command_payload)

            if command.__application_command_global_command__:
                global_payload.append(command_payload)

        if global_payload:
            await self.http.bulk_upsert_global_commands(application_id, global_payload)

        for guild_id, commands in guild_payloads.items():
            await self.http.bulk_upsert_guild_commands(application_id, guild_id, commands)

"""
The MIT License (MIT)

Copyright (c) 2015-present Rapptz

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
"""

from __future__ import annotations

import asyncio
import logging
import signal
import sys
import traceback
import inspect
import collections
import collections.abc
import types
import importlib.util

from typing import (
    Any,
    Callable,
    Coroutine,
    Dict,
    Generator,
    List,
    Optional,
    Sequence,
    TYPE_CHECKING,
    Tuple,
    TypeVar,
    Union,
    Type,
    Mapping,
)

import aiohttp

from .user import User, ClientUser
from .invite import Invite
from .template import Template
from .widget import Widget
from .guild import Guild
from .emoji import Emoji
from .channel import _threaded_channel_factory, PartialMessageable
from .enums import ChannelType
from .mentions import AllowedMentions
from .errors import *
from .enums import Status, VoiceRegion
from .flags import ApplicationFlags, Intents
from .gateway import *
from .activity import ActivityTypes, BaseActivity, create_activity
from .voice_client import VoiceClient
from .http import HTTPClient
from .state import ConnectionState
from . import utils
from .utils import MISSING
from .object import Object
from .backoff import ExponentialBackoff
from .webhook import Webhook
from .iterators import GuildIterator
from .appinfo import AppInfo
from .ui.view import View
from .stage_instance import StageInstance
from .threads import Thread
from .sticker import GuildSticker, StandardSticker, StickerPack, _sticker_factory
from .application_commands import (
    SlashCommand,
    MessageCommand,
    UserCommand,
    SlashCommandResponse,
    MessageCommandResponse,
    UserCommandResponse
)

if TYPE_CHECKING:
    import importlib.machinery

    from typing_extensions import ParamSpec

    from .ext.commands._types import CoroFunc

    from .abc import SnowflakeTime, PrivateChannel, GuildChannel, Snowflake
    from .channel import DMChannel
    from .message import Message
    from .member import Member
    from .voice_client import VoiceProtocol
    from .cog import Cog

    T = TypeVar('T')
    P = ParamSpec('P')

    ApplicationCommand = Union[SlashCommand, MessageCommand, UserCommand]
    AT = TypeVar('AT', bound=ApplicationCommand)

    Check = Union[
        Callable[[SlashCommandResponse[Any]], Union[bool, Coroutine[Any, Any, bool]]],
        Callable[[UserCommandResponse[Any]], Union[bool, Coroutine[Any, Any, bool]]],
        Callable[[MessageCommandResponse[Any]], Union[bool, Coroutine[Any, Any, bool]]],
    ]
    ApplicationCommandKey = Tuple[str, int, Optional['ApplicationCommandKey']]  # name, type, parent

__all__ = (
    'Client',
)

CFT = TypeVar('CFT', bound='CoroFunc')

_log = logging.getLogger(__name__)
_valid_application_command_types = (SlashCommand, MessageCommand, UserCommand)

def _cancel_tasks(loop: asyncio.AbstractEventLoop) -> None:
    tasks = {t for t in asyncio.all_tasks(loop=loop) if not t.done()}

    if not tasks:
        return

    _log.info('Cleaning up after %d tasks.', len(tasks))
    for task in tasks:
        task.cancel()

    loop.run_until_complete(asyncio.gather(*tasks, return_exceptions=True))
    _log.info('All tasks finished cancelling.')

    for task in tasks:
        if task.cancelled():
            continue
        if task.exception() is not None:
            loop.call_exception_handler({
                'message': 'Unhandled exception during Client.run shutdown.',
                'exception': task.exception(),
                'task': task
            })

def _cleanup_loop(loop: asyncio.AbstractEventLoop) -> None:
    try:
        _cancel_tasks(loop)
        loop.run_until_complete(loop.shutdown_asyncgens())
    finally:
        _log.info('Closing the event loop.')
        loop.close()

def _is_submodule(parent: str, child: str) -> bool:
    return parent == child or child.startswith(parent + ".")

class Client:
    r"""Represents a client connection that connects to Discord.
    This class is used to interact with the Discord WebSocket and API.

    A number of options can be passed to the :class:`Client`.

    Parameters
    -----------
    application_id: :class:`int`
        The client's application ID.
    max_messages: Optional[:class:`int`]
        The maximum number of messages to store in the internal message cache.
        This defaults to ``1000``. Passing in ``None`` disables the message cache.

        .. versionchanged:: 1.3
            Allow disabling the message cache and change the default size to ``1000``.
    loop: Optional[:class:`asyncio.AbstractEventLoop`]
        The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.
        Defaults to ``None``, in which case the default event loop is used via
        :func:`asyncio.get_event_loop()`.
    connector: Optional[:class:`aiohttp.BaseConnector`]
        The connector to use for connection pooling.
    proxy: Optional[:class:`str`]
        Proxy URL.
    proxy_auth: Optional[:class:`aiohttp.BasicAuth`]
        An object that represents proxy HTTP Basic Authorization.
    shard_id: Optional[:class:`int`]
        Integer starting at ``0`` and less than :attr:`.shard_count`.
    shard_count: Optional[:class:`int`]
        The total number of shards.
    intents: :class:`Intents`
        The intents that you want to enable for the session. This is a way of
        disabling and enabling certain gateway events from triggering and being sent.
        If not given, defaults to a regularly constructed :class:`Intents` class.

        .. versionadded:: 1.5
    member_cache_flags: :class:`MemberCacheFlags`
        Allows for finer control over how the library caches members.
        If not given, defaults to cache as much as possible with the
        currently selected intents.

        .. versionadded:: 1.5
    chunk_guilds_at_startup: :class:`bool`
        Indicates if :func:`.on_ready` should be delayed to chunk all guilds
        at start-up if necessary. This operation is incredibly slow for large
        amounts of guilds. The default is ``True`` if :attr:`Intents.members`
        is ``True``.

        .. versionadded:: 1.5
    status: Optional[:class:`.Status`]
        A status to start your presence with upon logging on to Discord.
    activity: Optional[:class:`.BaseActivity`]
        An activity to start your presence with upon logging on to Discord.
    allowed_mentions: Optional[:class:`AllowedMentions`]
        Control how the client handles mentions by default on every message sent.

        .. versionadded:: 1.4
    heartbeat_timeout: :class:`float`
        The maximum numbers of seconds before timing out and restarting the
        WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if
        processing the initial packets take too long to the point of disconnecting
        you. The default timeout is 60 seconds.
    guild_ready_timeout: :class:`float`
        The maximum number of seconds to wait for the GUILD_CREATE stream to end before
        preparing the member cache and firing READY. The default timeout is 2 seconds.

        .. versionadded:: 1.4
    assume_unsync_clock: :class:`bool`
        Whether to assume the system clock is unsynced. This applies to the ratelimit handling
        code. If this is set to ``True``, the default, then the library uses the time to reset
        a rate limit bucket given by Discord. If this is ``False`` then your system clock is
        used to calculate how long to sleep for. If this is set to ``False`` it is recommended to
        sync your system clock to Google's NTP server.

        .. versionadded:: 1.3
    enable_debug_events: :class:`bool`
        Whether to enable events that are useful only for debugging gateway related information.

        Right now this involves :func:`on_socket_raw_receive` and :func:`on_socket_raw_send`. If
        this is ``False`` then those events will not be dispatched (due to performance considerations).
        To enable these events, this must be set to ``True``. Defaults to ``False``.

        .. versionadded:: 2.0
    application_command_guild_ids: Optional[List[:class:`int`]]
        The IDs of the guilds to upload all application commands to that do not have guild IDs set.
        It is recommended to set this while testing to speed up the registering of the commands.

        .. versionadded:: 2.0
    register_application_commands_at_startup: :class:`bool`
        Whether :meth:`register_application_commands` should be called in :meth:`login`.
        It is recommended to set this to ``False`` when the application commands
        added to the client are the same (having the exact same name and options) as the previous
        time they were added. Defaults to ``True``.

        .. note::

            If this is set to ``True``, :meth:`register_application_commands` will be created as a task,
            which means that the client may connect to the gateway before all application commands are registered.
            :func:`on_ready` and :meth:`wait_until_ready` will be delayed to wait for
            :meth:`Client.register_application_commands` to finish, regardless of whether an error was raised in it or not.

        .. versionadded:: 2.0

    Attributes
    -----------
    ws
        The websocket gateway the client is currently connected to. Could be ``None``.
    loop: :class:`asyncio.AbstractEventLoop`
        The event loop that the client uses for asynchronous operations.
    """
    def __init__(
        self,
        *,
        loop: Optional[asyncio.AbstractEventLoop] = None,
        **options: Any,
    ):
        # self.ws is set in the connect method
        self.ws: DiscordWebSocket = None  # type: ignore
        self.loop: asyncio.AbstractEventLoop = asyncio.get_event_loop() if loop is None else loop
        self._listeners: Dict[str, List[Tuple[asyncio.Future, Callable[..., bool]]]] = {}
        self.shard_id: Optional[int] = options.get('shard_id')
        self.shard_count: Optional[int] = options.get('shard_count')
        self.owner_id: Optional[int] = options.get('owner_id')
        self.owner_ids: Optional[collections.abc.Collection[int]] = options.get('owner_ids', set())
        self.application_command_guild_ids: Optional[List[int]] = options.get('application_command_guild_ids')
        self.extra_events: Dict[str, List[CoroFunc]] = {}
        self.register_application_commands_at_startup: bool = options.get('register_application_commands_at_startup', True)

        if self.owner_id and self.owner_ids:
            raise TypeError('Both owner_id and owner_ids are set.')

        if self.owner_ids and not isinstance(self.owner_ids, collections.abc.Collection):
            raise TypeError(f'owner_ids must be a collection not {self.owner_ids.__class__!r}')

        connector: Optional[aiohttp.BaseConnector] = options.pop('connector', None)
        proxy: Optional[str] = options.pop('proxy', None)
        proxy_auth: Optional[aiohttp.BasicAuth] = options.pop('proxy_auth', None)
        unsync_clock: bool = options.pop('assume_unsync_clock', True)
        self.http: HTTPClient = HTTPClient(connector, proxy=proxy, proxy_auth=proxy_auth, unsync_clock=unsync_clock, loop=self.loop)

        self._handlers: Dict[str, Callable[..., None]] = {
            'ready': self._handle_ready
        }

        self._hooks: Dict[str, Callable[..., Coroutine[Any, Any, None]]] = {
            'before_identify': self._call_before_identify_hook
        }

        self._enable_debug_events: bool = options.pop('enable_debug_events', False)
        self._connection: ConnectionState = self._get_state(**options)
        self._connection.shard_count = self.shard_count
        self._closed: bool = False
        self._ready: asyncio.Event = asyncio.Event()
        self._connection._get_websocket = self._get_websocket
        self._connection._get_client = lambda: self
        self._application_commands: Dict[ApplicationCommandKey, ApplicationCommand] = {}
        self._application_command_checks: List[Check] = []
        self.__extensions: Dict[str, types.ModuleType] = {}
        self.__cogs: Dict[str, Cog] = {}

        if VoiceClient.warn_nacl:
            VoiceClient.warn_nacl = False
            _log.warning("PyNaCl is not installed, voice will NOT be supported")

    # internals

    def _get_websocket(self, guild_id: Optional[int] = None, *, shard_id: Optional[int] = None) -> DiscordWebSocket:
        return self.ws

    def _get_state(self, **options: Any) -> ConnectionState:
        return ConnectionState(dispatch=self.dispatch, handlers=self._handlers,
                               hooks=self._hooks, http=self.http, loop=self.loop, **options)

    def _handle_ready(self) -> None:
        self._ready.set()

    @property
    def latency(self) -> float:
        """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.

        This could be referred to as the Discord WebSocket protocol latency.
        """
        ws = self.ws
        return float('nan') if not ws else ws.latency

    def is_ws_ratelimited(self) -> bool:
        """:class:`bool`: Whether the websocket is currently rate limited.

        This can be useful to know when deciding whether you should query members
        using HTTP or via the gateway.

        .. versionadded:: 1.6
        """
        if self.ws:
            return self.ws.is_ratelimited()
        return False

    @property
    def user(self) -> Optional[ClientUser]:
        """Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in."""
        return self._connection.user

    @property
    def guilds(self) -> List[Guild]:
        """List[:class:`.Guild`]: The guilds that the connected client is a member of."""
        return self._connection.guilds

    @property
    def emojis(self) -> List[Emoji]:
        """List[:class:`.Emoji`]: The emojis that the connected client has."""
        return self._connection.emojis

    @property
    def stickers(self) -> List[GuildSticker]:
        """List[:class:`.GuildSticker`]: The stickers that the connected client has.

        .. versionadded:: 2.0
        """
        return self._connection.stickers

    @property
    def cached_messages(self) -> Sequence[Message]:
        """Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached.

        .. versionadded:: 1.1
        """
        return utils.SequenceProxy(self._connection._messages or [])

    @property
    def private_channels(self) -> List[PrivateChannel]:
        """List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on.

        .. note::

            This returns only up to 128 most recent private channels due to an internal working
            on how Discord deals with private channels.
        """
        return self._connection.private_channels

    @property
    def voice_clients(self) -> List[VoiceProtocol]:
        """List[:class:`.VoiceProtocol`]: Represents a list of voice connections.

        These are usually :class:`.VoiceClient` instances.
        """
        return self._connection.voice_clients

    @property
    def application_id(self) -> Optional[int]:
        """Optional[:class:`int`]: The client's application ID.

        If this is not passed via ``__init__`` then this is retrieved
        through the gateway when an event contains the data. Usually
        after :func:`~discord.on_connect` is called.
        
        .. versionadded:: 2.0
        """
        return self._connection.application_id

    @property
    def application_flags(self) -> ApplicationFlags:
        """:class:`~discord.ApplicationFlags`: The client's application flags.

        .. versionadded:: 2.0
        """
        return self._connection.application_flags

    def is_ready(self) -> bool:
        """:class:`bool`: Specifies if the client's internal cache is ready for use."""
        return self._ready.is_set()

    async def _run_event(self, coro: Callable[..., Coroutine[Any, Any, Any]], event_name: str, *args: Any, **kwargs: Any) -> None:
        try:
            await coro(*args, **kwargs)
        except asyncio.CancelledError:
            pass
        except Exception:
            try:
                await self.on_error(event_name, *args, **kwargs)
            except asyncio.CancelledError:
                pass

    def _schedule_event(self, coro: Callable[..., Coroutine[Any, Any, Any]], event_name: str, *args: Any, **kwargs: Any) -> asyncio.Task:
        wrapped = self._run_event(coro, event_name, *args, **kwargs)
        # Schedules the task
        return asyncio.create_task(wrapped, name=f'discord.py: {event_name}')

    def dispatch(self, event_name: str, *args: Any, **kwargs: Any) -> None:
        _log.debug('Dispatching event %s', event_name)
        method = 'on_' + event_name

        listeners = self._listeners.get(event_name)
        if listeners:
            removed = []
            for i, (future, condition) in enumerate(listeners):
                if future.cancelled():
                    removed.append(i)
                    continue

                try:
                    result = condition(*args)
                except Exception as exc:
                    future.set_exception(exc)
                    removed.append(i)
                else:
                    if result:
                        if len(args) == 0:
                            future.set_result(None)
                        elif len(args) == 1:
                            future.set_result(args[0])
                        else:
                            future.set_result(args)
                        removed.append(i)

            if len(removed) == len(listeners):
                self._listeners.pop(event_name)
            else:
                for idx in reversed(removed):
                    del listeners[idx]

        try:
            coro = getattr(self, method)
        except AttributeError:
            pass
        else:
            self._schedule_event(coro, method, *args, **kwargs)

        for event in self.extra_events.get(method, []):
            self._schedule_event(event, method, *args, **kwargs)

    async def on_error(self, event_method: str, *args: Any, **kwargs: Any) -> None:
        """|coro|

        The default error handler provided by the client.

        By default this prints to :data:`sys.stderr` however it could be
        overridden to have a different implementation.
        Check :func:`~discord.on_error` for more details.
        """
        print(f'Ignoring exception in {event_method}', file=sys.stderr)
        traceback.print_exc()

    async def on_application_command_error(
        self, response: Union[SlashCommandResponse[Any], MessageCommandResponse[Any], UserCommandResponse[Any]], exception: Exception
    ) -> None:
        """|coro|

        The default application command error handler provided by the client.

        By default this prints to :data:`sys.stderr` however it could be
        overridden to have a different implementation.
        Check :func:`~discord.on_application_command_error` for more details.
        """
        print(f'Ignoring exception in application command {response.command}:', file=sys.stderr)
        traceback.print_exception(type(exception), exception, exception.__traceback__, file=sys.stderr)

    # hooks

    async def _call_before_identify_hook(self, shard_id: Optional[int], *, initial: bool = False) -> None:
        # This hook is an internal hook that actually calls the public one.
        # It allows the library to have its own hook without stepping on the
        # toes of those who need to override their own hook.
        await self.before_identify_hook(shard_id, initial=initial)

    async def before_identify_hook(self, shard_id: Optional[int], *, initial: bool = False) -> None:
        """|coro|

        A hook that is called before IDENTIFYing a session. This is useful
        if you wish to have more control over the synchronization of multiple
        IDENTIFYing clients.

        The default implementation sleeps for 5 seconds.

        .. versionadded:: 1.4

        Parameters
        ------------
        shard_id: :class:`int`
            The shard ID that requested being IDENTIFY'd
        initial: :class:`bool`
            Whether this IDENTIFY is the first initial IDENTIFY.
        """

        if not initial:
            await asyncio.sleep(5.0)

    # login state management

    async def login(self, token: str) -> None:
        """|coro|

        Logs in the client with the specified credentials.


        Parameters
        -----------
        token: :class:`str`
            The authentication token. Do not prefix this token with
            anything as the library will do it for you.

        Raises
        ------
        :exc:`.LoginFailure`
            The wrong credentials are passed.
        :exc:`.HTTPException`
            An unknown HTTP related error occurred,
            usually when it isn't 200 or the known incorrect credentials
            passing status code.
        """

        _log.info('logging in using static token')

        data = await self.http.static_login(token.strip())
        self._connection.user = ClientUser(state=self._connection, data=data)

        if self.register_application_commands_at_startup:
            self._connection._application_command_task = asyncio.create_task(
                self._connection._register_application_commands(), name='discord-register-application-commands'
            )

    async def connect(self, *, reconnect: bool = True) -> None:
        """|coro|

        Creates a websocket connection and lets the websocket listen
        to messages from Discord. This is a loop that runs the entire
        event system and miscellaneous aspects of the library. Control
        is not resumed until the WebSocket connection is terminated.

        Parameters
        -----------
        reconnect: :class:`bool`
            If we should attempt reconnecting, either due to internet
            failure or a specific failure on Discord's part. Certain
            disconnects that lead to bad state will not be handled (such as
            invalid sharding payloads or bad tokens).

        Raises
        -------
        :exc:`.GatewayNotFound`
            If the gateway to connect to Discord is not found. Usually if this
            is thrown then there is a Discord API outage.
        :exc:`.ConnectionClosed`
            The websocket connection has been terminated.
        """

        backoff = ExponentialBackoff()
        ws_params = {
            'initial': True,
            'shard_id': self.shard_id,
        }
        while not self.is_closed():
            try:
                coro = DiscordWebSocket.from_client(self, **ws_params)
                self.ws = await asyncio.wait_for(coro, timeout=60.0)
                ws_params['initial'] = False
                while True:
                    await self.ws.poll_event()
            except ReconnectWebSocket as e:
                _log.info('Got a request to %s the websocket.', e.op)
                self.dispatch('disconnect')
                ws_params.update(sequence=self.ws.sequence, resume=e.resume, session=self.ws.session_id)
                continue
            except (OSError,
                    HTTPException,
                    GatewayNotFound,
                    ConnectionClosed,
                    aiohttp.ClientError,
                    asyncio.TimeoutError) as exc:

                self.dispatch('disconnect')
                if not reconnect:
                    await self.close()
                    if isinstance(exc, ConnectionClosed) and exc.code == 1000:
                        # clean close, don't re-raise this
                        return
                    raise

                if self.is_closed():
                    return

                # If we get connection reset by peer then try to RESUME
                if isinstance(exc, OSError) and exc.errno in (54, 10054):
                    ws_params.update(sequence=self.ws.sequence, initial=False, resume=True, session=self.ws.session_id)
                    continue

                # We should only get this when an unhandled close code happens,
                # such as a clean disconnect (1000) or a bad state (bad token, no sharding, etc)
                # sometimes, discord sends us 1000 for unknown reasons so we should reconnect
                # regardless and rely on is_closed instead
                if isinstance(exc, ConnectionClosed):
                    if exc.code == 4014:
                        raise PrivilegedIntentsRequired(exc.shard_id) from None
                    if exc.code != 1000:
                        await self.close()
                        raise

                retry = backoff.delay()
                _log.exception("Attempting a reconnect in %.2fs", retry)
                await asyncio.sleep(retry)
                # Always try to RESUME the connection
                # If the connection is not RESUME-able then the gateway will invalidate the session.
                # This is apparently what the official Discord client does.
                ws_params.update(sequence=self.ws.sequence, resume=True, session=self.ws.session_id)

    async def close(self) -> None:
        """|coro|

        Closes the connection to Discord.
        """
        if self._closed:
            return

        self._closed = True

        for extension in tuple(self.__extensions):
            try:
                self.unload_extension(extension)
            except Exception:
                pass
        
        for cog in tuple(self.__cogs):
            try:
                self.remove_cog(cog)
            except Exception:
                pass

        for voice in self.voice_clients:
            try:
                await voice.disconnect(force=True)
            except Exception:
                # if an error happens during disconnects, disregard it.
                pass

        if self.ws is not None and self.ws.open:
            await self.ws.close(code=1000)

        await self.http.close()
        self._ready.clear()

    def clear(self) -> None:
        """Clears the internal state of the bot.

        After this, the bot can be considered "re-opened", i.e. :meth:`is_closed`
        and :meth:`is_ready` both return ``False`` along with the bot's internal
        cache cleared.
        """
        self._closed = False
        self._ready.clear()
        self._connection.clear()
        self.http.recreate()

    async def start(self, token: str, *, reconnect: bool = True) -> None:
        """|coro|

        A shorthand coroutine for :meth:`login` + :meth:`connect`.

        Raises
        -------
        TypeError
            An unexpected keyword argument was received.
        """
        await self.login(token)
        await self.connect(reconnect=reconnect)

    def run(self, token: str, *, reconnect: bool = True) -> None:
        """A blocking call that abstracts away the event loop
        initialisation from you.

        If you want more control over the event loop then this
        function should not be used. Use :meth:`start` coroutine
        or :meth:`connect` + :meth:`login`.

        Roughly Equivalent to: ::

            try:
                loop.run_until_complete(start(*args, **kwargs))
            except KeyboardInterrupt:
                loop.run_until_complete(close())
                # cancel all tasks lingering
            finally:
                loop.close()

        .. warning::

            This function must be the last function to call due to the fact that it
            is blocking. That means that registration of events or anything being
            called after this function call will not execute until it returns.
        """
        loop = self.loop

        try:
            loop.add_signal_handler(signal.SIGINT, lambda: loop.stop())
            loop.add_signal_handler(signal.SIGTERM, lambda: loop.stop())
        except NotImplementedError:
            pass

        async def runner():
            try:
                await self.start(token, reconnect=reconnect)
            finally:
                if not self.is_closed():
                    await self.close()

        def stop_loop_on_completion(f):
            loop.stop()

        future = asyncio.ensure_future(runner(), loop=loop)
        future.add_done_callback(stop_loop_on_completion)
        try:
            loop.run_forever()
        except KeyboardInterrupt:
            _log.info('Received signal to terminate bot and event loop.')
        finally:
            future.remove_done_callback(stop_loop_on_completion)
            _log.info('Cleaning up tasks.')
            _cleanup_loop(loop)

        if not future.cancelled():
            try:
                return future.result()
            except KeyboardInterrupt:
                # I am unsure why this gets raised here but suppress it anyway
                return None

    # properties

    def is_closed(self) -> bool:
        """:class:`bool`: Indicates if the websocket connection is closed."""
        return self._closed

    @property
    def activity(self) -> Optional[ActivityTypes]:
        """Optional[:class:`.BaseActivity`]: The activity being used upon
        logging in.
        """
        return create_activity(self._connection._activity, self._connection)

    @activity.setter
    def activity(self, value: Optional[ActivityTypes]) -> None:
        if value is None:
            self._connection._activity = None
        elif isinstance(value, BaseActivity):
            # ConnectionState._activity is typehinted as ActivityPayload, we're passing Dict[str, Any]
            self._connection._activity = value.to_dict() # type: ignore
        else:
            raise TypeError('activity must derive from BaseActivity.')
    
    @property
    def status(self) -> Status:
        """:class:`.Status`:
        The status being used upon logging on to Discord.

        .. versionadded: 2.0
        """
        if self._connection._status in set(state.value for state in Status):
            return Status(self._connection._status)
        return Status.online

    @status.setter
    def status(self, value: Status) -> None:
        if value is Status.offline:
            self._connection._status = 'invisible'
        elif isinstance(value, Status):
            self._connection._status = str(value)
        else:
            raise TypeError('status must derive from Status.')

    @property
    def allowed_mentions(self) -> Optional[AllowedMentions]:
        """Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration.

        .. versionadded:: 1.4
        """
        return self._connection.allowed_mentions

    @allowed_mentions.setter
    def allowed_mentions(self, value: Optional[AllowedMentions]) -> None:
        if value is None or isinstance(value, AllowedMentions):
            self._connection.allowed_mentions = value
        else:
            raise TypeError(f'allowed_mentions must be AllowedMentions not {value.__class__!r}')

    @property
    def intents(self) -> Intents:
        """:class:`~discord.Intents`: The intents configured for this connection.

        .. versionadded:: 1.5
        """
        return self._connection.intents

    # helpers/getters

    @property
    def users(self) -> List[User]:
        """List[:class:`~discord.User`]: Returns a list of all the users the bot can see."""
        return list(self._connection._users.values())

    def get_channel(self, id: int, /) -> Optional[Union[GuildChannel, Thread, PrivateChannel]]:
        """Returns a channel or thread with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[Union[:class:`.abc.GuildChannel`, :class:`.Thread`, :class:`.abc.PrivateChannel`]]
            The returned channel or ``None`` if not found.
        """
        return self._connection.get_channel(id)

    def get_partial_messageable(self, id: int, *, type: Optional[ChannelType] = None) -> PartialMessageable:
        """Returns a partial messageable with the given channel ID.

        This is useful if you have a channel_id but don't want to do an API call
        to send messages to it.
        
        .. versionadded:: 2.0

        Parameters
        -----------
        id: :class:`int`
            The channel ID to create a partial messageable for.
        type: Optional[:class:`.ChannelType`]
            The underlying channel type for the partial messageable.

        Returns
        --------
        :class:`.PartialMessageable`
            The partial messageable
        """
        return PartialMessageable(state=self._connection, id=id, type=type)

    def get_stage_instance(self, id: int, /) -> Optional[StageInstance]:
        """Returns a stage instance with the given stage channel ID.

        .. versionadded:: 2.0

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`.StageInstance`]
            The returns stage instance of ``None`` if not found.
        """
        from .channel import StageChannel

        channel = self._connection.get_channel(id)

        if isinstance(channel, StageChannel):
            return channel.instance

    def get_guild(self, id: int, /) -> Optional[Guild]:
        """Returns a guild with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`.Guild`]
            The guild or ``None`` if not found.
        """
        return self._connection._get_guild(id)

    def get_user(self, id: int, /) -> Optional[User]:
        """Returns a user with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`~discord.User`]
            The user or ``None`` if not found.
        """
        return self._connection.get_user(id)

    def get_emoji(self, id: int, /) -> Optional[Emoji]:
        """Returns an emoji with the given ID.

        Parameters
        -----------
        id: :class:`int`
            The ID to search for.

        Returns
        --------
        Optional[:class:`.Emoji`]
            The custom emoji or ``None`` if not found.
        """
        return self._connection.get_emoji(id)

    def get_sticker(self, id: int, /) -> Optional[GuildSticker]:
        """Returns a guild sticker with the given ID.

        .. versionadded:: 2.0

        .. note::

            To retrieve standard stickers, use :meth:`.fetch_sticker`.
            or :meth:`.fetch_premium_sticker_packs`.

        Returns
        --------
        Optional[:class:`.GuildSticker`]
            The sticker or ``None`` if not found.
        """
        return self._connection.get_sticker(id)

    def get_all_channels(self) -> Generator[GuildChannel, None, None]:
        """A generator that retrieves every :class:`.abc.GuildChannel` the client can 'access'.

        This is equivalent to: ::

            for guild in client.guilds:
                for channel in guild.channels:
                    yield channel

        .. note::

            Just because you receive a :class:`.abc.GuildChannel` does not mean that
            you can communicate in said channel. :meth:`.abc.GuildChannel.permissions_for` should
            be used for that.

        Yields
        ------
        :class:`.abc.GuildChannel`
            A channel the client can 'access'.
        """

        for guild in self.guilds:
            yield from guild.channels

    def get_all_members(self) -> Generator[Member, None, None]:
        """Returns a generator with every :class:`.Member` the client can see.

        This is equivalent to: ::

            for guild in client.guilds:
                for member in guild.members:
                    yield member

        Yields
        ------
        :class:`.Member`
            A member the client can see.
        """
        for guild in self.guilds:
            yield from guild.members

    # listeners/waiters

    async def wait_until_ready(self) -> None:
        """|coro|

        Waits until the client's internal cache is all ready.
        """
        await self._ready.wait()

    def wait_for(
        self,
        event: str,
        *,
        check: Optional[Callable[..., bool]] = None,
        timeout: Optional[float] = None,
    ) -> Any:
        """|coro|

        Waits for a WebSocket event to be dispatched.

        This could be used to wait for a user to reply to a message,
        or to react to a message, or to edit a message in a self-contained
        way.

        The ``timeout`` parameter is passed onto :func:`asyncio.wait_for`. By default,
        it does not timeout. Note that this does propagate the
        :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for
        ease of use.

        In case the event returns multiple arguments, a :class:`tuple` containing those
        arguments is returned instead. Please check the
        :ref:`documentation <discord-api-events>` for a list of events and their
        parameters.

        This function returns the **first event that meets the requirements**.

        Examples
        ---------

        Waiting for a user reply: ::

            @client.event
            async def on_message(message):
                if message.content.startswith('$greet'):
                    channel = message.channel
                    await channel.send('Say hello!')

                    def check(m):
                        return m.content == 'hello' and m.channel == channel

                    msg = await client.wait_for('message', check=check)
                    await channel.send(f'Hello {msg.author}!')

        Waiting for a thumbs up reaction from the message author: ::

            @client.event
            async def on_message(message):
                if message.content.startswith('$thumb'):
                    channel = message.channel
                    await channel.send('Send me that \N{THUMBS UP SIGN} reaction, mate')

                    def check(reaction, user):
                        return user == message.author and str(reaction.emoji) == '\N{THUMBS UP SIGN}'

                    try:
                        reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
                    except asyncio.TimeoutError:
                        await channel.send('\N{THUMBS DOWN SIGN}')
                    else:
                        await channel.send('\N{THUMBS UP SIGN}')


        Parameters
        ------------
        event: :class:`str`
            The event name, similar to the :ref:`event reference <discord-api-events>`,
            but without the ``on_`` prefix, to wait for.
        check: Optional[Callable[..., :class:`bool`]]
            A predicate to check what to wait for. The arguments must meet the
            parameters of the event being waited for.
        timeout: Optional[:class:`float`]
            The number of seconds to wait before timing out and raising
            :exc:`asyncio.TimeoutError`.

        Raises
        -------
        asyncio.TimeoutError
            If a timeout is provided and it was reached.

        Returns
        --------
        Any
            Returns no arguments, a single argument, or a :class:`tuple` of multiple
            arguments that mirrors the parameters passed in the
            :ref:`event reference <discord-api-events>`.
        """

        future = self.loop.create_future()
        if check is None:
            def _check(*args):
                return True
            check = _check

        ev = event.lower()
        try:
            listeners = self._listeners[ev]
        except KeyError:
            listeners = []
            self._listeners[ev] = listeners

        listeners.append((future, check))
        return asyncio.wait_for(future, timeout)

    # event registration

    def event(self, coro: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, Coroutine[Any, Any, T]]:
        """A decorator that registers an event to listen to.

        You can find more info about the events on the :ref:`documentation below <discord-api-events>`.

        The events must be a :ref:`coroutine <coroutine>`, if not, :exc:`TypeError` is raised.

        Example
        ---------

        .. code-block:: python3

            @client.event
            async def on_ready():
                print('Ready!')

        Raises
        --------
        TypeError
            The coroutine passed is not actually a coroutine.
        """

        if not asyncio.iscoroutinefunction(coro):
            raise TypeError('event registered must be a coroutine function')

        setattr(self, coro.__name__, coro)
        _log.debug('%s has successfully been registered as an event', coro.__name__)
        return coro

    async def change_presence(
        self,
        *,
        activity: Optional[BaseActivity] = None,
        status: Optional[Status] = None,
    ) -> None:
        """|coro|

        Changes the client's presence.

        Example
        ---------

        .. code-block:: python3

            game = discord.Game("with the API")
            await client.change_presence(status=discord.Status.idle, activity=game)

        .. versionchanged:: 2.0
            Removed the ``afk`` keyword-only parameter.

        Parameters
        ----------
        activity: Optional[:class:`.BaseActivity`]
            The activity being done. ``None`` if no currently active activity is done.
        status: Optional[:class:`.Status`]
            Indicates what status to change to. If ``None``, then
            :attr:`.Status.online` is used.

        Raises
        ------
        :exc:`.InvalidArgument`
            If the ``activity`` parameter is not the proper type.
        """

        if status is None:
            status_str = 'online'
            status = Status.online
        elif status is Status.offline:
            status_str = 'invisible'
            status = Status.offline
        else:
            status_str = str(status)

        await self.ws.change_presence(activity=activity, status=status_str)

        for guild in self._connection.guilds:
            me = guild.me
            if me is None:
                continue

            if activity is not None:
                me.activities = (activity,)  # type: ignore
            else:
                me.activities = ()

            me.status = status

    # Guild stuff

    def fetch_guilds(
        self,
        *,
        limit: Optional[int] = 100,
        before: SnowflakeTime = None,
        after: SnowflakeTime = None
    ) -> GuildIterator:
        """Retrieves an :class:`.AsyncIterator` that enables receiving your guilds.

        .. note::

            Using this, you will only receive :attr:`.Guild.owner`, :attr:`.Guild.icon`,
            :attr:`.Guild.id`, and :attr:`.Guild.name` per :class:`.Guild`.

        .. note::

            This method is an API call. For general usage, consider :attr:`guilds` instead.

        Examples
        ---------

        Usage ::

            async for guild in client.fetch_guilds(limit=150):
                print(guild.name)

        Flattening into a list ::

            guilds = await client.fetch_guilds(limit=150).flatten()
            # guilds is now a list of Guild...

        All parameters are optional.

        Parameters
        -----------
        limit: Optional[:class:`int`]
            The number of guilds to retrieve.
            If ``None``, it retrieves every guild you have access to. Note, however,
            that this would make it a slow operation.
            Defaults to ``100``.
        before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
            Retrieves guilds before this date or object.
            If a datetime is provided, it is recommended to use a UTC aware datetime.
            If the datetime is naive, it is assumed to be local time.
        after: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]
            Retrieve guilds after this date or object.
            If a datetime is provided, it is recommended to use a UTC aware datetime.
            If the datetime is naive, it is assumed to be local time.

        Raises
        ------
        :exc:`.HTTPException`
            Getting the guilds failed.

        Yields
        --------
        :class:`.Guild`
            The guild with the guild data parsed.
        """
        return GuildIterator(self, limit=limit, before=before, after=after)

    async def fetch_template(self, code: Union[Template, str]) -> Template:
        """|coro|

        Gets a :class:`.Template` from a discord.new URL or code.

        Parameters
        -----------
        code: Union[:class:`.Template`, :class:`str`]
            The Discord Template Code or URL (must be a discord.new URL).

        Raises
        -------
        :exc:`.NotFound`
            The template is invalid.
        :exc:`.HTTPException`
            Getting the template failed.

        Returns
        --------
        :class:`.Template`
            The template from the URL/code.
        """
        code = utils.resolve_template(code)
        data = await self.http.get_template(code)
        return Template(data=data, state=self._connection) # type: ignore

    async def fetch_guild(self, guild_id: int, /) -> Guild:
        """|coro|

        Retrieves a :class:`.Guild` from an ID.

        .. note::

            Using this, you will **not** receive :attr:`.Guild.channels`, :attr:`.Guild.members`,
            :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.

        .. note::

            This method is an API call. For general usage, consider :meth:`get_guild` instead.

        Parameters
        -----------
        guild_id: :class:`int`
            The guild's ID to fetch from.

        Raises
        ------
        :exc:`.Forbidden`
            You do not have access to the guild.
        :exc:`.HTTPException`
            Getting the guild failed.

        Returns
        --------
        :class:`.Guild`
            The guild from the ID.
        """
        data = await self.http.get_guild(guild_id)
        return Guild(data=data, state=self._connection)

    async def create_guild(
        self,
        *,
        name: str,
        region: Union[VoiceRegion, str] = VoiceRegion.us_west,
        icon: bytes = MISSING,
        code: str = MISSING,
    ) -> Guild:
        """|coro|

        Creates a :class:`.Guild`.

        Bot accounts in more than 10 guilds are not allowed to create guilds.

        Parameters
        ----------
        name: :class:`str`
            The name of the guild.
        region: :class:`.VoiceRegion`
            The region for the voice communication server.
            Defaults to :attr:`.VoiceRegion.us_west`.
        icon: Optional[:class:`bytes`]
            The :term:`py:bytes-like object` representing the icon. See :meth:`.ClientUser.edit`
            for more details on what is expected.
        code: :class:`str`
            The code for a template to create the guild with.

            .. versionadded:: 1.4

        Raises
        ------
        :exc:`.HTTPException`
            Guild creation failed.
        :exc:`.InvalidArgument`
            Invalid icon image format given. Must be PNG or JPG.

        Returns
        -------
        :class:`.Guild`
            The guild created. This is not the same guild that is
            added to cache.
        """
        if icon is not MISSING:
            icon_base64 = utils._bytes_to_base64_data(icon)
        else:
            icon_base64 = None

        region_value = str(region)

        if code:
            data = await self.http.create_from_template(code, name, region_value, icon_base64)
        else:
            data = await self.http.create_guild(name, region_value, icon_base64)
        return Guild(data=data, state=self._connection)

    async def fetch_stage_instance(self, channel_id: int, /) -> StageInstance:
        """|coro|

        Gets a :class:`.StageInstance` for a stage channel id.

        .. versionadded:: 2.0

        Parameters
        -----------
        channel_id: :class:`int`
            The stage channel ID.

        Raises
        -------
        :exc:`.NotFound`
            The stage instance or channel could not be found.
        :exc:`.HTTPException`
            Getting the stage instance failed.

        Returns
        --------
        :class:`.StageInstance`
            The stage instance from the stage channel ID.
        """
        data = await self.http.get_stage_instance(channel_id)
        guild = self.get_guild(int(data['guild_id']))
        return StageInstance(guild=guild, state=self._connection, data=data)  # type: ignore

    # Invite management

    async def fetch_invite(
        self, url: Union[Invite, str], *, with_counts: bool = True, with_expiration: bool = True, scheduled_event_id: Optional[int] = None
    ) -> Invite:
        """|coro|

        Gets an :class:`.Invite` from a discord.gg URL or ID.

        .. note::

            If the invite is for a guild you have not joined, the guild and channel
            attributes of the returned :class:`.Invite` will be :class:`.PartialInviteGuild` and
            :class:`.PartialInviteChannel` respectively.

        Parameters
        -----------
        url: Union[:class:`.Invite`, :class:`str`]
            The Discord invite ID or URL (must be a discord.gg URL).
        with_counts: :class:`bool`
            Whether to include count information in the invite. This fills the
            :attr:`.Invite.approximate_member_count` and :attr:`.Invite.approximate_presence_count`
            fields.
        with_expiration: :class:`bool`
            Whether to include the expiration date of the invite. This fills the
            :attr:`.Invite.expires_at` field.

            .. versionadded:: 2.0
        scheduled_event_id: Optional[:class:`int`]
            The ID of the scheduled event to include information about in the invite.
            This fills the :attr:`.Invite.scheduled_event` field. If the ID is invalid,
            the field will be ``None``.

        Raises
        -------
        :exc:`.NotFound`
            The invite has expired or is invalid.
        :exc:`.HTTPException`
            Getting the invite failed.

        Returns
        --------
        :class:`.Invite`
            The invite from the URL/ID.
        """

        invite_id = utils.resolve_invite(url)
        data = await self.http.get_invite(
            invite_id, with_counts=with_counts, with_expiration=with_expiration, scheduled_event_id=scheduled_event_id
        )
        return Invite.from_incomplete(state=self._connection, data=data)

    async def delete_invite(self, invite: Union[Invite, str]) -> None:
        """|coro|

        Revokes an :class:`.Invite`, URL, or ID to an invite.

        You must have the :attr:`~.Permissions.manage_channels` permission in
        the associated guild to do this.

        Parameters
        ----------
        invite: Union[:class:`.Invite`, :class:`str`]
            The invite to revoke.

        Raises
        -------
        :exc:`.Forbidden`
            You do not have permissions to revoke invites.
        :exc:`.NotFound`
            The invite is invalid or expired.
        :exc:`.HTTPException`
            Revoking the invite failed.
        """

        invite_id = utils.resolve_invite(invite)
        await self.http.delete_invite(invite_id)

    # Miscellaneous stuff

    async def fetch_widget(self, guild_id: int, /) -> Widget:
        """|coro|

        Gets a :class:`.Widget` from a guild ID.

        .. note::

            The guild must have the widget enabled to get this information.

        Parameters
        -----------
        guild_id: :class:`int`
            The ID of the guild.

        Raises
        -------
        :exc:`.Forbidden`
            The widget for this guild is disabled.
        :exc:`.HTTPException`
            Retrieving the widget failed.

        Returns
        --------
        :class:`.Widget`
            The guild's widget.
        """
        data = await self.http.get_widget(guild_id)

        return Widget(state=self._connection, data=data)

    async def application_info(self) -> AppInfo:
        """|coro|

        Retrieves the bot's application information.

        Raises
        -------
        :exc:`.HTTPException`
            Retrieving the information failed somehow.

        Returns
        --------
        :class:`.AppInfo`
            The bot's application information.
        """
        data = await self.http.application_info()
        if 'rpc_origins' not in data:
            data['rpc_origins'] = None
        return AppInfo(self._connection, data)

    async def fetch_user(self, user_id: int, /) -> User:
        """|coro|

        Retrieves a :class:`~discord.User` based on their ID.
        You do not have to share any guilds with the user to get this information,
        however many operations do require that you do.

        .. note::

            This method is an API call. If you have :attr:`discord.Intents.members` and member cache enabled, consider :meth:`get_user` instead.

        Parameters
        -----------
        user_id: :class:`int`
            The user's ID to fetch from.

        Raises
        -------
        :exc:`.NotFound`
            A user with this ID does not exist.
        :exc:`.HTTPException`
            Fetching the user failed.

        Returns
        --------
        :class:`~discord.User`
            The user you requested.
        """
        data = await self.http.get_user(user_id)
        return User(state=self._connection, data=data)

    async def fetch_channel(self, channel_id: int, /) -> Union[GuildChannel, PrivateChannel, Thread]:
        """|coro|

        Retrieves a :class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, or :class:`.Thread` with the specified ID.

        .. note::

            This method is an API call. For general usage, consider :meth:`get_channel` instead.

        .. versionadded:: 1.2

        Raises
        -------
        :exc:`.InvalidData`
            An unknown channel type was received from Discord.
        :exc:`.HTTPException`
            Retrieving the channel failed.
        :exc:`.NotFound`
            Invalid Channel ID.
        :exc:`.Forbidden`
            You do not have permission to fetch this channel.

        Returns
        --------
        Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, :class:`.Thread`]
            The channel from the ID.
        """
        data = await self.http.get_channel(channel_id)

        factory, ch_type = _threaded_channel_factory(data['type'])
        if factory is None:
            raise InvalidData('Unknown channel type {type} for channel ID {id}.'.format_map(data))

        if ch_type in (ChannelType.group, ChannelType.private):
            # the factory will be a DMChannel or GroupChannel here
            channel = factory(me=self.user, data=data, state=self._connection) # type: ignore
        else:
            # the factory can't be a DMChannel or GroupChannel here
            guild_id = int(data['guild_id']) # type: ignore
            guild = self.get_guild(guild_id) or Object(id=guild_id)
            # GuildChannels expect a Guild, we may be passing an Object
            channel = factory(guild=guild, state=self._connection, data=data) # type: ignore

        return channel

    async def fetch_webhook(self, webhook_id: int, /) -> Webhook:
        """|coro|

        Retrieves a :class:`.Webhook` with the specified ID.

        Raises
        --------
        :exc:`.HTTPException`
            Retrieving the webhook failed.
        :exc:`.NotFound`
            Invalid webhook ID.
        :exc:`.Forbidden`
            You do not have permission to fetch this webhook.

        Returns
        ---------
        :class:`.Webhook`
            The webhook you requested.
        """
        data = await self.http.get_webhook(webhook_id)
        return Webhook.from_state(data, state=self._connection)

    async def fetch_sticker(self, sticker_id: int, /) -> Union[StandardSticker, GuildSticker]:
        """|coro|

        Retrieves a :class:`.Sticker` with the specified ID.

        .. versionadded:: 2.0

        Raises
        --------
        :exc:`.HTTPException`
            Retrieving the sticker failed.
        :exc:`.NotFound`
            Invalid sticker ID.

        Returns
        --------
        Union[:class:`.StandardSticker`, :class:`.GuildSticker`]
            The sticker you requested.
        """
        data = await self.http.get_sticker(sticker_id)
        cls, _ = _sticker_factory(data['type'])  # type: ignore
        return cls(state=self._connection, data=data) # type: ignore

    async def fetch_premium_sticker_packs(self) -> List[StickerPack]:
        """|coro|

        Retrieves all available premium sticker packs.

        .. versionadded:: 2.0

        Raises
        -------
        :exc:`.HTTPException`
            Retrieving the sticker packs failed.

        Returns
        ---------
        List[:class:`.StickerPack`]
            All available premium sticker packs.
        """
        data = await self.http.list_premium_sticker_packs()
        return [StickerPack(state=self._connection, data=pack) for pack in data['sticker_packs']]

    async def create_dm(self, user: Snowflake) -> DMChannel:
        """|coro|

        Creates a :class:`.DMChannel` with this user.

        This should be rarely called, as this is done transparently for most
        people.

        .. versionadded:: 2.0

        Parameters
        -----------
        user: :class:`~discord.abc.Snowflake`
            The user to create a DM with.

        Returns
        -------
        :class:`.DMChannel`
            The channel that was created.
        """
        state = self._connection
        found = state._get_private_channel_by_user(user.id)
        if found:
            return found

        data = await state.http.start_private_message(user.id)
        return state.add_dm_channel(data)

    def add_view(self, view: View, *, message_id: Optional[int] = None) -> None:
        """Registers a :class:`~discord.ui.View` for persistent listening.

        This method should be used for when a view is comprised of components
        that last longer than the lifecycle of the program.
        
        .. versionadded:: 2.0

        Parameters
        ------------
        view: :class:`discord.ui.View`
            The view to register for dispatching.
        message_id: Optional[:class:`int`]
            The message ID that the view is attached to. This is currently used to
            refresh the view's state during message update events. If not given
            then message update events are not propagated for the view.

        Raises
        -------
        TypeError
            A view was not passed.
        ValueError
            The view is not persistent. A persistent view has no timeout
            and all their components have an explicitly provided custom_id.
        """

        if not isinstance(view, View):
            raise TypeError(f'expected an instance of View not {view.__class__!r}')

        if not view.is_persistent():
            raise ValueError('View is not persistent. Items need to have a custom_id set and View must have no timeout')

        self._connection.store_view(view, message_id)

    @property
    def persistent_views(self) -> Sequence[View]:
        """Sequence[:class:`.View`]: A sequence of persistent views added to the client.
        
        .. versionadded:: 2.0
        """
        return self._connection.persistent_views

    async def is_owner(self, user: Snowflake) -> bool:
        """|coro|

        Checks if a :class:`~discord.abc.Snowflake` is the owner of
        this bot.

        If an :attr:`owner_id` is not set, it is fetched automatically
        through the use of :meth:`~.Bot.application_info`.

        .. versionchanged:: 1.3
            The function also checks if the application is team-owned if
            :attr:`owner_ids` is not set.

        Parameters
        -----------
        user: :class:`.abc.Snowflake`
            The user to check for.

        Returns
        --------
        :class:`bool`
            Whether the user is the owner.
        """

        if self.owner_id:
            return user.id == self.owner_id
        elif self.owner_ids:
            return user.id in self.owner_ids
        else:
            app = await self.application_info()
            if app.team:
                self.owner_ids = ids = {m.id for m in app.team.members}
                return user.id in ids
            else:
                self.owner_id = owner_id = app.owner.id
                return user.id == owner_id

    # listener registration

    def add_listener(self, func: CoroFunc, name: str = MISSING) -> None:
        """The non decorator alternative to :meth:`.listen`.

        Parameters
        -----------
        func: :ref:`coroutine <coroutine>`
            The function to call.
        name: :class:`str`
            The name of the event to listen for. Defaults to ``func.__name__``.

        Example
        --------

        .. code-block:: python3

            async def on_ready(): pass
            async def my_message(message): pass

            bot.add_listener(on_ready)
            bot.add_listener(my_message, 'on_message')

        """
        name = func.__name__ if name is MISSING else name

        if not asyncio.iscoroutinefunction(func):
            raise TypeError('Listeners must be coroutines')

        if name in self.extra_events:
            self.extra_events[name].append(func)
        else:
            self.extra_events[name] = [func]

    def remove_listener(self, func: CoroFunc, name: str = MISSING) -> None:
        """Removes a listener from the pool of listeners.

        Parameters
        -----------
        func
            The function that was used as a listener to remove.
        name: :class:`str`
            The name of the event we want to remove. Defaults to
            ``func.__name__``.
        """

        name = func.__name__ if name is MISSING else name

        if name in self.extra_events:
            try:
                self.extra_events[name].remove(func)
            except ValueError:
                pass

    def listen(self, name: str = MISSING) -> Callable[[CFT], CFT]:
        """A decorator that registers another function as an external
        event listener. Basically this allows you to listen to multiple
        events from different places e.g. such as :func:`.on_ready`

        The functions being listened to must be a :ref:`coroutine <coroutine>`.

        Example
        --------

        .. code-block:: python3

            @client.listen()
            async def on_message(message):
                print('one')

            # in some other file...

            @client.listen('on_message')
            async def my_message(message):
                print('two')

        Would print one and two in an unspecified order.

        Raises
        -------
        TypeError
            The function being listened to is not a coroutine.
        """

        def decorator(func: CFT) -> CFT:
            self.add_listener(func, name)
            return func

        return decorator

    # cogs

    def add_cog(self, cog: Cog, *, override: bool = False) -> None:
        """Adds a "cog" client.

        A cog is a class that has its own event listeners and commands.

        .. versionchanged:: 2.0

            :exc:`.ClientException` is raised when a cog with the same name
            is already loaded.

        Parameters
        -----------
        cog: :class:`.Cog`
            The cog to register client.
        override: :class:`bool`
            If a previously loaded cog with the same name should be ejected
            instead of raising an error.

            .. versionadded:: 2.0

        Raises
        -------
        TypeError
            The cog does not inherit from :class:`.Cog`.
        CommandError
            An error happened during loading.
        .ClientException
            A cog with the same name is already loaded.
        """

        # circular import
        from .cog import Cog

        if not isinstance(cog, Cog):
            raise TypeError('cogs must derive from Cog')

        cog_name = cog.__cog_name__
        existing = self.__cogs.get(cog_name)

        if existing is not None:
            if not override:
                raise ClientException(f'Cog named {cog_name!r} already loaded')
            self.remove_cog(cog_name)

        cog = cog._inject(self)
        self.__cogs[cog_name] = cog

    def get_cog(self, name: str) -> Optional[Cog]:
        """Gets the cog instance requested.

        If the cog is not found, ``None`` is returned instead.

        Parameters
        -----------
        name: :class:`str`
            The name of the cog you are requesting.
            This is equivalent to the name passed via keyword
            argument in class creation or the class name if unspecified.

        Returns
        --------
        Optional[:class:`Cog`]
            The cog that was requested. If not found, returns ``None``.
        """
        return self.__cogs.get(name)

    def remove_cog(self, name: str) -> Optional[Cog]:
        """Removes a cog from the client and returns it.

        All registered commands and event listeners that the
        cog has registered will be removed as well.

        If no cog is found then this method has no effect.

        Parameters
        -----------
        name: :class:`str`
            The name of the cog to remove.

        Returns
        -------
        Optional[:class:`.Cog`]
            The cog that was removed. ``None`` if not found.
        """

        cog = self.__cogs.pop(name, None)
        if cog is None:
            return

        # circular import
        from .ext.commands.bot import Bot

        if isinstance(self, Bot):
            help_command = self._help_command
            if help_command and help_command.cog is cog:
                help_command.cog = None

        cog._eject(self)

        return cog

    @property
    def cogs(self) -> Mapping[str, Cog]:
        """Mapping[:class:`str`, :class:`Cog`]: A read-only mapping of cog name to cog."""
        return types.MappingProxyType(self.__cogs)

    # extensions

    def _remove_module_references(self, name: str) -> None:
        # find all references to the module
        # remove the cogs registered from the module
        for cogname, cog in self.__cogs.copy().items():
            if _is_submodule(name, cog.__module__):
                self.remove_cog(cogname)

        # circular imports
        from .ext.commands.bot import Bot
        from .ext.commands.core import GroupMixin

        # remove all the commands from the module
        if isinstance(self, Bot):
            for cmd in self.all_commands.copy().values():
                if cmd.module is not None and _is_submodule(name, cmd.module):
                    if isinstance(cmd, GroupMixin):
                        cmd.recursively_remove_all_commands()
                    self.remove_command(cmd.name)

        # remove all the listeners from the module
        for event_list in self.extra_events.copy().values():
            remove = []
            for index, event in enumerate(event_list):
                if event.__module__ is not None and _is_submodule(name, event.__module__):
                    remove.append(index)

            for index in reversed(remove):
                del event_list[index]

    def _call_module_finalizers(self, lib: types.ModuleType, key: str) -> None:
        try:
            func = getattr(lib, 'teardown')
        except AttributeError:
            pass
        else:
            try:
                func(self)
            except Exception:
                pass
        finally:
            self.__extensions.pop(key, None)
            sys.modules.pop(key, None)
            name = lib.__name__
            for module in list(sys.modules.keys()):
                if _is_submodule(name, module):
                    del sys.modules[module]

    def _load_from_module_spec(self, spec: importlib.machinery.ModuleSpec, key: str) -> None:
        # precondition: key not in self.__extensions
        lib = importlib.util.module_from_spec(spec)
        sys.modules[key] = lib
        try:
            spec.loader.exec_module(lib)  # type: ignore
        except Exception as e:
            del sys.modules[key]
            raise ExtensionFailed(key, e) from e

        try:
            setup = getattr(lib, 'setup')
        except AttributeError:
            del sys.modules[key]
            raise NoEntryPointError(key)

        try:
            setup(self)
        except Exception as e:
            del sys.modules[key]
            self._remove_module_references(lib.__name__)
            self._call_module_finalizers(lib, key)
            raise ExtensionFailed(key, e) from e
        else:
            self.__extensions[key] = lib

    def _resolve_name(self, name: str, package: Optional[str]) -> str:
        try:
            return importlib.util.resolve_name(name, package)
        except ImportError:
            raise ExtensionNotFound(name)

    def load_extension(self, name: str, *, package: Optional[str] = None) -> None:
        """Loads an extension.

        An extension is a python module that contains commands, cogs, or
        listeners.

        An extension must have a global function, ``setup`` defined as
        the entry point on what to do when the extension is loaded. This entry
        point must have a single argument, the ``client``.

        Parameters
        ------------
        name: :class:`str`
            The extension name to load. It must be dot separated like
            regular Python imports if accessing a sub-module. e.g.
            ``foo.test`` if you want to import ``foo/test.py``.
        package: Optional[:class:`str`]
            The package name to resolve relative imports with.
            This is required when loading an extension using a relative path, e.g ``.foo.test``.
            Defaults to ``None``.

            .. versionadded:: 1.7

        Raises
        --------
        ExtensionNotFound
            The extension could not be imported.
            This is also raised if the name of the extension could not
            be resolved using the provided ``package`` parameter.
        ExtensionAlreadyLoaded
            The extension is already loaded.
        NoEntryPointError
            The extension does not have a setup function.
        ExtensionFailed
            The extension or its setup function had an execution error.
        """

        name = self._resolve_name(name, package)
        if name in self.__extensions:
            raise ExtensionAlreadyLoaded(name)

        spec = importlib.util.find_spec(name)
        if spec is None:
            raise ExtensionNotFound(name)

        self._load_from_module_spec(spec, name)

    def unload_extension(self, name: str, *, package: Optional[str] = None) -> None:
        """Unloads an extension.

        When the extension is unloaded, all commands, listeners, and cogs are
        removed from the client and the module is un-imported.

        The extension can provide an optional global function, ``teardown``,
        to do miscellaneous clean-up if necessary. This function takes a single
        parameter, the ``client``, similar to ``setup`` from
        :meth:`.load_extension`.

        Parameters
        ------------
        name: :class:`str`
            The extension name to unload. It must be dot separated like
            regular Python imports if accessing a sub-module. e.g.
            ``foo.test`` if you want to import ``foo/test.py``.
        package: Optional[:class:`str`]
            The package name to resolve relative imports with.
            This is required when unloading an extension using a relative path, e.g ``.foo.test``.
            Defaults to ``None``.

            .. versionadded:: 1.7

        Raises
        -------
        ExtensionNotFound
            The name of the extension could not
            be resolved using the provided ``package`` parameter.
        ExtensionNotLoaded
            The extension was not loaded.
        """

        name = self._resolve_name(name, package)
        lib = self.__extensions.get(name)
        if lib is None:
            raise ExtensionNotLoaded(name)

        self._remove_module_references(lib.__name__)
        self._call_module_finalizers(lib, name)

    def reload_extension(self, name: str, *, package: Optional[str] = None) -> None:
        """Atomically reloads an extension.

        This replaces the extension with the same extension, only refreshed. This is
        equivalent to a :meth:`unload_extension` followed by a :meth:`load_extension`
        except done in an atomic way. That is, if an operation fails mid-reload then
        the client will roll-back to the prior working state.

        Parameters
        ------------
        name: :class:`str`
            The extension name to reload. It must be dot separated like
            regular Python imports if accessing a sub-module. e.g.
            ``foo.test`` if you want to import ``foo/test.py``.
        package: Optional[:class:`str`]
            The package name to resolve relative imports with.
            This is required when reloading an extension using a relative path, e.g ``.foo.test``.
            Defaults to ``None``.

            .. versionadded:: 1.7

        Raises
        -------
        ExtensionNotLoaded
            The extension was not loaded.
        ExtensionNotFound
            The extension could not be imported.
            This is also raised if the name of the extension could not
            be resolved using the provided ``package`` parameter.
        NoEntryPointError
            The extension does not have a setup function.
        ExtensionFailed
            The extension setup function had an execution error.
        """

        name = self._resolve_name(name, package)
        lib = self.__extensions.get(name)
        if lib is None:
            raise ExtensionNotLoaded(name)

        # get the previous module states from sys modules
        modules = {
            name: module
            for name, module in sys.modules.items()
            if _is_submodule(lib.__name__, name)
        }

        try:
            # Unload and then load the module...
            self._remove_module_references(lib.__name__)
            self._call_module_finalizers(lib, name)
            self.load_extension(name)
        except Exception:
            # if the load failed, the remnants should have been
            # cleaned from the load_extension function call
            # so let's load it from our old compiled library.
            lib.setup(self)  # type: ignore
            self.__extensions[name] = lib

            # revert sys.modules back to normal and raise back to caller
            sys.modules.update(modules)
            raise

    @property
    def extensions(self) -> Mapping[str, types.ModuleType]:
        """Mapping[:class:`str`, :class:`py:types.ModuleType`]: A read-only mapping of extension name to extension."""
        return types.MappingProxyType(self.__extensions)

    # application commands

    @property
    def application_commands(self) -> List[ApplicationCommand]:
        """List[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]: A list of application commands added to the client.

        .. versionadded:: 2.0
        """
        return list(self._application_commands.values())

    def add_application_command(self, application_command: ApplicationCommand) -> None:
        """Adds an application command to the client.

        Parameters
        -----------
        application_command: Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]
            The application command to add.

        Raises
        ------
        TypeError
            The application command passed is not an application command instance.
        """
        if not isinstance(application_command, _valid_application_command_types):
            raise TypeError(f'application_command must derive from SlashCommand, MessageCommand, or UserCommand')

        if application_command.__application_command_guild_ids__ is not None and self.application_command_guild_ids is not None:
            application_command.__application_command_guild_ids__ = self.application_command_guild_ids
            application_command.__application_command_global_command__ = False

        self._application_commands[application_command._get_key()] = application_command
        subcommands = list(application_command.__application_command_subcommands__.items())
        while subcommands:
            name, subcommand = subcommands.pop(0)
            subcommand.__application_command_parent__ = application_command  # type: ignore

            if inspect.isclass(subcommand):
                # parent won't be None
                application_command.__application_command_subcommands__[name] = subcommand()  # type: ignore

            subcommands.extend(subcommand.__application_command_subcommands__.items())  # type: ignore

    def remove_application_command(self, application_command: Union[ApplicationCommand, Type[ApplicationCommand]]) -> Optional[ApplicationCommand]:
        """Removes an application command from the client.

        Parameters
        -----------
        application_command: Union[
            :class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`,
            Type[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]
        ]
            The application command to remove. This can be an instance of the application command
            or its class.

        Raises
        ------
        TypeError
            The application command passed is not an application command.

        Returns
        -------
        Optional[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]
            The application command that was removed. ``None`` if not found.
        """

        if not hasattr(application_command, '__discord_application_command__'):
            raise TypeError('application_command must derive from SlashCommand, MessageCommand, or UserCommand')

        return self._application_commands.pop(application_command._get_key(), None)

    def add_application_command_check(self, func: Check) -> None:
        """Adds a global application command check client.

        This is the non-decorator interface to :meth:`.application_command_check`.

        Parameters
        -----------
        func
            The function that was used as a global check.
            This function can either be a regular function or a coroutine.
        """

        self._application_command_checks.append(func)

    def application_command_check(self, func: T) -> T:
        r"""A decorator that adds a global application command check to the client.

        A global check is similar to an application command's ``command_check`` method
        that is applied on a per command basis except it is run before any command checks
        have been run and applies to every application command the client has.

        .. note::

            This function can either be a regular function or a coroutine.

        This takes a single parameter, which is the response of the application command. The type of it can be
        :class:`SlashCommandResponse`, :class:`MessageCommandResponse` or :class:`UserCommandResponse`.

        Example
        ---------

        .. code-block:: python3

            @client.application_command_check
            async def check_commands(response):
                return await client.is_owner(response.user)

        """
        # T was used instead of Check to ensure the type matches on return
        self.add_application_command_check(func)  # type: ignore
        return func

    def application_command(self, cls: Type[AT]) -> Type[AT]:
        r"""A decorator that adds an application command to the client.

        The class being decorated must subclass :class:`SlashCommand`\, :class:`MessageCommand` or :class:`UserCommand`.

        This decorator is a shortcut method to :meth:`add_application_command` that passes an instantiated version
        of the decorated class.

        .. note::

            If you need to pass parameters to the ``__init__`` of the class\,
            call :meth:`add_application_command` yourself.

        Raises
        ------
        TypeError
            The application command passed does not derive from a valid application command class.
        """

        self.add_application_command(cls())
        return cls

    async def register_application_commands(self) -> None:
        """|coro|
        
        Registers all application commands added to the client. This will be called in
        :meth:`login` if :attr:`.register_application_commands_at_startup` is ``True``.

        .. note::

            This overwrites existing application commands. For example, if an existing
            slash command has the same name as the one you are registering, it will be
            overwritten.

        .. note::

            Global commands may take 1 hour to register in all guilds.

        Raises
        ------
        :exc:`.HTTPException`
            Registering the application commands failed.
        """

        application_commands = self._application_commands.values()
        if not application_commands:
            return

        application_id = self.application_id
        if application_id is None:
            app = await self.application_info()
            # cache the information from application_info
            self._connection.application_id = application_id = app.id
            if app.team and self.owner_ids is None:
                self.owner_ids = {m.id for m in app.team.members}
            elif self.owner_id is None:
                self.owner_id = app.owner.id

        guild_payloads = collections.defaultdict(list)
        global_payload = []
        for command in application_commands:
            command_payload = command.to_dict()
            guild_ids = command.__application_command_guild_ids__ or []
            for guild_id in guild_ids:
                guild_payloads[guild_id].append(command_payload)

            if command.__application_command_global_command__:
                global_payload.append(command_payload)

        if global_payload:
            await self.http.bulk_upsert_global_commands(application_id, global_payload)

        for guild_id, commands in guild_payloads.items():
            await self.http.bulk_upsert_guild_commands(application_id, guild_id, commands)
The MIT License (MIT)  Copyright (c) 2015-present Rapptz  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # name, type, parent Represents a client connection that connects to Discord.     This class is used to interact with the Discord WebSocket and API.      A number of options can be passed to the :class:`Client`.      Parameters     -----------     application_id: :class:`int`         The client's application ID.     max_messages: Optional[:class:`int`]         The maximum number of messages to store in the internal message cache.         This defaults to ``1000``. Passing in ``None`` disables the message cache.          .. versionchanged:: 1.3             Allow disabling the message cache and change the default size to ``1000``.     loop: Optional[:class:`asyncio.AbstractEventLoop`]         The :class:`asyncio.AbstractEventLoop` to use for asynchronous operations.         Defaults to ``None``, in which case the default event loop is used via         :func:`asyncio.get_event_loop()`.     connector: Optional[:class:`aiohttp.BaseConnector`]         The connector to use for connection pooling.     proxy: Optional[:class:`str`]         Proxy URL.     proxy_auth: Optional[:class:`aiohttp.BasicAuth`]         An object that represents proxy HTTP Basic Authorization.     shard_id: Optional[:class:`int`]         Integer starting at ``0`` and less than :attr:`.shard_count`.     shard_count: Optional[:class:`int`]         The total number of shards.     intents: :class:`Intents`         The intents that you want to enable for the session. This is a way of         disabling and enabling certain gateway events from triggering and being sent.         If not given, defaults to a regularly constructed :class:`Intents` class.          .. versionadded:: 1.5     member_cache_flags: :class:`MemberCacheFlags`         Allows for finer control over how the library caches members.         If not given, defaults to cache as much as possible with the         currently selected intents.          .. versionadded:: 1.5     chunk_guilds_at_startup: :class:`bool`         Indicates if :func:`.on_ready` should be delayed to chunk all guilds         at start-up if necessary. This operation is incredibly slow for large         amounts of guilds. The default is ``True`` if :attr:`Intents.members`         is ``True``.          .. versionadded:: 1.5     status: Optional[:class:`.Status`]         A status to start your presence with upon logging on to Discord.     activity: Optional[:class:`.BaseActivity`]         An activity to start your presence with upon logging on to Discord.     allowed_mentions: Optional[:class:`AllowedMentions`]         Control how the client handles mentions by default on every message sent.          .. versionadded:: 1.4     heartbeat_timeout: :class:`float`         The maximum numbers of seconds before timing out and restarting the         WebSocket in the case of not receiving a HEARTBEAT_ACK. Useful if         processing the initial packets take too long to the point of disconnecting         you. The default timeout is 60 seconds.     guild_ready_timeout: :class:`float`         The maximum number of seconds to wait for the GUILD_CREATE stream to end before         preparing the member cache and firing READY. The default timeout is 2 seconds.          .. versionadded:: 1.4     assume_unsync_clock: :class:`bool`         Whether to assume the system clock is unsynced. This applies to the ratelimit handling         code. If this is set to ``True``, the default, then the library uses the time to reset         a rate limit bucket given by Discord. If this is ``False`` then your system clock is         used to calculate how long to sleep for. If this is set to ``False`` it is recommended to         sync your system clock to Google's NTP server.          .. versionadded:: 1.3     enable_debug_events: :class:`bool`         Whether to enable events that are useful only for debugging gateway related information.          Right now this involves :func:`on_socket_raw_receive` and :func:`on_socket_raw_send`. If         this is ``False`` then those events will not be dispatched (due to performance considerations).         To enable these events, this must be set to ``True``. Defaults to ``False``.          .. versionadded:: 2.0     application_command_guild_ids: Optional[List[:class:`int`]]         The IDs of the guilds to upload all application commands to that do not have guild IDs set.         It is recommended to set this while testing to speed up the registering of the commands.          .. versionadded:: 2.0     register_application_commands_at_startup: :class:`bool`         Whether :meth:`register_application_commands` should be called in :meth:`login`.         It is recommended to set this to ``False`` when the application commands         added to the client are the same (having the exact same name and options) as the previous         time they were added. Defaults to ``True``.          .. note::              If this is set to ``True``, :meth:`register_application_commands` will be created as a task,             which means that the client may connect to the gateway before all application commands are registered.             :func:`on_ready` and :meth:`wait_until_ready` will be delayed to wait for             :meth:`Client.register_application_commands` to finish, regardless of whether an error was raised in it or not.          .. versionadded:: 2.0      Attributes     -----------     ws         The websocket gateway the client is currently connected to. Could be ``None``.     loop: :class:`asyncio.AbstractEventLoop`         The event loop that the client uses for asynchronous operations. # self.ws is set in the connect method # type: ignore # internals :class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.          This could be referred to as the Discord WebSocket protocol latency. :class:`bool`: Whether the websocket is currently rate limited.          This can be useful to know when deciding whether you should query members         using HTTP or via the gateway.          .. versionadded:: 1.6 Optional[:class:`.ClientUser`]: Represents the connected client. ``None`` if not logged in. List[:class:`.Guild`]: The guilds that the connected client is a member of. List[:class:`.Emoji`]: The emojis that the connected client has. List[:class:`.GuildSticker`]: The stickers that the connected client has.          .. versionadded:: 2.0 Sequence[:class:`.Message`]: Read-only list of messages the connected client has cached.          .. versionadded:: 1.1 List[:class:`.abc.PrivateChannel`]: The private channels that the connected client is participating on.          .. note::              This returns only up to 128 most recent private channels due to an internal working             on how Discord deals with private channels. List[:class:`.VoiceProtocol`]: Represents a list of voice connections.          These are usually :class:`.VoiceClient` instances. Optional[:class:`int`]: The client's application ID.          If this is not passed via ``__init__`` then this is retrieved         through the gateway when an event contains the data. Usually         after :func:`~discord.on_connect` is called.                  .. versionadded:: 2.0 :class:`~discord.ApplicationFlags`: The client's application flags.          .. versionadded:: 2.0 :class:`bool`: Specifies if the client's internal cache is ready for use. # Schedules the task |coro|          The default error handler provided by the client.          By default this prints to :data:`sys.stderr` however it could be         overridden to have a different implementation.         Check :func:`~discord.on_error` for more details. |coro|          The default application command error handler provided by the client.          By default this prints to :data:`sys.stderr` however it could be         overridden to have a different implementation.         Check :func:`~discord.on_application_command_error` for more details. # hooks # This hook is an internal hook that actually calls the public one. # It allows the library to have its own hook without stepping on the # toes of those who need to override their own hook. |coro|          A hook that is called before IDENTIFYing a session. This is useful         if you wish to have more control over the synchronization of multiple         IDENTIFYing clients.          The default implementation sleeps for 5 seconds.          .. versionadded:: 1.4          Parameters         ------------         shard_id: :class:`int`             The shard ID that requested being IDENTIFY'd         initial: :class:`bool`             Whether this IDENTIFY is the first initial IDENTIFY. # login state management |coro|          Logs in the client with the specified credentials.           Parameters         -----------         token: :class:`str`             The authentication token. Do not prefix this token with             anything as the library will do it for you.          Raises         ------         :exc:`.LoginFailure`             The wrong credentials are passed.         :exc:`.HTTPException`             An unknown HTTP related error occurred,             usually when it isn't 200 or the known incorrect credentials             passing status code. |coro|          Creates a websocket connection and lets the websocket listen         to messages from Discord. This is a loop that runs the entire         event system and miscellaneous aspects of the library. Control         is not resumed until the WebSocket connection is terminated.          Parameters         -----------         reconnect: :class:`bool`             If we should attempt reconnecting, either due to internet             failure or a specific failure on Discord's part. Certain             disconnects that lead to bad state will not be handled (such as             invalid sharding payloads or bad tokens).          Raises         -------         :exc:`.GatewayNotFound`             If the gateway to connect to Discord is not found. Usually if this             is thrown then there is a Discord API outage.         :exc:`.ConnectionClosed`             The websocket connection has been terminated. # clean close, don't re-raise this # If we get connection reset by peer then try to RESUME # We should only get this when an unhandled close code happens, # such as a clean disconnect (1000) or a bad state (bad token, no sharding, etc) # sometimes, discord sends us 1000 for unknown reasons so we should reconnect # regardless and rely on is_closed instead # Always try to RESUME the connection # If the connection is not RESUME-able then the gateway will invalidate the session. # This is apparently what the official Discord client does. |coro|          Closes the connection to Discord. # if an error happens during disconnects, disregard it. Clears the internal state of the bot.          After this, the bot can be considered "re-opened", i.e. :meth:`is_closed`         and :meth:`is_ready` both return ``False`` along with the bot's internal         cache cleared. |coro|          A shorthand coroutine for :meth:`login` + :meth:`connect`.          Raises         -------         TypeError             An unexpected keyword argument was received. A blocking call that abstracts away the event loop         initialisation from you.          If you want more control over the event loop then this         function should not be used. Use :meth:`start` coroutine         or :meth:`connect` + :meth:`login`.          Roughly Equivalent to: ::              try:                 loop.run_until_complete(start(*args, **kwargs))             except KeyboardInterrupt:                 loop.run_until_complete(close())                 # cancel all tasks lingering             finally:                 loop.close()          .. warning::              This function must be the last function to call due to the fact that it             is blocking. That means that registration of events or anything being             called after this function call will not execute until it returns. # I am unsure why this gets raised here but suppress it anyway # properties :class:`bool`: Indicates if the websocket connection is closed. Optional[:class:`.BaseActivity`]: The activity being used upon         logging in. # ConnectionState._activity is typehinted as ActivityPayload, we're passing Dict[str, Any] # type: ignore :class:`.Status`:         The status being used upon logging on to Discord.          .. versionadded: 2.0 Optional[:class:`~discord.AllowedMentions`]: The allowed mention configuration.          .. versionadded:: 1.4 :class:`~discord.Intents`: The intents configured for this connection.          .. versionadded:: 1.5 # helpers/getters List[:class:`~discord.User`]: Returns a list of all the users the bot can see. Returns a channel or thread with the given ID.          Parameters         -----------         id: :class:`int`             The ID to search for.          Returns         --------         Optional[Union[:class:`.abc.GuildChannel`, :class:`.Thread`, :class:`.abc.PrivateChannel`]]             The returned channel or ``None`` if not found. Returns a partial messageable with the given channel ID.          This is useful if you have a channel_id but don't want to do an API call         to send messages to it.                  .. versionadded:: 2.0          Parameters         -----------         id: :class:`int`             The channel ID to create a partial messageable for.         type: Optional[:class:`.ChannelType`]             The underlying channel type for the partial messageable.          Returns         --------         :class:`.PartialMessageable`             The partial messageable Returns a stage instance with the given stage channel ID.          .. versionadded:: 2.0          Parameters         -----------         id: :class:`int`             The ID to search for.          Returns         --------         Optional[:class:`.StageInstance`]             The returns stage instance of ``None`` if not found. Returns a guild with the given ID.          Parameters         -----------         id: :class:`int`             The ID to search for.          Returns         --------         Optional[:class:`.Guild`]             The guild or ``None`` if not found. Returns a user with the given ID.          Parameters         -----------         id: :class:`int`             The ID to search for.          Returns         --------         Optional[:class:`~discord.User`]             The user or ``None`` if not found. Returns an emoji with the given ID.          Parameters         -----------         id: :class:`int`             The ID to search for.          Returns         --------         Optional[:class:`.Emoji`]             The custom emoji or ``None`` if not found. Returns a guild sticker with the given ID.          .. versionadded:: 2.0          .. note::              To retrieve standard stickers, use :meth:`.fetch_sticker`.             or :meth:`.fetch_premium_sticker_packs`.          Returns         --------         Optional[:class:`.GuildSticker`]             The sticker or ``None`` if not found. A generator that retrieves every :class:`.abc.GuildChannel` the client can 'access'.          This is equivalent to: ::              for guild in client.guilds:                 for channel in guild.channels:                     yield channel          .. note::              Just because you receive a :class:`.abc.GuildChannel` does not mean that             you can communicate in said channel. :meth:`.abc.GuildChannel.permissions_for` should             be used for that.          Yields         ------         :class:`.abc.GuildChannel`             A channel the client can 'access'. Returns a generator with every :class:`.Member` the client can see.          This is equivalent to: ::              for guild in client.guilds:                 for member in guild.members:                     yield member          Yields         ------         :class:`.Member`             A member the client can see. # listeners/waiters |coro|          Waits until the client's internal cache is all ready. |coro|          Waits for a WebSocket event to be dispatched.          This could be used to wait for a user to reply to a message,         or to react to a message, or to edit a message in a self-contained         way.          The ``timeout`` parameter is passed onto :func:`asyncio.wait_for`. By default,         it does not timeout. Note that this does propagate the         :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for         ease of use.          In case the event returns multiple arguments, a :class:`tuple` containing those         arguments is returned instead. Please check the         :ref:`documentation <discord-api-events>` for a list of events and their         parameters.          This function returns the **first event that meets the requirements**.          Examples         ---------          Waiting for a user reply: ::              @client.event             async def on_message(message):                 if message.content.startswith('$greet'):                     channel = message.channel                     await channel.send('Say hello!')                      def check(m):                         return m.content == 'hello' and m.channel == channel                      msg = await client.wait_for('message', check=check)                     await channel.send(f'Hello {msg.author}!')          Waiting for a thumbs up reaction from the message author: ::              @client.event             async def on_message(message):                 if message.content.startswith('$thumb'):                     channel = message.channel                     await channel.send('Send me that \N{THUMBS UP SIGN} reaction, mate')                      def check(reaction, user):                         return user == message.author and str(reaction.emoji) == '\N{THUMBS UP SIGN}'                      try:                         reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)                     except asyncio.TimeoutError:                         await channel.send('\N{THUMBS DOWN SIGN}')                     else:                         await channel.send('\N{THUMBS UP SIGN}')           Parameters         ------------         event: :class:`str`             The event name, similar to the :ref:`event reference <discord-api-events>`,             but without the ``on_`` prefix, to wait for.         check: Optional[Callable[..., :class:`bool`]]             A predicate to check what to wait for. The arguments must meet the             parameters of the event being waited for.         timeout: Optional[:class:`float`]             The number of seconds to wait before timing out and raising             :exc:`asyncio.TimeoutError`.          Raises         -------         asyncio.TimeoutError             If a timeout is provided and it was reached.          Returns         --------         Any             Returns no arguments, a single argument, or a :class:`tuple` of multiple             arguments that mirrors the parameters passed in the             :ref:`event reference <discord-api-events>`. # event registration A decorator that registers an event to listen to.          You can find more info about the events on the :ref:`documentation below <discord-api-events>`.          The events must be a :ref:`coroutine <coroutine>`, if not, :exc:`TypeError` is raised.          Example         ---------          .. code-block:: python3              @client.event             async def on_ready():                 print('Ready!')          Raises         --------         TypeError             The coroutine passed is not actually a coroutine. |coro|          Changes the client's presence.          Example         ---------          .. code-block:: python3              game = discord.Game("with the API")             await client.change_presence(status=discord.Status.idle, activity=game)          .. versionchanged:: 2.0             Removed the ``afk`` keyword-only parameter.          Parameters         ----------         activity: Optional[:class:`.BaseActivity`]             The activity being done. ``None`` if no currently active activity is done.         status: Optional[:class:`.Status`]             Indicates what status to change to. If ``None``, then             :attr:`.Status.online` is used.          Raises         ------         :exc:`.InvalidArgument`             If the ``activity`` parameter is not the proper type. # type: ignore # Guild stuff Retrieves an :class:`.AsyncIterator` that enables receiving your guilds.          .. note::              Using this, you will only receive :attr:`.Guild.owner`, :attr:`.Guild.icon`,             :attr:`.Guild.id`, and :attr:`.Guild.name` per :class:`.Guild`.          .. note::              This method is an API call. For general usage, consider :attr:`guilds` instead.          Examples         ---------          Usage ::              async for guild in client.fetch_guilds(limit=150):                 print(guild.name)          Flattening into a list ::              guilds = await client.fetch_guilds(limit=150).flatten()             # guilds is now a list of Guild...          All parameters are optional.          Parameters         -----------         limit: Optional[:class:`int`]             The number of guilds to retrieve.             If ``None``, it retrieves every guild you have access to. Note, however,             that this would make it a slow operation.             Defaults to ``100``.         before: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]             Retrieves guilds before this date or object.             If a datetime is provided, it is recommended to use a UTC aware datetime.             If the datetime is naive, it is assumed to be local time.         after: Union[:class:`.abc.Snowflake`, :class:`datetime.datetime`]             Retrieve guilds after this date or object.             If a datetime is provided, it is recommended to use a UTC aware datetime.             If the datetime is naive, it is assumed to be local time.          Raises         ------         :exc:`.HTTPException`             Getting the guilds failed.          Yields         --------         :class:`.Guild`             The guild with the guild data parsed. |coro|          Gets a :class:`.Template` from a discord.new URL or code.          Parameters         -----------         code: Union[:class:`.Template`, :class:`str`]             The Discord Template Code or URL (must be a discord.new URL).          Raises         -------         :exc:`.NotFound`             The template is invalid.         :exc:`.HTTPException`             Getting the template failed.          Returns         --------         :class:`.Template`             The template from the URL/code. # type: ignore |coro|          Retrieves a :class:`.Guild` from an ID.          .. note::              Using this, you will **not** receive :attr:`.Guild.channels`, :attr:`.Guild.members`,             :attr:`.Member.activity` and :attr:`.Member.voice` per :class:`.Member`.          .. note::              This method is an API call. For general usage, consider :meth:`get_guild` instead.          Parameters         -----------         guild_id: :class:`int`             The guild's ID to fetch from.          Raises         ------         :exc:`.Forbidden`             You do not have access to the guild.         :exc:`.HTTPException`             Getting the guild failed.          Returns         --------         :class:`.Guild`             The guild from the ID. |coro|          Creates a :class:`.Guild`.          Bot accounts in more than 10 guilds are not allowed to create guilds.          Parameters         ----------         name: :class:`str`             The name of the guild.         region: :class:`.VoiceRegion`             The region for the voice communication server.             Defaults to :attr:`.VoiceRegion.us_west`.         icon: Optional[:class:`bytes`]             The :term:`py:bytes-like object` representing the icon. See :meth:`.ClientUser.edit`             for more details on what is expected.         code: :class:`str`             The code for a template to create the guild with.              .. versionadded:: 1.4          Raises         ------         :exc:`.HTTPException`             Guild creation failed.         :exc:`.InvalidArgument`             Invalid icon image format given. Must be PNG or JPG.          Returns         -------         :class:`.Guild`             The guild created. This is not the same guild that is             added to cache. |coro|          Gets a :class:`.StageInstance` for a stage channel id.          .. versionadded:: 2.0          Parameters         -----------         channel_id: :class:`int`             The stage channel ID.          Raises         -------         :exc:`.NotFound`             The stage instance or channel could not be found.         :exc:`.HTTPException`             Getting the stage instance failed.          Returns         --------         :class:`.StageInstance`             The stage instance from the stage channel ID. # type: ignore # Invite management |coro|          Gets an :class:`.Invite` from a discord.gg URL or ID.          .. note::              If the invite is for a guild you have not joined, the guild and channel             attributes of the returned :class:`.Invite` will be :class:`.PartialInviteGuild` and             :class:`.PartialInviteChannel` respectively.          Parameters         -----------         url: Union[:class:`.Invite`, :class:`str`]             The Discord invite ID or URL (must be a discord.gg URL).         with_counts: :class:`bool`             Whether to include count information in the invite. This fills the             :attr:`.Invite.approximate_member_count` and :attr:`.Invite.approximate_presence_count`             fields.         with_expiration: :class:`bool`             Whether to include the expiration date of the invite. This fills the             :attr:`.Invite.expires_at` field.              .. versionadded:: 2.0         scheduled_event_id: Optional[:class:`int`]             The ID of the scheduled event to include information about in the invite.             This fills the :attr:`.Invite.scheduled_event` field. If the ID is invalid,             the field will be ``None``.          Raises         -------         :exc:`.NotFound`             The invite has expired or is invalid.         :exc:`.HTTPException`             Getting the invite failed.          Returns         --------         :class:`.Invite`             The invite from the URL/ID. |coro|          Revokes an :class:`.Invite`, URL, or ID to an invite.          You must have the :attr:`~.Permissions.manage_channels` permission in         the associated guild to do this.          Parameters         ----------         invite: Union[:class:`.Invite`, :class:`str`]             The invite to revoke.          Raises         -------         :exc:`.Forbidden`             You do not have permissions to revoke invites.         :exc:`.NotFound`             The invite is invalid or expired.         :exc:`.HTTPException`             Revoking the invite failed. # Miscellaneous stuff |coro|          Gets a :class:`.Widget` from a guild ID.          .. note::              The guild must have the widget enabled to get this information.          Parameters         -----------         guild_id: :class:`int`             The ID of the guild.          Raises         -------         :exc:`.Forbidden`             The widget for this guild is disabled.         :exc:`.HTTPException`             Retrieving the widget failed.          Returns         --------         :class:`.Widget`             The guild's widget. |coro|          Retrieves the bot's application information.          Raises         -------         :exc:`.HTTPException`             Retrieving the information failed somehow.          Returns         --------         :class:`.AppInfo`             The bot's application information. |coro|          Retrieves a :class:`~discord.User` based on their ID.         You do not have to share any guilds with the user to get this information,         however many operations do require that you do.          .. note::              This method is an API call. If you have :attr:`discord.Intents.members` and member cache enabled, consider :meth:`get_user` instead.          Parameters         -----------         user_id: :class:`int`             The user's ID to fetch from.          Raises         -------         :exc:`.NotFound`             A user with this ID does not exist.         :exc:`.HTTPException`             Fetching the user failed.          Returns         --------         :class:`~discord.User`             The user you requested. |coro|          Retrieves a :class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, or :class:`.Thread` with the specified ID.          .. note::              This method is an API call. For general usage, consider :meth:`get_channel` instead.          .. versionadded:: 1.2          Raises         -------         :exc:`.InvalidData`             An unknown channel type was received from Discord.         :exc:`.HTTPException`             Retrieving the channel failed.         :exc:`.NotFound`             Invalid Channel ID.         :exc:`.Forbidden`             You do not have permission to fetch this channel.          Returns         --------         Union[:class:`.abc.GuildChannel`, :class:`.abc.PrivateChannel`, :class:`.Thread`]             The channel from the ID. # the factory will be a DMChannel or GroupChannel here # type: ignore # the factory can't be a DMChannel or GroupChannel here # type: ignore # GuildChannels expect a Guild, we may be passing an Object # type: ignore |coro|          Retrieves a :class:`.Webhook` with the specified ID.          Raises         --------         :exc:`.HTTPException`             Retrieving the webhook failed.         :exc:`.NotFound`             Invalid webhook ID.         :exc:`.Forbidden`             You do not have permission to fetch this webhook.          Returns         ---------         :class:`.Webhook`             The webhook you requested. |coro|          Retrieves a :class:`.Sticker` with the specified ID.          .. versionadded:: 2.0          Raises         --------         :exc:`.HTTPException`             Retrieving the sticker failed.         :exc:`.NotFound`             Invalid sticker ID.          Returns         --------         Union[:class:`.StandardSticker`, :class:`.GuildSticker`]             The sticker you requested. # type: ignore # type: ignore |coro|          Retrieves all available premium sticker packs.          .. versionadded:: 2.0          Raises         -------         :exc:`.HTTPException`             Retrieving the sticker packs failed.          Returns         ---------         List[:class:`.StickerPack`]             All available premium sticker packs. |coro|          Creates a :class:`.DMChannel` with this user.          This should be rarely called, as this is done transparently for most         people.          .. versionadded:: 2.0          Parameters         -----------         user: :class:`~discord.abc.Snowflake`             The user to create a DM with.          Returns         -------         :class:`.DMChannel`             The channel that was created. Registers a :class:`~discord.ui.View` for persistent listening.          This method should be used for when a view is comprised of components         that last longer than the lifecycle of the program.                  .. versionadded:: 2.0          Parameters         ------------         view: :class:`discord.ui.View`             The view to register for dispatching.         message_id: Optional[:class:`int`]             The message ID that the view is attached to. This is currently used to             refresh the view's state during message update events. If not given             then message update events are not propagated for the view.          Raises         -------         TypeError             A view was not passed.         ValueError             The view is not persistent. A persistent view has no timeout             and all their components have an explicitly provided custom_id. Sequence[:class:`.View`]: A sequence of persistent views added to the client.                  .. versionadded:: 2.0 |coro|          Checks if a :class:`~discord.abc.Snowflake` is the owner of         this bot.          If an :attr:`owner_id` is not set, it is fetched automatically         through the use of :meth:`~.Bot.application_info`.          .. versionchanged:: 1.3             The function also checks if the application is team-owned if             :attr:`owner_ids` is not set.          Parameters         -----------         user: :class:`.abc.Snowflake`             The user to check for.          Returns         --------         :class:`bool`             Whether the user is the owner. # listener registration The non decorator alternative to :meth:`.listen`.          Parameters         -----------         func: :ref:`coroutine <coroutine>`             The function to call.         name: :class:`str`             The name of the event to listen for. Defaults to ``func.__name__``.          Example         --------          .. code-block:: python3              async def on_ready(): pass             async def my_message(message): pass              bot.add_listener(on_ready)             bot.add_listener(my_message, 'on_message') Removes a listener from the pool of listeners.          Parameters         -----------         func             The function that was used as a listener to remove.         name: :class:`str`             The name of the event we want to remove. Defaults to             ``func.__name__``. A decorator that registers another function as an external         event listener. Basically this allows you to listen to multiple         events from different places e.g. such as :func:`.on_ready`          The functions being listened to must be a :ref:`coroutine <coroutine>`.          Example         --------          .. code-block:: python3              @client.listen()             async def on_message(message):                 print('one')              # in some other file...              @client.listen('on_message')             async def my_message(message):                 print('two')          Would print one and two in an unspecified order.          Raises         -------         TypeError             The function being listened to is not a coroutine. # cogs Adds a "cog" client.          A cog is a class that has its own event listeners and commands.          .. versionchanged:: 2.0              :exc:`.ClientException` is raised when a cog with the same name             is already loaded.          Parameters         -----------         cog: :class:`.Cog`             The cog to register client.         override: :class:`bool`             If a previously loaded cog with the same name should be ejected             instead of raising an error.              .. versionadded:: 2.0          Raises         -------         TypeError             The cog does not inherit from :class:`.Cog`.         CommandError             An error happened during loading.         .ClientException             A cog with the same name is already loaded. # circular import Gets the cog instance requested.          If the cog is not found, ``None`` is returned instead.          Parameters         -----------         name: :class:`str`             The name of the cog you are requesting.             This is equivalent to the name passed via keyword             argument in class creation or the class name if unspecified.          Returns         --------         Optional[:class:`Cog`]             The cog that was requested. If not found, returns ``None``. Removes a cog from the client and returns it.          All registered commands and event listeners that the         cog has registered will be removed as well.          If no cog is found then this method has no effect.          Parameters         -----------         name: :class:`str`             The name of the cog to remove.          Returns         -------         Optional[:class:`.Cog`]             The cog that was removed. ``None`` if not found. # circular import Mapping[:class:`str`, :class:`Cog`]: A read-only mapping of cog name to cog. # extensions # find all references to the module # remove the cogs registered from the module # circular imports # remove all the commands from the module # remove all the listeners from the module # precondition: key not in self.__extensions # type: ignore Loads an extension.          An extension is a python module that contains commands, cogs, or         listeners.          An extension must have a global function, ``setup`` defined as         the entry point on what to do when the extension is loaded. This entry         point must have a single argument, the ``client``.          Parameters         ------------         name: :class:`str`             The extension name to load. It must be dot separated like             regular Python imports if accessing a sub-module. e.g.             ``foo.test`` if you want to import ``foo/test.py``.         package: Optional[:class:`str`]             The package name to resolve relative imports with.             This is required when loading an extension using a relative path, e.g ``.foo.test``.             Defaults to ``None``.              .. versionadded:: 1.7          Raises         --------         ExtensionNotFound             The extension could not be imported.             This is also raised if the name of the extension could not             be resolved using the provided ``package`` parameter.         ExtensionAlreadyLoaded             The extension is already loaded.         NoEntryPointError             The extension does not have a setup function.         ExtensionFailed             The extension or its setup function had an execution error. Unloads an extension.          When the extension is unloaded, all commands, listeners, and cogs are         removed from the client and the module is un-imported.          The extension can provide an optional global function, ``teardown``,         to do miscellaneous clean-up if necessary. This function takes a single         parameter, the ``client``, similar to ``setup`` from         :meth:`.load_extension`.          Parameters         ------------         name: :class:`str`             The extension name to unload. It must be dot separated like             regular Python imports if accessing a sub-module. e.g.             ``foo.test`` if you want to import ``foo/test.py``.         package: Optional[:class:`str`]             The package name to resolve relative imports with.             This is required when unloading an extension using a relative path, e.g ``.foo.test``.             Defaults to ``None``.              .. versionadded:: 1.7          Raises         -------         ExtensionNotFound             The name of the extension could not             be resolved using the provided ``package`` parameter.         ExtensionNotLoaded             The extension was not loaded. Atomically reloads an extension.          This replaces the extension with the same extension, only refreshed. This is         equivalent to a :meth:`unload_extension` followed by a :meth:`load_extension`         except done in an atomic way. That is, if an operation fails mid-reload then         the client will roll-back to the prior working state.          Parameters         ------------         name: :class:`str`             The extension name to reload. It must be dot separated like             regular Python imports if accessing a sub-module. e.g.             ``foo.test`` if you want to import ``foo/test.py``.         package: Optional[:class:`str`]             The package name to resolve relative imports with.             This is required when reloading an extension using a relative path, e.g ``.foo.test``.             Defaults to ``None``.              .. versionadded:: 1.7          Raises         -------         ExtensionNotLoaded             The extension was not loaded.         ExtensionNotFound             The extension could not be imported.             This is also raised if the name of the extension could not             be resolved using the provided ``package`` parameter.         NoEntryPointError             The extension does not have a setup function.         ExtensionFailed             The extension setup function had an execution error. # get the previous module states from sys modules # Unload and then load the module... # if the load failed, the remnants should have been # cleaned from the load_extension function call # so let's load it from our old compiled library. # type: ignore # revert sys.modules back to normal and raise back to caller Mapping[:class:`str`, :class:`py:types.ModuleType`]: A read-only mapping of extension name to extension. # application commands List[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]: A list of application commands added to the client.          .. versionadded:: 2.0 Adds an application command to the client.          Parameters         -----------         application_command: Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]             The application command to add.          Raises         ------         TypeError             The application command passed is not an application command instance. # type: ignore # parent won't be None # type: ignore # type: ignore Removes an application command from the client.          Parameters         -----------         application_command: Union[             :class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`,             Type[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]         ]             The application command to remove. This can be an instance of the application command             or its class.          Raises         ------         TypeError             The application command passed is not an application command.          Returns         -------         Optional[Union[:class:`SlashCommand`, :class:`MessageCommand`, :class:`UserCommand`]]             The application command that was removed. ``None`` if not found. Adds a global application command check client.          This is the non-decorator interface to :meth:`.application_command_check`.          Parameters         -----------         func             The function that was used as a global check.             This function can either be a regular function or a coroutine. A decorator that adds a global application command check to the client.          A global check is similar to an application command's ``command_check`` method         that is applied on a per command basis except it is run before any command checks         have been run and applies to every application command the client has.          .. note::              This function can either be a regular function or a coroutine.          This takes a single parameter, which is the response of the application command. The type of it can be         :class:`SlashCommandResponse`, :class:`MessageCommandResponse` or :class:`UserCommandResponse`.          Example         ---------          .. code-block:: python3              @client.application_command_check             async def check_commands(response):                 return await client.is_owner(response.user) # T was used instead of Check to ensure the type matches on return # type: ignore A decorator that adds an application command to the client.          The class being decorated must subclass :class:`SlashCommand`\, :class:`MessageCommand` or :class:`UserCommand`.          This decorator is a shortcut method to :meth:`add_application_command` that passes an instantiated version         of the decorated class.          .. note::              If you need to pass parameters to the ``__init__`` of the class\,             call :meth:`add_application_command` yourself.          Raises         ------         TypeError             The application command passed does not derive from a valid application command class. |coro|                  Registers all application commands added to the client. This will be called in         :meth:`login` if :attr:`.register_application_commands_at_startup` is ``True``.          .. note::              This overwrites existing application commands. For example, if an existing             slash command has the same name as the one you are registering, it will be             overwritten.          .. note::              Global commands may take 1 hour to register in all guilds.          Raises         ------         :exc:`.HTTPException`             Registering the application commands failed. # cache the information from application_info