Fix typings in raw_models.py

# Conflicts:
#	discord/raw_models.py

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,6 @@
 name: Bug Report
 description: Report broken or incorrect behaviour
 labels: unconfirmed bug
-issue_body: true
 body:
   - type: markdown
     attributes:
@@ -73,3 +72,7 @@ body:
           required: true
         - label: I have removed my token from display, if visible.
           required: true
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: If there is anything else to say, please do so here.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,6 @@
 name: Feature Request
 description: Suggest a feature for this library
 labels: feature request
-issue_body: true
 body:
   - type: input
     attributes:
@@ -44,3 +43,7 @@ body:
         What is the current solution to the problem, if any?
     validations:
       required: false
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: If there is anything else to say, please do so here.

MANIFEST.in

@@ -2,3 +2,4 @@ include README.rst
 include LICENSE
 include requirements.txt
 include discord/bin/*.dll
+include discord/py.typed

README.ja.rst

@@ -1,114 +0,0 @@
-discord.py
-==========
-
-.. image:: https://discord.com/api/guilds/336642139381301249/embed.png
-   :target: https://discord.gg/nXzj3dg
-   :alt: Discordサーバーの招待
-.. image:: https://img.shields.io/pypi/v/discord.py.svg
-   :target: https://pypi.python.org/pypi/discord.py
-   :alt: PyPIのバージョン情報
-.. image:: https://img.shields.io/pypi/pyversions/discord.py.svg
-   :target: https://pypi.python.org/pypi/discord.py
-   :alt: PyPIのサポートしているPythonのバージョン
-
-discord.py は機能豊富かつモダンで使いやすい、非同期処理にも対応したDiscord用のAPIラッパーです。
-
-主な特徴
--------------
-
-- ``async`` と ``await`` を使ったモダンなPythonらしいAPI。
-- 適切なレート制限処理
-- Discord APIによってサポートされているものを100％カバー。
-- メモリと速度の両方を最適化。
-
-インストール
--------------
-
-**Python 3.5.3 以降のバージョンが必須です**
-
-完全な音声サポートなしでライブラリをインストールする場合は次のコマンドを実行してください:
-
-.. code:: sh
-
-    # Linux/OS X
-    python3 -m pip install -U discord.py
-
-    # Windows
-    py -3 -m pip install -U discord.py
-
-音声サポートが必要なら、次のコマンドを実行しましょう:
-
-.. code:: sh
-
-    # Linux/OS X
-    python3 -m pip install -U discord.py[voice]
-
-    # Windows
-    py -3 -m pip install -U discord.py[voice]
-
-
-開発版をインストールしたいのならば、次の手順に従ってください:
-
-.. code:: sh
-
-    $ git clone https://github.com/Rapptz/discord.py
-    $ cd discord.py
-    $ python3 -m pip install -U .[voice]
-
-
-オプションパッケージ
-~~~~~~~~~~~~~~~~~~~~~~
-
-* PyNaCl (音声サポート用)
-
-Linuxで音声サポートを導入するには、前述のコマンドを実行する前にお気に入りのパッケージマネージャー(例えば ``apt`` や ``dnf`` など)を使って以下のパッケージをインストールする必要があります:
-
-* libffi-dev (システムによっては ``libffi-devel``)
-* python-dev (例えばPython 3.6用の ``python3.6-dev``)
-
-簡単な例
---------------
-
-.. code:: py
-
-    import discord
-
-    class MyClient(discord.Client):
-        async def on_ready(self):
-            print('Logged on as', self.user)
-
-        async def on_message(self, message):
-            # don't respond to ourselves
-            if message.author == self.user:
-                return
-
-            if message.content == 'ping':
-                await message.channel.send('pong')
-
-    client = MyClient()
-    client.run('token')
-
-Botの例
-~~~~~~~~~~~~~
-
-.. code:: py
-
-    import discord
-    from discord.ext import commands
-
-    bot = commands.Bot(command_prefix='>')
-
-    @bot.command()
-    async def ping(ctx):
-        await ctx.send('pong')
-
-    bot.run('token')
-
-examplesディレクトリに更に多くのサンプルがあります。
-
-リンク
-------
-
-- `ドキュメント <https://discordpy.readthedocs.io/ja/latest/index.html>`_
-- `公式Discordサーバー <https://discord.gg/nXzj3dg>`_
-- `Discord API <https://discord.gg/discord-api>`_

README.rst

@@ -1,57 +1,64 @@
 discord.py
 ==========
 
-.. image:: https://discord.com/api/guilds/336642139381301249/embed.png
-   :target: https://discord.gg/r3sSKJJ
+.. image:: https://discord.com/api/guilds/514232441498763279/embed.png
+   :target: https://discord.gg/PYAfZzpsjG
    :alt: Discord server invite
-.. image:: https://img.shields.io/pypi/v/discord.py.svg
-   :target: https://pypi.python.org/pypi/discord.py
+.. image:: https://img.shields.io/pypi/v/enhanced-dpy.svg
+   :target: https://pypi.python.org/pypi/enhanced-dpy
    :alt: PyPI version info
-.. image:: https://img.shields.io/pypi/pyversions/discord.py.svg
-   :target: https://pypi.python.org/pypi/discord.py
+.. image:: https://img.shields.io/pypi/pyversions/enhanced-dpy.svg
+   :target: https://pypi.python.org/pypi/enhanced-dpy
    :alt: PyPI supported Python versions
 
-A modern, easy to use, feature-rich, and async ready API wrapper for Discord written in Python.
+A modern, maintained, easy to use, feature-rich, and async ready API wrapper for Discord written in Python.
+
+The Future of enhanced-discord.py
+--------------------------
+
+Enhanced discord.py is a fork of Rapptz's discord.py, that went unmaintained (`gist <https://gist.github.com/Rapptz/4a2f62751b9600a31a0d3c78100287f1>`_)
+
+It is currently maintained by (in alphabetical order)
+
+- Chillymosh#8175
+- Daggy#9889
+- dank Had0cK#6081
+- Dutchy#6127
+- Eyesofcreeper#0001
+- Gnome!#6669
+- IAmTomahawkx#1000
+- Jadon#2494
+
+An overview of added features is available on the `custom features page <https://enhanced-dpy.readthedocs.io/en/latest/index.html#custom-features>`_.
 
 Key Features
 -------------
 
 - Modern Pythonic API using ``async`` and ``await``.
 - Proper rate limit handling.
-- 100% coverage of the supported Discord API.
 - Optimised in both speed and memory.
 
 Installing
 ----------
 
-**Python 3.5.3 or higher is required**
+**Python 3.8 or higher is required**
 
 To install the library without full voice support, you can just run the following command:
 
 .. code:: sh
 
     # Linux/macOS
-    python3 -m pip install -U discord.py
+    python3 -m pip install -U enhanced-dpy
 
     # Windows
-    py -3 -m pip install -U discord.py
-
-Otherwise to get voice support you should run the following command:
-
-.. code:: sh
-
-    # Linux/macOS
-    python3 -m pip install -U "discord.py[voice]"
-
-    # Windows
-    py -3 -m pip install -U discord.py[voice]
+    py -3 -m pip install -U enhanced-dpy
 
 
 To install the development version, do the following:
 
 .. code:: sh
 
-    $ git clone https://github.com/Rapptz/discord.py
+    $ git clone https://github.com/iDevision/enhanced-discord.py
     $ cd discord.py
     $ python3 -m pip install -U .[voice]
 
@@ -59,7 +66,7 @@ To install the development version, do the following:
 Optional Packages
 ~~~~~~~~~~~~~~~~~~
 
-* PyNaCl (for voice support)
+* `PyNaCl <https://pypi.org/project/PyNaCl/>`__ (for voice support)
 
 Please note that on Linux installing voice you must install the following packages via your favourite package manager (e.g. ``apt``, ``dnf``, etc) before running the above commands:
 
@@ -109,6 +116,6 @@ You can find more examples in the examples directory.
 Links
 ------
 
-- `Documentation <https://discordpy.readthedocs.io/en/latest/index.html>`_
-- `Official Discord Server <https://discord.gg/r3sSKJJ>`_
+- `Documentation <https://enhanced-dpy.readthedocs.io/en/latest/index.html>`_
+- `Official Discord Server <https://discord.gg/PYAfZzpsjG>`_
 - `Discord API <https://discord.gg/discord-api>`_

discord/__init__.py

@@ -17,8 +17,8 @@ __version__ = '2.0.0a'
 
 __path__ = __import__('pkgutil').extend_path(__path__, __name__)
 
-from collections import namedtuple
 import logging
+from typing import NamedTuple, Literal
 
 from .client import *
 from .appinfo import *
@@ -43,7 +43,7 @@ from .template import *
 from .widget import *
 from .object import *
 from .reaction import *
-from . import utils, opus, abc
+from . import utils, opus, abc, ui
 from .enums import *
 from .embeds import *
 from .mentions import *
@@ -55,10 +55,20 @@ from .audit_logs import *
 from .raw_models import *
 from .team import *
 from .sticker import *
+from .stage_instance import *
 from .interactions import *
+from .components import *
+from .threads import *
 
-VersionInfo = namedtuple('VersionInfo', 'major minor micro releaselevel serial')
 
-version_info = VersionInfo(major=2, minor=0, micro=0, releaselevel='alpha', serial=0)
+class VersionInfo(NamedTuple):
+    major: int
+    minor: int
+    micro: int
+    releaselevel: Literal["alpha", "beta", "candidate", "final"]
+    serial: int
+
+
+version_info: VersionInfo = VersionInfo(major=2, minor=0, micro=0, releaselevel='alpha', serial=0)
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())

discord/__main__.py

@@ -51,7 +51,7 @@ def core(parser, args):
     if args.version:
         show_version()
 
-bot_template = """#!/usr/bin/env python3
+_bot_template = """#!/usr/bin/env python3
 
 from discord.ext import commands
 import discord
@@ -64,10 +64,10 @@ class Bot(commands.{base}):
             try:
                 self.load_extension(cog)
             except Exception as exc:
-                print('Could not load extension {{0}} due to {{1.__class__.__name__}}: {{1}}'.format(cog, exc))
+                print(f'Could not load extension {{cog}} due to {{exc.__class__.__name__}}: {{exc}}')
 
     async def on_ready(self):
-        print('Logged on as {{0}} (ID: {{0.id}})'.format(self.user))
+        print(f'Logged on as {{self.user}} (ID: {{self.user.id}})')
 
 
 bot = Bot()
@@ -77,7 +77,7 @@ bot = Bot()
 bot.run(config.token)
 """
 
-gitignore_template = """# Byte-compiled / optimized / DLL files
+_gitignore_template = """# Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
 *$py.class
@@ -107,7 +107,7 @@ var/
 config.py
 """
 
-cog_template = '''from discord.ext import commands
+_cog_template = '''from discord.ext import commands
 import discord
 
 class {name}(commands.Cog{attrs}):
@@ -120,7 +120,7 @@ def setup(bot):
     bot.add_cog({name}(bot))
 '''
 
-cog_extras = '''
+_cog_extras = '''
     def cog_unload(self):
         # clean up logic goes here
         pass
@@ -170,7 +170,7 @@ _base_table = {
 # NUL (0) and 1-31 are disallowed
 _base_table.update((chr(i), None) for i in range(32))
 
-translation_table = str.maketrans(_base_table)
+_translation_table = str.maketrans(_base_table)
 
 def to_path(parser, name, *, replace_spaces=False):
     if isinstance(name, Path):
@@ -182,7 +182,7 @@ def to_path(parser, name, *, replace_spaces=False):
         if len(name) <= 4 and name.upper() in forbidden:
             parser.error('invalid directory name given, use a different one')
 
-    name = name.translate(translation_table)
+    name = name.translate(_translation_table)
     if replace_spaces:
         name = name.replace(' ', '-')
     return Path(name)
@@ -215,14 +215,14 @@ def newbot(parser, args):
     try:
         with open(str(new_directory / 'bot.py'), 'w', encoding='utf-8') as fp:
             base = 'Bot' if not args.sharded else 'AutoShardedBot'
-            fp.write(bot_template.format(base=base, prefix=args.prefix))
+            fp.write(_bot_template.format(base=base, prefix=args.prefix))
     except OSError as exc:
         parser.error(f'could not create bot file ({exc})')
 
     if not args.no_git:
         try:
             with open(str(new_directory / '.gitignore'), 'w', encoding='utf-8') as fp:
-                fp.write(gitignore_template)
+                fp.write(_gitignore_template)
         except OSError as exc:
             print(f'warning: could not create .gitignore file ({exc})')
 
@@ -240,7 +240,7 @@ def newcog(parser, args):
     try:
         with open(str(directory), 'w', encoding='utf-8') as fp:
             attrs = ''
-            extra = cog_extras if args.full else ''
+            extra = _cog_extras if args.full else ''
             if args.class_name:
                 name = args.class_name
             else:
@@ -255,7 +255,7 @@ def newcog(parser, args):
                 attrs += f', name="{args.display_name}"'
             if args.hide_commands:
                 attrs += ', command_attrs=dict(hidden=True)'
-            fp.write(cog_template.format(name=name, extra=extra, attrs=attrs))
+            fp.write(_cog_template.format(name=name, extra=extra, attrs=attrs))
     except OSError as exc:
         parser.error(f'could not create cog file ({exc})')
     else:

discord/activity.py

@@ -22,7 +22,10 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 import datetime
+from typing import Any, Dict, List, Optional, TYPE_CHECKING, Union, overload
 
 from .asset import Asset
 from .enums import ActivityType, try_enum
@@ -71,6 +74,9 @@ type: int
 sync_id: str
 session_id: str
 flags: int
+buttons: list[dict]
+    label: str (max: 32)
+    url: str (max: 512)
 
 There are also activity flags which are mostly uninteresting for the library atm.
 
@@ -84,6 +90,16 @@ t.ActivityFlags = {
 }
 """
 
+if TYPE_CHECKING:
+    from .types.activity import (
+        Activity as ActivityPayload,
+        ActivityTimestamps,
+        ActivityParty,
+        ActivityAssets,
+        ActivityButton,
+    )
+
+
 class BaseActivity:
     """The base activity that all user-settable activities inherit from.
     A user-settable activity is one that can be used in :meth:`Client.change_presence`.
@@ -102,19 +118,24 @@ class BaseActivity:
 
     .. versionadded:: 1.3
     """
+
     __slots__ = ('_created_at',)
 
     def __init__(self, **kwargs):
-        self._created_at = kwargs.pop('created_at', None)
+        self._created_at: Optional[float] = kwargs.pop('created_at', None)
 
     @property
-    def created_at(self):
+    def created_at(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC.
 
         .. versionadded:: 1.3
         """
         if self._created_at is not None:
-            return datetime.datetime.utcfromtimestamp(self._created_at / 1000)
+            return datetime.datetime.fromtimestamp(self._created_at / 1000, tz=datetime.timezone.utc)
+
+    def to_dict(self) -> ActivityPayload:
+        raise NotImplementedError
+
 
 class Activity(BaseActivity):
     """Represents an activity in Discord.
@@ -130,17 +151,17 @@ class Activity(BaseActivity):
 
     Attributes
     ------------
-    application_id: :class:`int`
+    application_id: Optional[:class:`int`]
         The application ID of the game.
-    name: :class:`str`
+    name: Optional[:class:`str`]
         The name of the activity.
-    url: :class:`str`
+    url: Optional[:class:`str`]
         A stream URL that the activity could be doing.
     type: :class:`ActivityType`
         The type of activity currently being done.
-    state: :class:`str`
+    state: Optional[:class:`str`]
         The user's current state. For example, "In Game".
-    details: :class:`str`
+    details: Optional[:class:`str`]
         The detail of the user's current activity.
     timestamps: :class:`dict`
         A dictionary of timestamps. It contains the following optional keys:
@@ -164,38 +185,61 @@ class Activity(BaseActivity):
 
         - ``id``: A string representing the party ID.
         - ``size``: A list of up to two integer elements denoting (current_size, maximum_size).
+    buttons: List[:class:`dict`]
+        An list of dictionaries representing custom buttons shown in a rich presence.
+        Each dictionary contains the following keys:
+
+        - ``label``: A string representing the text shown on the button.
+        - ``url``: A string representing the URL opened upon clicking the button.
+
+        .. versionadded:: 2.0
+
     emoji: Optional[:class:`PartialEmoji`]
         The emoji that belongs to this activity.
     """
 
-    __slots__ = ('state', 'details', '_created_at', 'timestamps', 'assets', 'party',
-                 'flags', 'sync_id', 'session_id', 'type', 'name', 'url',
-                 'application_id', 'emoji')
+    __slots__ = (
+        'state',
+        'details',
+        '_created_at',
+        'timestamps',
+        'assets',
+        'party',
+        'flags',
+        'sync_id',
+        'session_id',
+        'type',
+        'name',
+        'url',
+        'application_id',
+        'emoji',
+        'buttons',
+    )
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
-        self.state = kwargs.pop('state', None)
-        self.details = kwargs.pop('details', None)
-        self.timestamps = kwargs.pop('timestamps', {})
-        self.assets = kwargs.pop('assets', {})
-        self.party = kwargs.pop('party', {})
-        self.application_id = _get_as_snowflake(kwargs, 'application_id')
-        self.name = kwargs.pop('name', None)
-        self.url = kwargs.pop('url', None)
-        self.flags = kwargs.pop('flags', 0)
-        self.sync_id = kwargs.pop('sync_id', None)
-        self.session_id = kwargs.pop('session_id', None)
+        self.state: Optional[str] = kwargs.pop('state', None)
+        self.details: Optional[str] = kwargs.pop('details', None)
+        self.timestamps: ActivityTimestamps = kwargs.pop('timestamps', {})
+        self.assets: ActivityAssets = kwargs.pop('assets', {})
+        self.party: ActivityParty = kwargs.pop('party', {})
+        self.application_id: Optional[int] = _get_as_snowflake(kwargs, 'application_id')
+        self.name: Optional[str] = kwargs.pop('name', None)
+        self.url: Optional[str] = kwargs.pop('url', None)
+        self.flags: int = kwargs.pop('flags', 0)
+        self.sync_id: Optional[str] = kwargs.pop('sync_id', None)
+        self.session_id: Optional[str] = kwargs.pop('session_id', None)
+        self.buttons: List[ActivityButton] = kwargs.pop('buttons', [])
 
         activity_type = kwargs.pop('type', -1)
-        self.type = activity_type if isinstance(activity_type, ActivityType) else try_enum(ActivityType, activity_type)
+        self.type: ActivityType = (
+            activity_type if isinstance(activity_type, ActivityType) else try_enum(ActivityType, activity_type)
+        )
 
         emoji = kwargs.pop('emoji', None)
-        if emoji is not None:
-            self.emoji = PartialEmoji.from_dict(emoji)
-        else:
-            self.emoji = None
+        self.emoji: Optional[PartialEmoji] = PartialEmoji.from_dict(emoji) if emoji is not None else None
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         attrs = (
             ('type', self.type),
             ('name', self.name),
@@ -208,8 +252,8 @@ class Activity(BaseActivity):
         inner = ' '.join('%s=%r' % t for t in attrs)
         return f'<Activity {inner}>'
 
-    def to_dict(self):
-        ret = {}
+    def to_dict(self) -> Dict[str, Any]:
+        ret: Dict[str, Any] = {}
         for attr in self.__slots__:
             value = getattr(self, attr, None)
             if value is None:
@@ -225,27 +269,27 @@ class Activity(BaseActivity):
         return ret
 
     @property
-    def start(self):
+    def start(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the user started doing this activity in UTC, if applicable."""
         try:
             timestamp = self.timestamps['start'] / 1000
         except KeyError:
             return None
         else:
-            return datetime.datetime.utcfromtimestamp(timestamp).replace(tzinfo=datetime.timezone.utc)
+            return datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
 
     @property
-    def end(self):
+    def end(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the user will stop doing this activity in UTC, if applicable."""
         try:
             timestamp = self.timestamps['end'] / 1000
         except KeyError:
             return None
         else:
-            return datetime.datetime.utcfromtimestamp(timestamp).replace(tzinfo=datetime.timezone.utc)
+            return datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
 
     @property
-    def large_image_url(self):
+    def large_image_url(self) -> Optional[str]:
         """Optional[:class:`str`]: Returns a URL pointing to the large image asset of this activity if applicable."""
         if self.application_id is None:
             return None
@@ -258,7 +302,7 @@ class Activity(BaseActivity):
             return Asset.BASE + f'/app-assets/{self.application_id}/{large_image}.png'
 
     @property
-    def small_image_url(self):
+    def small_image_url(self) -> Optional[str]:
         """Optional[:class:`str`]: Returns a URL pointing to the small image asset of this activity if applicable."""
         if self.application_id is None:
             return None
@@ -269,13 +313,14 @@ class Activity(BaseActivity):
             return None
         else:
             return Asset.BASE + f'/app-assets/{self.application_id}/{small_image}.png'
+
     @property
-    def large_image_text(self):
+    def large_image_text(self) -> Optional[str]:
         """Optional[:class:`str`]: Returns the large image asset hover text of this activity if applicable."""
         return self.assets.get('large_text', None)
 
     @property
-    def small_image_text(self):
+    def small_image_text(self) -> Optional[str]:
         """Optional[:class:`str`]: Returns the small image asset hover text of this activity if applicable."""
         return self.assets.get('small_text', None)
 
@@ -316,12 +361,12 @@ class Game(BaseActivity):
 
     __slots__ = ('name', '_end', '_start')
 
-    def __init__(self, name, **extra):
+    def __init__(self, name: str, **extra):
         super().__init__(**extra)
-        self.name = name
+        self.name: str = name
 
         try:
-            timestamps = extra['timestamps']
+            timestamps: ActivityTimestamps = extra['timestamps']
         except KeyError:
             self._start = 0
             self._end = 0
@@ -330,7 +375,7 @@ class Game(BaseActivity):
             self._end = timestamps.get('end', 0)
 
     @property
-    def type(self):
+    def type(self) -> ActivityType:
         """:class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.playing`.
@@ -338,48 +383,51 @@ class Game(BaseActivity):
         return ActivityType.playing
 
     @property
-    def start(self):
+    def start(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the user started playing this game in UTC, if applicable."""
         if self._start:
-            return datetime.datetime.utcfromtimestamp(self._start / 1000).replace(tzinfo=datetime.timezone.utc)
+            return datetime.datetime.fromtimestamp(self._start / 1000, tz=datetime.timezone.utc)
         return None
 
     @property
-    def end(self):
+    def end(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the user will stop playing this game in UTC, if applicable."""
         if self._end:
-            return datetime.datetime.utcfromtimestamp(self._end / 1000).replace(tzinfo=datetime.timezone.utc)
+            return datetime.datetime.fromtimestamp(self._end / 1000, tz=datetime.timezone.utc)
         return None
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self.name)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f'<Game name={self.name!r}>'
 
-    def to_dict(self):
-        timestamps = {}
+    def to_dict(self) -> Dict[str, Any]:
+        timestamps: Dict[str, Any] = {}
         if self._start:
             timestamps['start'] = self._start
 
         if self._end:
             timestamps['end'] = self._end
 
+        # fmt: off
         return {
             'type': ActivityType.playing.value,
             'name': str(self.name),
             'timestamps': timestamps
         }
+        # fmt: on
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         return isinstance(other, Game) and other.name == self.name
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.name)
 
+
 class Streaming(BaseActivity):
     """A slimmed down version of :class:`Activity` that represents a Discord streaming status.
 
@@ -405,7 +453,7 @@ class Streaming(BaseActivity):
 
     Attributes
     -----------
-    platform: :class:`str`
+    platform: Optional[:class:`str`]
         Where the user is streaming from (ie. YouTube, Twitch).
 
         .. versionadded:: 1.3
@@ -427,27 +475,27 @@ class Streaming(BaseActivity):
 
     __slots__ = ('platform', 'name', 'game', 'url', 'details', 'assets')
 
-    def __init__(self, *, name, url, **extra):
+    def __init__(self, *, name: Optional[str], url: str, **extra: Any):
         super().__init__(**extra)
-        self.platform = name
-        self.name = extra.pop('details', name)
-        self.game = extra.pop('state', None)
-        self.url = url
-        self.details = extra.pop('details', self.name) # compatibility
-        self.assets = extra.pop('assets', {})
+        self.platform: Optional[str] = name
+        self.name: Optional[str] = extra.pop('details', name)
+        self.game: Optional[str] = extra.pop('state', None)
+        self.url: str = url
+        self.details: Optional[str] = extra.pop('details', self.name)  # compatibility
+        self.assets: ActivityAssets = extra.pop('assets', {})
 
     @property
-    def type(self):
+    def type(self) -> ActivityType:
         """:class:`ActivityType`: Returns the game's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.streaming`.
         """
         return ActivityType.streaming
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self.name)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f'<Streaming name={self.name!r}>'
 
     @property
@@ -465,26 +513,29 @@ class Streaming(BaseActivity):
         else:
             return name[7:] if name[:7] == 'twitch:' else None
 
-    def to_dict(self):
-        ret = {
+    def to_dict(self) -> Dict[str, Any]:
+        # fmt: off
+        ret: Dict[str, Any] = {
             'type': ActivityType.streaming.value,
             'name': str(self.name),
             'url': str(self.url),
             'assets': self.assets
         }
+        # fmt: on
         if self.details:
             ret['details'] = self.details
         return ret
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         return isinstance(other, Streaming) and other.name == self.name and other.url == self.url
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.name)
 
+
 class Spotify:
     """Represents a Spotify listening activity from Discord. This is a special case of
     :class:`Activity` that makes it easier to work with the Spotify integration.
@@ -508,21 +559,20 @@ class Spotify:
             Returns the string 'Spotify'.
     """
 
-    __slots__ = ('_state', '_details', '_timestamps', '_assets', '_party', '_sync_id', '_session_id',
-                 '_created_at')
+    __slots__ = ('_state', '_details', '_timestamps', '_assets', '_party', '_sync_id', '_session_id', '_created_at')
 
     def __init__(self, **data):
-        self._state = data.pop('state', None)
-        self._details = data.pop('details', None)
-        self._timestamps = data.pop('timestamps', {})
-        self._assets = data.pop('assets', {})
-        self._party = data.pop('party', {})
-        self._sync_id = data.pop('sync_id')
-        self._session_id = data.pop('session_id')
-        self._created_at = data.pop('created_at', None)
+        self._state: str = data.pop('state', '')
+        self._details: str = data.pop('details', '')
+        self._timestamps: Dict[str, int] = data.pop('timestamps', {})
+        self._assets: ActivityAssets = data.pop('assets', {})
+        self._party: ActivityParty = data.pop('party', {})
+        self._sync_id: str = data.pop('sync_id')
+        self._session_id: str = data.pop('session_id')
+        self._created_at: Optional[float] = data.pop('created_at', None)
 
     @property
-    def type(self):
+    def type(self) -> ActivityType:
         """:class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.listening`.
@@ -530,31 +580,31 @@ class Spotify:
         return ActivityType.listening
 
     @property
-    def created_at(self):
+    def created_at(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the user started listening in UTC.
 
         .. versionadded:: 1.3
         """
         if self._created_at is not None:
-            return datetime.datetime.utcfromtimestamp(self._created_at / 1000)
+            return datetime.datetime.fromtimestamp(self._created_at / 1000, tz=datetime.timezone.utc)
 
     @property
-    def colour(self):
+    def colour(self) -> Colour:
         """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
 
         There is an alias for this named :attr:`color`"""
-        return Colour(0x1db954)
+        return Colour(0x1DB954)
 
     @property
-    def color(self):
+    def color(self) -> Colour:
         """:class:`Colour`: Returns the Spotify integration colour, as a :class:`Colour`.
 
         There is an alias for this named :attr:`colour`"""
         return self.colour
 
-    def to_dict(self):
+    def to_dict(self) -> Dict[str, Any]:
         return {
-            'flags': 48, # SYNC | PLAY
+            'flags': 48,  # SYNC | PLAY
             'name': 'Spotify',
             'assets': self._assets,
             'party': self._party,
@@ -562,42 +612,46 @@ class Spotify:
             'session_id': self._session_id,
             'timestamps': self._timestamps,
             'details': self._details,
-            'state': self._state
+            'state': self._state,
         }
 
     @property
-    def name(self):
+    def name(self) -> str:
         """:class:`str`: The activity's name. This will always return "Spotify"."""
         return 'Spotify'
 
-    def __eq__(self, other):
-        return (isinstance(other, Spotify) and other._session_id == self._session_id
-                and other._sync_id == self._sync_id and other.start == self.start)
+    def __eq__(self, other: Any) -> bool:
+        return (
+            isinstance(other, Spotify)
+            and other._session_id == self._session_id
+            and other._sync_id == self._sync_id
+            and other.start == self.start
+        )
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self._session_id)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return 'Spotify'
 
-    def __repr__(self):
-        return '<Spotify title={0.title!r} artist={0.artist!r} track_id={0.track_id!r}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<Spotify title={self.title!r} artist={self.artist!r} track_id={self.track_id!r}>'
 
     @property
-    def title(self):
+    def title(self) -> str:
         """:class:`str`: The title of the song being played."""
         return self._details
 
     @property
-    def artists(self):
+    def artists(self) -> List[str]:
         """List[:class:`str`]: The artists of the song being played."""
         return self._state.split('; ')
 
     @property
-    def artist(self):
+    def artist(self) -> str:
         """:class:`str`: The artist of the song being played.
 
         This does not attempt to split the artist information into
@@ -606,12 +660,12 @@ class Spotify:
         return self._state
 
     @property
-    def album(self):
+    def album(self) -> str:
         """:class:`str`: The album that the song being played belongs to."""
         return self._assets.get('large_text', '')
 
     @property
-    def album_cover_url(self):
+    def album_cover_url(self) -> str:
         """:class:`str`: The album cover image URL from Spotify's CDN."""
         large_image = self._assets.get('large_image', '')
         if large_image[:8] != 'spotify:':
@@ -620,30 +674,39 @@ class Spotify:
         return 'https://i.scdn.co/image/' + album_image_id
 
     @property
-    def track_id(self):
+    def track_id(self) -> str:
         """:class:`str`: The track ID used by Spotify to identify this song."""
         return self._sync_id
 
     @property
-    def start(self):
+    def track_url(self) -> str:
+        """:class:`str`: The track URL to listen on Spotify.
+
+        .. versionadded:: 2.0
+        """
+        return f'https://open.spotify.com/track/{self.track_id}'
+
+    @property
+    def start(self) -> datetime.datetime:
         """:class:`datetime.datetime`: When the user started playing this song in UTC."""
-        return datetime.datetime.utcfromtimestamp(self._timestamps['start'] / 1000)
+        return datetime.datetime.fromtimestamp(self._timestamps['start'] / 1000, tz=datetime.timezone.utc)
 
     @property
-    def end(self):
+    def end(self) -> datetime.datetime:
         """:class:`datetime.datetime`: When the user will stop playing this song in UTC."""
-        return datetime.datetime.utcfromtimestamp(self._timestamps['end'] / 1000)
+        return datetime.datetime.fromtimestamp(self._timestamps['end'] / 1000, tz=datetime.timezone.utc)
 
     @property
-    def duration(self):
+    def duration(self) -> datetime.timedelta:
         """:class:`datetime.timedelta`: The duration of the song being played."""
         return self.end - self.start
 
     @property
-    def party_id(self):
+    def party_id(self) -> str:
         """:class:`str`: The party ID of the listening party."""
         return self._party.get('id', '')
 
+
 class CustomActivity(BaseActivity):
     """Represents a Custom activity from Discord.
 
@@ -677,13 +740,14 @@ class CustomActivity(BaseActivity):
 
     __slots__ = ('name', 'emoji', 'state')
 
-    def __init__(self, name, *, emoji=None, **extra):
+    def __init__(self, name: Optional[str], *, emoji: Optional[PartialEmoji] = None, **extra: Any):
         super().__init__(**extra)
-        self.name = name
-        self.state = extra.pop('state', None)
+        self.name: Optional[str] = name
+        self.state: Optional[str] = extra.pop('state', None)
         if self.name == 'Custom Status':
             self.name = self.state
 
+        self.emoji: Optional[PartialEmoji]
         if emoji is None:
             self.emoji = emoji
         elif isinstance(emoji, dict):
@@ -696,14 +760,14 @@ class CustomActivity(BaseActivity):
             raise TypeError(f'Expected str, PartialEmoji, or None, received {type(emoji)!r} instead.')
 
     @property
-    def type(self):
+    def type(self) -> ActivityType:
         """:class:`ActivityType`: Returns the activity's type. This is for compatibility with :class:`Activity`.
 
         It always returns :attr:`ActivityType.custom`.
         """
         return ActivityType.custom
 
-    def to_dict(self):
+    def to_dict(self) -> Dict[str, Any]:
         if self.name == self.state:
             o = {
                 'type': ActivityType.custom.value,
@@ -720,16 +784,16 @@ class CustomActivity(BaseActivity):
             o['emoji'] = self.emoji.to_dict()
         return o
 
-    def __eq__(self, other):
-        return (isinstance(other, CustomActivity) and other.name == self.name and other.emoji == self.emoji)
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, CustomActivity) and other.name == self.name and other.emoji == self.emoji
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash((self.name, str(self.emoji)))
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.emoji:
             if self.name:
                 return f'{self.emoji} {self.name}'
@@ -737,11 +801,21 @@ class CustomActivity(BaseActivity):
         else:
             return str(self.name)
 
-    def __repr__(self):
-        return '<CustomActivity name={0.name!r} emoji={0.emoji!r}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<CustomActivity name={self.name!r} emoji={self.emoji!r}>'
 
 
-def create_activity(data):
+ActivityTypes = Union[Activity, Game, CustomActivity, Streaming, Spotify]
+
+@overload
+def create_activity(data: ActivityPayload) -> ActivityTypes:
+    ...
+
+@overload
+def create_activity(data: None) -> None:
+    ...
+
+def create_activity(data: Optional[ActivityPayload]) -> Optional[ActivityTypes]:
     if not data:
         return None
 
@@ -756,10 +830,12 @@ def create_activity(data):
         except KeyError:
             return Activity(**data)
         else:
-            return CustomActivity(name=name, **data)
+            # we removed the name key from data already
+            return CustomActivity(name=name, **data) # type: ignore
     elif game_type is ActivityType.streaming:
         if 'url' in data:
-            return Streaming(**data)
+            # the url won't be None here
+            return Streaming(**data) # type: ignore
         return Activity(**data)
     elif game_type is ActivityType.listening and 'sync_id' in data and 'session_id' in data:
         return Spotify(**data)

discord/appinfo.py

@@ -22,15 +22,29 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import List, TYPE_CHECKING, Optional
+
 from . import utils
-from .user import User
 from .asset import Asset
-from .team import Team
+
+if TYPE_CHECKING:
+    from .guild import Guild
+    from .types.appinfo import (
+        AppInfo as AppInfoPayload,
+        PartialAppInfo as PartialAppInfoPayload,
+        Team as TeamPayload,
+    )
+    from .user import User
+    from .state import ConnectionState
 
 __all__ = (
     'AppInfo',
+    'PartialAppInfo',
 )
 
+
 class AppInfo:
     """Represents the application info for the bot provided by Discord.
 
@@ -48,9 +62,7 @@ class AppInfo:
 
         .. versionadded:: 1.3
 
-    icon: Optional[:class:`str`]
-        The icon hash, if it exists.
-    description: Optional[:class:`str`]
+    description: :class:`str`
         The application description.
     bot_public: :class:`bool`
         Whether the bot can be invited by anyone or if it is locked
@@ -62,155 +74,174 @@ class AppInfo:
         A list of RPC origin URLs, if RPC is enabled.
     summary: :class:`str`
         If this application is a game sold on Discord,
-        this field will be the summary field for the store page of its primary SKU
+        this field will be the summary field for the store page of its primary SKU.
 
         .. versionadded:: 1.3
 
     verify_key: :class:`str`
-        The base64 encoded key for the GameSDK's GetTicket
+        The hex encoded key for verification in interactions and the
+        GameSDK's `GetTicket <https://discord.com/developers/docs/game-sdk/applications#getticket>`_.
 
         .. versionadded:: 1.3
 
     guild_id: Optional[:class:`int`]
         If this application is a game sold on Discord,
-        this field will be the guild to which it has been linked
+        this field will be the guild to which it has been linked to.
 
         .. versionadded:: 1.3
 
     primary_sku_id: Optional[:class:`int`]
         If this application is a game sold on Discord,
-        this field will be the id of the "Game SKU" that is created, if exists
+        this field will be the id of the "Game SKU" that is created,
+        if it exists.
 
         .. versionadded:: 1.3
 
     slug: Optional[:class:`str`]
         If this application is a game sold on Discord,
-        this field will be the URL slug that links to the store page
+        this field will be the URL slug that links to the store page.
 
         .. versionadded:: 1.3
 
-    cover_image: Optional[:class:`str`]
-        If this application is a game sold on Discord,
-        this field will be the hash of the image on store embeds
+    terms_of_service_url: Optional[:class:`str`]
+        The application's terms of service URL, if set.
 
-        .. versionadded:: 1.3
+        .. versionadded:: 2.0
+
+    privacy_policy_url: Optional[:class:`str`]
+        The application's privacy policy URL, if set.
+
+        .. versionadded:: 2.0
     """
-    __slots__ = ('_state', 'description', 'id', 'name', 'rpc_origins',
-                 'bot_public', 'bot_require_code_grant', 'owner', 'icon',
-                 'summary', 'verify_key', 'team', 'guild_id', 'primary_sku_id',
-                  'slug', 'cover_image')
 
-    def __init__(self, state, data):
-        self._state = state
+    __slots__ = (
+        '_state',
+        'description',
+        'id',
+        'name',
+        'rpc_origins',
+        'bot_public',
+        'bot_require_code_grant',
+        'owner',
+        '_icon',
+        'summary',
+        'verify_key',
+        'team',
+        'guild_id',
+        'primary_sku_id',
+        'slug',
+        '_cover_image',
+        'terms_of_service_url',
+        'privacy_policy_url',
+    )
 
-        self.id = int(data['id'])
-        self.name = data['name']
-        self.description = data['description']
-        self.icon = data['icon']
-        self.rpc_origins = data['rpc_origins']
-        self.bot_public = data['bot_public']
-        self.bot_require_code_grant = data['bot_require_code_grant']
-        self.owner = User(state=self._state, data=data['owner'])
+    def __init__(self, state: ConnectionState, data: AppInfoPayload):
+        from .team import Team
 
-        team = data.get('team')
-        self.team = Team(state, team) if team else None
+        self._state: ConnectionState = state
+        self.id: int = int(data['id'])
+        self.name: str = data['name']
+        self.description: str = data['description']
+        self._icon: Optional[str] = data['icon']
+        self.rpc_origins: List[str] = data['rpc_origins']
+        self.bot_public: bool = data['bot_public']
+        self.bot_require_code_grant: bool = data['bot_require_code_grant']
+        self.owner: User = state.create_user(data['owner'])
 
-        self.summary = data['summary']
-        self.verify_key = data['verify_key']
+        team: Optional[TeamPayload] = data.get('team')
+        self.team: Optional[Team] = Team(state, team) if team else None
 
-        self.guild_id = utils._get_as_snowflake(data, 'guild_id')
+        self.summary: str = data['summary']
+        self.verify_key: str = data['verify_key']
 
-        self.primary_sku_id = utils._get_as_snowflake(data, 'primary_sku_id')
-        self.slug = data.get('slug')
-        self.cover_image = data.get('cover_image')
+        self.guild_id: Optional[int] = utils._get_as_snowflake(data, 'guild_id')
 
-    def __repr__(self):
-        return '<{0.__class__.__name__} id={0.id} name={0.name!r} description={0.description!r} public={0.bot_public} ' \
-               'owner={0.owner!r}>'.format(self)
+        self.primary_sku_id: Optional[int] = utils._get_as_snowflake(data, 'primary_sku_id')
+        self.slug: Optional[str] = data.get('slug')
+        self._cover_image: Optional[str] = data.get('cover_image')
+        self.terms_of_service_url: Optional[str] = data.get('terms_of_service_url')
+        self.privacy_policy_url: Optional[str] = data.get('privacy_policy_url')
+
+    def __repr__(self) -> str:
+        return (
+            f'<{self.__class__.__name__} id={self.id} name={self.name!r} '
+            f'description={self.description!r} public={self.bot_public} '
+            f'owner={self.owner!r}>'
+        )
 
     @property
-    def icon_url(self):
-        """:class:`.Asset`: Retrieves the application's icon asset.
-
-        This is equivalent to calling :meth:`icon_url_as` with
-        the default parameters ('webp' format and a size of 1024).
-
-        .. versionadded:: 1.3
-        """
-        return self.icon_url_as()
-
-    def icon_url_as(self, *, format='webp', size=1024):
-        """Returns an :class:`Asset` for the icon the application has.
-
-        The format must be one of 'webp', 'jpeg', 'jpg' or 'png'.
-        The size must be a power of 2 between 16 and 4096.
-
-        .. versionadded:: 1.6
-
-        Parameters
-        -----------
-        format: :class:`str`
-            The format to attempt to convert the icon to. Defaults to 'webp'.
-        size: :class:`int`
-            The size of the image to display.
-
-        Raises
-        ------
-        InvalidArgument
-            Bad image format passed to ``format`` or invalid ``size``.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_icon(self._state, self, 'app', format=format, size=size)
-
+    def icon(self) -> Optional[Asset]:
+        """Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any."""
+        if self._icon is None:
+            return None
+        return Asset._from_icon(self._state, self.id, self._icon, path='app')
 
     @property
-    def cover_image_url(self):
-        """:class:`.Asset`: Retrieves the cover image on a store embed.
+    def cover_image(self) -> Optional[Asset]:
+        """Optional[:class:`.Asset`]: Retrieves the cover image on a store embed, if any.
 
-        This is equivalent to calling :meth:`cover_image_url_as` with
-        the default parameters ('webp' format and a size of 1024).
-
-        .. versionadded:: 1.3
+        This is only available if the application is a game sold on Discord.
         """
-        return self.cover_image_url_as()
-
-    def cover_image_url_as(self, *, format='webp', size=1024):
-        """Returns an :class:`Asset` for the image on store embeds
-        if this application is a game sold on Discord.
-
-        The format must be one of 'webp', 'jpeg', 'jpg' or 'png'.
-        The size must be a power of 2 between 16 and 4096.
-
-        .. versionadded:: 1.6
-
-        Parameters
-        -----------
-        format: :class:`str`
-            The format to attempt to convert the image to. Defaults to 'webp'.
-        size: :class:`int`
-            The size of the image to display.
-
-        Raises
-        ------
-        InvalidArgument
-            Bad image format passed to ``format`` or invalid ``size``.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_cover_image(self._state, self, format=format, size=size)
+        if self._cover_image is None:
+            return None
+        return Asset._from_cover_image(self._state, self.id, self._cover_image)
 
     @property
-    def guild(self):
+    def guild(self) -> Optional[Guild]:
         """Optional[:class:`Guild`]: If this application is a game sold on Discord,
         this field will be the guild to which it has been linked
 
         .. versionadded:: 1.3
         """
-        return self._state._get_guild(int(self.guild_id))
+        return self._state._get_guild(self.guild_id)
+
+class PartialAppInfo:
+    """Represents a partial AppInfo given by :func:`~discord.abc.GuildChannel.create_invite`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -------------
+    id: :class:`int`
+        The application ID.
+    name: :class:`str`
+        The application name.
+    description: :class:`str`
+        The application description.
+    rpc_origins: Optional[List[:class:`str`]]
+        A list of RPC origin URLs, if RPC is enabled.
+    summary: :class:`str`
+        If this application is a game sold on Discord,
+        this field will be the summary field for the store page of its primary SKU.
+    verify_key: :class:`str`
+        The hex encoded key for verification in interactions and the
+        GameSDK's `GetTicket <https://discord.com/developers/docs/game-sdk/applications#getticket>`_.
+    terms_of_service_url: Optional[:class:`str`]
+        The application's terms of service URL, if set.
+    privacy_policy_url: Optional[:class:`str`]
+        The application's privacy policy URL, if set.
+    """
+
+    __slots__ = ('_state', 'id', 'name', 'description', 'rpc_origins', 'summary', 'verify_key', 'terms_of_service_url', 'privacy_policy_url', '_icon')
+
+    def __init__(self, *, state: ConnectionState, data: PartialAppInfoPayload):
+        self._state: ConnectionState = state
+        self.id: int = int(data['id'])
+        self.name: str = data['name']
+        self._icon: Optional[str] = data.get('icon')
+        self.description: str = data['description']
+        self.rpc_origins: Optional[List[str]] = data.get('rpc_origins')
+        self.summary: str = data['summary']
+        self.verify_key: str = data['verify_key']
+        self.terms_of_service_url: Optional[str] = data.get('terms_of_service_url')
+        self.privacy_policy_url: Optional[str] = data.get('privacy_policy_url')
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__} id={self.id} name={self.name!r} description={self.description!r}>'
+
+    @property
+    def icon(self) -> Optional[Asset]:
+        """Optional[:class:`.Asset`]: Retrieves the application's icon asset, if any."""
+        if self._icon is None:
+            return None
+        return Asset._from_icon(self._state, self.id, self._icon, path='app')

discord/asset.py

@@ -22,19 +22,101 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 import io
+import os
+from typing import Any, Literal, Optional, TYPE_CHECKING, Tuple, Union
 from .errors import DiscordException
 from .errors import InvalidArgument
 from . import utils
 
+import yarl
+
 __all__ = (
     'Asset',
 )
 
-VALID_STATIC_FORMATS = frozenset({"jpeg", "jpg", "webp", "png"})
-VALID_AVATAR_FORMATS = VALID_STATIC_FORMATS | {"gif"}
+if TYPE_CHECKING:
+    ValidStaticFormatTypes = Literal['webp', 'jpeg', 'jpg', 'png']
+    ValidAssetFormatTypes = Literal['webp', 'jpeg', 'jpg', 'png', 'gif']
 
-class Asset:
+VALID_STATIC_FORMATS = frozenset({"jpeg", "jpg", "webp", "png"})
+VALID_ASSET_FORMATS = VALID_STATIC_FORMATS | {"gif"}
+
+
+MISSING = utils.MISSING
+
+class AssetMixin:
+    url: str
+    _state: Optional[Any]
+
+    async def read(self) -> bytes:
+        """|coro|
+
+        Retrieves the content of this asset as a :class:`bytes` object.
+
+        Raises
+        ------
+        DiscordException
+            There was no internal connection state.
+        HTTPException
+            Downloading the asset failed.
+        NotFound
+            The asset was deleted.
+
+        Returns
+        -------
+        :class:`bytes`
+            The content of the asset.
+        """
+        if self._state is None:
+            raise DiscordException('Invalid state (no ConnectionState provided)')
+
+        return await self._state.http.get_from_cdn(self.url)
+
+    async def save(self, fp: Union[str, bytes, os.PathLike, io.BufferedIOBase], *, seek_begin: bool = True) -> int:
+        """|coro|
+
+        Saves this asset into a file-like object.
+
+        Parameters
+        ----------
+        fp: Union[:class:`io.BufferedIOBase`, :class:`os.PathLike`]
+            The file-like object to save this attachment to or the filename
+            to use. If a filename is passed then a file is created with that
+            filename and used instead.
+        seek_begin: :class:`bool`
+            Whether to seek to the beginning of the file after saving is
+            successfully done.
+
+        Raises
+        ------
+        DiscordException
+            There was no internal connection state.
+        HTTPException
+            Downloading the asset failed.
+        NotFound
+            The asset was deleted.
+
+        Returns
+        --------
+        :class:`int`
+            The number of bytes written.
+        """
+
+        data = await self.read()
+        if isinstance(fp, io.BufferedIOBase):
+            written = fp.write(data)
+            if seek_begin:
+                fp.seek(0)
+            return written
+        else:
+            with open(fp, 'wb') as f:
+                return f.write(data)
+
+
+class Asset(AssetMixin):
     """Represents a CDN asset on Discord.
 
     .. container:: operations
@@ -47,10 +129,6 @@ class Asset:
 
             Returns the length of the CDN asset's URL.
 
-        .. describe:: bool(x)
-
-            Checks if the Asset has a URL.
-
         .. describe:: x == y
 
             Checks if the asset is equal to another asset.
@@ -63,202 +141,276 @@ class Asset:
 
             Returns the hash of the asset.
     """
-    __slots__ = ('_state', '_url')
+
+    __slots__: Tuple[str, ...] = (
+        '_state',
+        '_url',
+        '_animated',
+        '_key',
+    )
 
     BASE = 'https://cdn.discordapp.com'
 
-    def __init__(self, state, url=None):
+    def __init__(self, state, *, url: str, key: str, animated: bool = False):
         self._state = state
         self._url = url
+        self._animated = animated
+        self._key = key
 
     @classmethod
-    def _from_avatar(cls, state, user, *, format=None, static_format='webp', size=1024):
-        if not utils.valid_icon_size(size):
-            raise InvalidArgument("size must be a power of 2 between 16 and 4096")
-        if format is not None and format not in VALID_AVATAR_FORMATS:
-            raise InvalidArgument(f"format must be None or one of {VALID_AVATAR_FORMATS}")
-        if format == "gif" and not user.is_avatar_animated():
-            raise InvalidArgument("non animated avatars do not support gif format")
-        if static_format not in VALID_STATIC_FORMATS:
-            raise InvalidArgument(f"static_format must be one of {VALID_STATIC_FORMATS}")
-
-        if user.avatar is None:
-            return user.default_avatar_url
-
-        if format is None:
-            format = 'gif' if user.is_avatar_animated() else static_format
-
-        return cls(state, '/avatars/{0.id}/{0.avatar}.{1}?size={2}'.format(user, format, size))
+    def _from_default_avatar(cls, state, index: int) -> Asset:
+        return cls(
+            state,
+            url=f'{cls.BASE}/embed/avatars/{index}.png',
+            key=str(index),
+            animated=False,
+        )
 
     @classmethod
-    def _from_icon(cls, state, object, path, *, format='webp', size=1024):
-        if object.icon is None:
-            return cls(state)
-
-        if not utils.valid_icon_size(size):
-            raise InvalidArgument("size must be a power of 2 between 16 and 4096")
-        if format not in VALID_STATIC_FORMATS:
-            raise InvalidArgument(f"format must be None or one of {VALID_STATIC_FORMATS}")
-
-        url = '/{0}-icons/{1.id}/{1.icon}.{2}?size={3}'.format(path, object, format, size)
-        return cls(state, url)
+    def _from_avatar(cls, state, user_id: int, avatar: str) -> Asset:
+        animated = avatar.startswith('a_')
+        format = 'gif' if animated else 'png'
+        return cls(
+            state,
+            url=f'{cls.BASE}/avatars/{user_id}/{avatar}.{format}?size=1024',
+            key=avatar,
+            animated=animated,
+        )
 
     @classmethod
-    def _from_cover_image(cls, state, obj, *, format='webp', size=1024):
-        if obj.cover_image is None:
-            return cls(state)
-
-        if not utils.valid_icon_size(size):
-            raise InvalidArgument("size must be a power of 2 between 16 and 4096")
-        if format not in VALID_STATIC_FORMATS:
-            raise InvalidArgument(f"format must be None or one of {VALID_STATIC_FORMATS}")
-
-        url = '/app-assets/{0.id}/store/{0.cover_image}.{1}?size={2}'.format(obj, format, size)
-        return cls(state, url)
+    def _from_guild_avatar(cls, state, guild_id: int, member_id: int, avatar: str) -> Asset:
+        animated = avatar.startswith('a_')
+        format = 'gif' if animated else 'png'
+        return cls(
+            state,
+            url=f"{cls.BASE}/guilds/{guild_id}/users/{member_id}/avatars/{avatar}.{format}?size=1024",
+            key=avatar,
+            animated=animated,
+        )
 
     @classmethod
-    def _from_guild_image(cls, state, id, hash, key, *, format='webp', size=1024):
-        if not utils.valid_icon_size(size):
-            raise InvalidArgument("size must be a power of 2 between 16 and 4096")
-        if format not in VALID_STATIC_FORMATS:
-            raise InvalidArgument(f"format must be one of {VALID_STATIC_FORMATS}")
-
-        if hash is None:
-            return cls(state)
-
-        url = '/{key}/{0}/{1}.{2}?size={3}'
-        return cls(state, url.format(id, hash, format, size, key=key))
+    def _from_icon(cls, state, object_id: int, icon_hash: str, path: str) -> Asset:
+        return cls(
+            state,
+            url=f'{cls.BASE}/{path}-icons/{object_id}/{icon_hash}.png?size=1024',
+            key=icon_hash,
+            animated=False,
+        )
 
     @classmethod
-    def _from_guild_icon(cls, state, guild, *, format=None, static_format='webp', size=1024):
-        if not utils.valid_icon_size(size):
-            raise InvalidArgument("size must be a power of 2 between 16 and 4096")
-        if format is not None and format not in VALID_AVATAR_FORMATS:
-            raise InvalidArgument(f"format must be one of {VALID_AVATAR_FORMATS}")
-        if format == "gif" and not guild.is_icon_animated():
-            raise InvalidArgument("non animated guild icons do not support gif format")
-        if static_format not in VALID_STATIC_FORMATS:
-            raise InvalidArgument(f"static_format must be one of {VALID_STATIC_FORMATS}")
-
-        if guild.icon is None:
-            return cls(state)
-
-        if format is None:
-            format = 'gif' if guild.is_icon_animated() else static_format
-
-        return cls(state, '/icons/{0.id}/{0.icon}.{1}?size={2}'.format(guild, format, size))
+    def _from_cover_image(cls, state, object_id: int, cover_image_hash: str) -> Asset:
+        return cls(
+            state,
+            url=f'{cls.BASE}/app-assets/{object_id}/store/{cover_image_hash}.png?size=1024',
+            key=cover_image_hash,
+            animated=False,
+        )
 
     @classmethod
-    def _from_sticker_url(cls, state, sticker, *, size=1024):
-        if not utils.valid_icon_size(size):
-            raise InvalidArgument("size must be a power of 2 between 16 and 4096")
-
-        return cls(state, '/stickers/{0.id}/{0.image}.png?size={2}'.format(sticker, format, size))
+    def _from_guild_image(cls, state, guild_id: int, image: str, path: str) -> Asset:
+        return cls(
+            state,
+            url=f'{cls.BASE}/{path}/{guild_id}/{image}.png?size=1024',
+            key=image,
+            animated=False,
+        )
 
     @classmethod
-    def _from_emoji(cls, state, emoji, *, format=None, static_format='png'):
-        if format is not None and format not in VALID_AVATAR_FORMATS:
-            raise InvalidArgument(f"format must be None or one of {VALID_AVATAR_FORMATS}")
-        if format == "gif" and not emoji.animated:
-            raise InvalidArgument("non animated emoji's do not support gif format")
-        if static_format not in VALID_STATIC_FORMATS:
-            raise InvalidArgument(f"static_format must be one of {VALID_STATIC_FORMATS}")
-        if format is None:
-            format = 'gif' if emoji.animated else static_format
+    def _from_guild_icon(cls, state, guild_id: int, icon_hash: str) -> Asset:
+        animated = icon_hash.startswith('a_')
+        format = 'gif' if animated else 'png'
+        return cls(
+            state,
+            url=f'{cls.BASE}/icons/{guild_id}/{icon_hash}.{format}?size=1024',
+            key=icon_hash,
+            animated=animated,
+        )
 
-        return cls(state, f'/emojis/{emoji.id}.{format}')
+    @classmethod
+    def _from_sticker_banner(cls, state, banner: int) -> Asset:
+        return cls(
+            state,
+            url=f'{cls.BASE}/app-assets/710982414301790216/store/{banner}.png',
+            key=str(banner),
+            animated=False,
+        )
 
-    def __str__(self):
-        return self.BASE + self._url if self._url is not None else ''
+    @classmethod
+    def _from_user_banner(cls, state, user_id: int, banner_hash: str) -> Asset:
+        animated = banner_hash.startswith('a_')
+        format = 'gif' if animated else 'png'
+        return cls(
+            state,
+            url=f'{cls.BASE}/banners/{user_id}/{banner_hash}.{format}?size=512',
+            key=banner_hash,
+            animated=animated
+        )
 
-    def __len__(self):
-        if self._url:
-            return len(self.BASE + self._url)
-        return 0
+    def __str__(self) -> str:
+        return self._url
 
-    def __bool__(self):
-        return self._url is not None
+    def __len__(self) -> int:
+        return len(self._url)
 
     def __repr__(self):
-        return f'<Asset url={self._url!r}>'
+        shorten = self._url.replace(self.BASE, '')
+        return f'<Asset url={shorten!r}>'
 
     def __eq__(self, other):
         return isinstance(other, Asset) and self._url == other._url
 
-    def __ne__(self, other):
-        return not self.__eq__(other)
-
     def __hash__(self):
         return hash(self._url)
 
-    async def read(self):
-        """|coro|
+    @property
+    def url(self) -> str:
+        """:class:`str`: Returns the underlying URL of the asset."""
+        return self._url
 
-        Retrieves the content of this asset as a :class:`bytes` object.
+    @property
+    def key(self) -> str:
+        """:class:`str`: Returns the identifying key of the asset."""
+        return self._key
 
-        .. warning::
+    def is_animated(self) -> bool:
+        """:class:`bool`: Returns whether the asset is animated."""
+        return self._animated
 
-            :class:`PartialEmoji` won't have a connection state if user created,
-            and a URL won't be present if a custom image isn't associated with
-            the asset, e.g. a guild with no custom icon.
-
-        .. versionadded:: 1.1
-
-        Raises
-        ------
-        DiscordException
-            There was no valid URL or internal connection state.
-        HTTPException
-            Downloading the asset failed.
-        NotFound
-            The asset was deleted.
-
-        Returns
-        -------
-        :class:`bytes`
-            The content of the asset.
-        """
-        if not self._url:
-            raise DiscordException('Invalid asset (no URL provided)')
-
-        if self._state is None:
-            raise DiscordException('Invalid state (no ConnectionState provided)')
-
-        return await self._state.http.get_from_cdn(self.BASE + self._url)
-
-    async def save(self, fp, *, seek_begin=True):
-        """|coro|
-
-        Saves this asset into a file-like object.
+    def replace(
+        self,
+        *,
+        size: int = MISSING,
+        format: ValidAssetFormatTypes = MISSING,
+        static_format: ValidStaticFormatTypes = MISSING,
+    ) -> Asset:
+        """Returns a new asset with the passed components replaced.
 
         Parameters
-        ----------
-        fp: Union[BinaryIO, :class:`os.PathLike`]
-            Same as in :meth:`Attachment.save`.
-        seek_begin: :class:`bool`
-            Same as in :meth:`Attachment.save`.
+        -----------
+        size: :class:`int`
+            The new size of the asset.
+        format: :class:`str`
+            The new format to change it to. Must be either
+            'webp', 'jpeg', 'jpg', 'png', or 'gif' if it's animated.
+        static_format: :class:`str`
+            The new format to change it to if the asset isn't animated.
+            Must be either 'webp', 'jpeg', 'jpg', or 'png'.
 
         Raises
-        ------
-        DiscordException
-            There was no valid URL or internal connection state.
-        HTTPException
-            Downloading the asset failed.
-        NotFound
-            The asset was deleted.
+        -------
+        InvalidArgument
+            An invalid size or format was passed.
 
         Returns
         --------
-        :class:`int`
-            The number of bytes written.
+        :class:`Asset`
+            The newly updated asset.
+        """
+        url = yarl.URL(self._url)
+        path, _ = os.path.splitext(url.path)
+
+        if format is not MISSING:
+            if self._animated:
+                if format not in VALID_ASSET_FORMATS:
+                    raise InvalidArgument(f'format must be one of {VALID_ASSET_FORMATS}')
+                url = url.with_path(f'{path}.{format}')
+            elif static_format is MISSING:
+                if format not in VALID_STATIC_FORMATS:
+                    raise InvalidArgument(f'format must be one of {VALID_STATIC_FORMATS}')
+                url = url.with_path(f'{path}.{format}')
+
+        if static_format is not MISSING and not self._animated:
+            if static_format not in VALID_STATIC_FORMATS:
+                raise InvalidArgument(f'static_format must be one of {VALID_STATIC_FORMATS}')
+            url = url.with_path(f'{path}.{static_format}')
+
+        if size is not MISSING:
+            if not utils.valid_icon_size(size):
+                raise InvalidArgument('size must be a power of 2 between 16 and 4096')
+            url = url.with_query(size=size)
+        else:
+            url = url.with_query(url.raw_query_string)
+
+        url = str(url)
+        return Asset(state=self._state, url=url, key=self._key, animated=self._animated)
+
+    def with_size(self, size: int, /) -> Asset:
+        """Returns a new asset with the specified size.
+
+        Parameters
+        ------------
+        size: :class:`int`
+            The new size of the asset.
+
+        Raises
+        -------
+        InvalidArgument
+            The asset had an invalid size.
+
+        Returns
+        --------
+        :class:`Asset`
+            The new updated asset.
+        """
+        if not utils.valid_icon_size(size):
+            raise InvalidArgument('size must be a power of 2 between 16 and 4096')
+
+        url = str(yarl.URL(self._url).with_query(size=size))
+        return Asset(state=self._state, url=url, key=self._key, animated=self._animated)
+
+    def with_format(self, format: ValidAssetFormatTypes, /) -> Asset:
+        """Returns a new asset with the specified format.
+
+        Parameters
+        ------------
+        format: :class:`str`
+            The new format of the asset.
+
+        Raises
+        -------
+        InvalidArgument
+            The asset had an invalid format.
+
+        Returns
+        --------
+        :class:`Asset`
+            The new updated asset.
         """
 
-        data = await self.read()
-        if isinstance(fp, io.IOBase) and fp.writable():
-            written = fp.write(data)
-            if seek_begin:
-                fp.seek(0)
-            return written
+        if self._animated:
+            if format not in VALID_ASSET_FORMATS:
+                raise InvalidArgument(f'format must be one of {VALID_ASSET_FORMATS}')
         else:
-            with open(fp, 'wb') as f:
-                return f.write(data)
+            if format not in VALID_STATIC_FORMATS:
+                raise InvalidArgument(f'format must be one of {VALID_STATIC_FORMATS}')
+
+        url = yarl.URL(self._url)
+        path, _ = os.path.splitext(url.path)
+        url = str(url.with_path(f'{path}.{format}').with_query(url.raw_query_string))
+        return Asset(state=self._state, url=url, key=self._key, animated=self._animated)
+
+    def with_static_format(self, format: ValidStaticFormatTypes, /) -> Asset:
+        """Returns a new asset with the specified static format.
+
+        This only changes the format if the underlying asset is
+        not animated. Otherwise, the asset is not changed.
+
+        Parameters
+        ------------
+        format: :class:`str`
+            The new static format of the asset.
+
+        Raises
+        -------
+        InvalidArgument
+            The asset had an invalid format.
+
+        Returns
+        --------
+        :class:`Asset`
+            The new updated asset.
+        """
+
+        if self._animated:
+            return self
+        return self.with_format(format)

discord/audit_logs.py

@@ -22,12 +22,17 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
-from . import utils, enums
-from .object import Object
-from .permissions import PermissionOverwrite, Permissions
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Dict, Generator, List, Optional, Tuple, Type, TypeVar, Union
+
+from . import enums, utils
+from .asset import Asset
 from .colour import Colour
 from .invite import Invite
 from .mixins import Hashable
+from .object import Object
+from .permissions import PermissionOverwrite, Permissions
 
 __all__ = (
     'AuditLogDiff',
@@ -35,51 +40,72 @@ __all__ = (
     'AuditLogEntry',
 )
 
-def _transform_verification_level(entry, data):
-    return enums.try_enum(enums.VerificationLevel, data)
 
-def _transform_default_notifications(entry, data):
-    return enums.try_enum(enums.NotificationLevel, data)
+if TYPE_CHECKING:
+    import datetime
 
-def _transform_explicit_content_filter(entry, data):
-    return enums.try_enum(enums.ContentFilter, data)
+    from . import abc
+    from .emoji import Emoji
+    from .guild import Guild
+    from .member import Member
+    from .role import Role
+    from .types.audit_log import (
+        AuditLogChange as AuditLogChangePayload,
+        AuditLogEntry as AuditLogEntryPayload,
+    )
+    from .types.channel import PermissionOverwrite as PermissionOverwritePayload
+    from .types.role import Role as RolePayload
+    from .types.snowflake import Snowflake
+    from .user import User
+    from .stage_instance import StageInstance
+    from .sticker import GuildSticker
+    from .threads import Thread
 
-def _transform_permissions(entry, data):
-    return Permissions(data)
 
-def _transform_color(entry, data):
+def _transform_permissions(entry: AuditLogEntry, data: str) -> Permissions:
+    return Permissions(int(data))
+
+
+def _transform_color(entry: AuditLogEntry, data: int) -> Colour:
     return Colour(data)
 
-def _transform_snowflake(entry, data):
+
+def _transform_snowflake(entry: AuditLogEntry, data: Snowflake) -> int:
     return int(data)
 
-def _transform_channel(entry, data):
+
+def _transform_channel(entry: AuditLogEntry, data: Optional[Snowflake]) -> Optional[Union[abc.GuildChannel, Object]]:
     if data is None:
         return None
     return entry.guild.get_channel(int(data)) or Object(id=data)
 
-def _transform_owner_id(entry, data):
+
+def _transform_member_id(entry: AuditLogEntry, data: Optional[Snowflake]) -> Union[Member, User, None]:
     if data is None:
         return None
     return entry._get_member(int(data))
 
-def _transform_inviter_id(entry, data):
+def _transform_guild_id(entry: AuditLogEntry, data: Optional[Snowflake]) -> Optional[Guild]:
     if data is None:
         return None
-    return entry._get_member(int(data))
+    return entry._state._get_guild(data)
 
-def _transform_overwrites(entry, data):
+
+def _transform_overwrites(
+    entry: AuditLogEntry, data: List[PermissionOverwritePayload]
+) -> List[Tuple[Object, PermissionOverwrite]]:
     overwrites = []
     for elem in data:
-        allow = Permissions(elem['allow'])
-        deny = Permissions(elem['deny'])
+        allow = Permissions(int(elem['allow']))
+        deny = Permissions(int(elem['deny']))
         ow = PermissionOverwrite.from_pair(allow, deny)
 
         ow_type = elem['type']
         ow_id = int(elem['id'])
-        if ow_type == 'role':
+        target = None
+        if ow_type == '0':
             target = entry.guild.get_role(ow_id)
-        else:
+        elif ow_type == '1':
             target = entry._get_member(ow_id)
 
         if target is None:
@@ -89,41 +115,104 @@ def _transform_overwrites(entry, data):
 
     return overwrites
 
+
+def _transform_icon(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:
+    if data is None:
+        return None
+    return Asset._from_guild_icon(entry._state, entry.guild.id, data)
+
+
+def _transform_avatar(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:
+    if data is None:
+        return None
+    return Asset._from_avatar(entry._state, entry._target_id, data)  # type: ignore
+
+
+def _guild_hash_transformer(path: str) -> Callable[[AuditLogEntry, Optional[str]], Optional[Asset]]:
+    def _transform(entry: AuditLogEntry, data: Optional[str]) -> Optional[Asset]:
+        if data is None:
+            return None
+        return Asset._from_guild_image(entry._state, entry.guild.id, data, path=path)
+
+    return _transform
+
+
+T = TypeVar('T', bound=enums.Enum)
+
+
+def _enum_transformer(enum: Type[T]) -> Callable[[AuditLogEntry, int], T]:
+    def _transform(entry: AuditLogEntry, data: int) -> T:
+        return enums.try_enum(enum, data)
+
+    return _transform
+
+def _transform_type(entry: AuditLogEntry, data: Union[int]) -> Union[enums.ChannelType, enums.StickerType]:
+    if entry.action.name.startswith('sticker_'):
+        return enums.try_enum(enums.StickerType, data)
+    else:
+        return enums.try_enum(enums.ChannelType, data)
+
 class AuditLogDiff:
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.__dict__)
 
-    def __iter__(self):
-        return iter(self.__dict__.items())
+    def __iter__(self) -> Generator[Tuple[str, Any], None, None]:
+        yield from self.__dict__.items()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         values = ' '.join('%s=%r' % item for item in self.__dict__.items())
         return f'<AuditLogDiff {values}>'
 
+    if TYPE_CHECKING:
+
+        def __getattr__(self, item: str) -> Any:
+            ...
+
+        def __setattr__(self, key: str, value: Any) -> Any:
+            ...
+
+
+Transformer = Callable[["AuditLogEntry", Any], Any]
+
+
 class AuditLogChanges:
-    TRANSFORMERS = {
-        'verification_level':            (None, _transform_verification_level),
-        'explicit_content_filter':       (None, _transform_explicit_content_filter),
+    # fmt: off
+    TRANSFORMERS: ClassVar[Dict[str, Tuple[Optional[str], Optional[Transformer]]]] = {
+        'verification_level':            (None, _enum_transformer(enums.VerificationLevel)),
+        'explicit_content_filter':       (None, _enum_transformer(enums.ContentFilter)),
         'allow':                         (None, _transform_permissions),
         'deny':                          (None, _transform_permissions),
         'permissions':                   (None, _transform_permissions),
         'id':                            (None, _transform_snowflake),
         'color':                         ('colour', _transform_color),
-        'owner_id':                      ('owner', _transform_owner_id),
-        'inviter_id':                    ('inviter', _transform_inviter_id),
+        'owner_id':                      ('owner', _transform_member_id),
+        'inviter_id':                    ('inviter', _transform_member_id),
         'channel_id':                    ('channel', _transform_channel),
         'afk_channel_id':                ('afk_channel', _transform_channel),
         'system_channel_id':             ('system_channel', _transform_channel),
         'widget_channel_id':             ('widget_channel', _transform_channel),
+        'rules_channel_id':              ('rules_channel', _transform_channel),
+        'public_updates_channel_id':     ('public_updates_channel', _transform_channel),
         'permission_overwrites':         ('overwrites', _transform_overwrites),
-        'splash_hash':                   ('splash', None),
-        'icon_hash':                     ('icon', None),
-        'avatar_hash':                   ('avatar', None),
+        'splash_hash':                   ('splash', _guild_hash_transformer('splashes')),
+        'banner_hash':                   ('banner', _guild_hash_transformer('banners')),
+        'discovery_splash_hash':         ('discovery_splash', _guild_hash_transformer('discovery-splashes')),
+        'icon_hash':                     ('icon', _transform_icon),
+        'avatar_hash':                   ('avatar', _transform_avatar),
         'rate_limit_per_user':           ('slowmode_delay', None),
-        'default_message_notifications': ('default_notifications', _transform_default_notifications),
+        'guild_id':                      ('guild', _transform_guild_id),
+        'tags':                          ('emoji', None),
+        'default_message_notifications': ('default_notifications', _enum_transformer(enums.NotificationLevel)),
+        'region':                        (None, _enum_transformer(enums.VoiceRegion)),
+        'rtc_region':                    (None, _enum_transformer(enums.VoiceRegion)),
+        'video_quality_mode':            (None, _enum_transformer(enums.VideoQualityMode)),
+        'privacy_level':                 (None, _enum_transformer(enums.StagePrivacyLevel)),
+        'format_type':                   (None, _enum_transformer(enums.StickerFormatType)),
+        'type':                          (None, _transform_type),
     }
+    # fmt: on
 
-    def __init__(self, entry, data):
+    def __init__(self, entry: AuditLogEntry, data: List[AuditLogChangePayload]):
         self.before = AuditLogDiff()
         self.after = AuditLogDiff()
 
@@ -132,18 +221,22 @@ class AuditLogChanges:
 
             # special cases for role add/remove
             if attr == '$add':
-                self._handle_role(self.before, self.after, entry, elem['new_value'])
+                self._handle_role(self.before, self.after, entry, elem['new_value'])  # type: ignore
                 continue
             elif attr == '$remove':
-                self._handle_role(self.after, self.before, entry, elem['new_value'])
+                self._handle_role(self.after, self.before, entry, elem['new_value'])  # type: ignore
                 continue
 
-            transformer = self.TRANSFORMERS.get(attr)
-            if transformer:
-                key, transformer = transformer
+            try:
+                key, transformer = self.TRANSFORMERS[attr]
+            except (ValueError, KeyError):
+                transformer = None
+            else:
                 if key:
                     attr = key
 
+            transformer: Optional[Transformer]
+
             try:
                 before = elem['old_value']
             except KeyError:
@@ -168,16 +261,19 @@ class AuditLogChanges:
         if hasattr(self.after, 'colour'):
             self.after.color = self.after.colour
             self.before.color = self.before.colour
+        if hasattr(self.after, 'expire_behavior'):
+            self.after.expire_behaviour = self.after.expire_behavior
+            self.before.expire_behaviour = self.before.expire_behavior
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f'<AuditLogChanges before={self.before!r} after={self.after!r}>'
 
-    def _handle_role(self, first, second, entry, elem):
+    def _handle_role(self, first: AuditLogDiff, second: AuditLogDiff, entry: AuditLogEntry, elem: List[RolePayload]) -> None:
         if not hasattr(first, 'roles'):
             setattr(first, 'roles', [])
 
         data = []
-        g = entry.guild
+        g: Guild = entry.guild  # type: ignore
 
         for e in elem:
             role_id = int(e['id'])
@@ -185,12 +281,36 @@ class AuditLogChanges:
 
             if role is None:
                 role = Object(id=role_id)
-                role.name = e['name']
+                role.name = e['name']  # type: ignore
 
             data.append(role)
 
         setattr(second, 'roles', data)
 
+
+class _AuditLogProxyMemberPrune:
+    delete_member_days: int
+    members_removed: int
+
+
+class _AuditLogProxyMemberMoveOrMessageDelete:
+    channel: abc.GuildChannel
+    count: int
+
+
+class _AuditLogProxyMemberDisconnect:
+    count: int
+
+
+class _AuditLogProxyPinAction:
+    channel: abc.GuildChannel
+    message_id: int
+
+
+class _AuditLogProxyStageInstanceAction:
+    channel: abc.GuildChannel
+
+
 class AuditLogEntry(Hashable):
     r"""Represents an Audit Log entry.
 
@@ -210,6 +330,10 @@ class AuditLogEntry(Hashable):
 
             Returns the entry's hash.
 
+        .. describe:: int(x)
+
+            Returns the entry's ID.
+
     .. versionchanged:: 1.7
         Audit log entries are now comparable and hashable.
 
@@ -234,13 +358,13 @@ class AuditLogEntry(Hashable):
         which actions have this field filled out.
     """
 
-    def __init__(self, *, users, data, guild):
+    def __init__(self, *, users: Dict[int, User], data: AuditLogEntryPayload, guild: Guild):
         self._state = guild._state
         self.guild = guild
         self._users = users
         self._from_data(data)
 
-    def _from_data(self, data):
+    def _from_data(self, data: AuditLogEntryPayload) -> None:
         self.action = enums.try_enum(enums.AuditLogAction, data['action_type'])
         self.id = int(data['id'])
 
@@ -251,41 +375,58 @@ class AuditLogEntry(Hashable):
         if isinstance(self.action, enums.AuditLogAction) and self.extra:
             if self.action is enums.AuditLogAction.member_prune:
                 # member prune has two keys with useful information
-                self.extra = type('_AuditLogProxy', (), {k: int(v) for k, v in self.extra.items()})()
+                self.extra: _AuditLogProxyMemberPrune = type(
+                    '_AuditLogProxy', (), {k: int(v) for k, v in self.extra.items()}
+                )()
             elif self.action is enums.AuditLogAction.member_move or self.action is enums.AuditLogAction.message_delete:
                 channel_id = int(self.extra['channel_id'])
                 elems = {
                     'count': int(self.extra['count']),
-                    'channel': self.guild.get_channel(channel_id) or Object(id=channel_id)
+                    'channel': self.guild.get_channel(channel_id) or Object(id=channel_id),
                 }
-                self.extra = type('_AuditLogProxy', (), elems)()
+                self.extra: _AuditLogProxyMemberMoveOrMessageDelete = type('_AuditLogProxy', (), elems)()
             elif self.action is enums.AuditLogAction.member_disconnect:
                 # The member disconnect action has a dict with some information
                 elems = {
                     'count': int(self.extra['count']),
                 }
-                self.extra = type('_AuditLogProxy', (), elems)()
+                self.extra: _AuditLogProxyMemberDisconnect = type('_AuditLogProxy', (), elems)()
             elif self.action.name.endswith('pin'):
                 # the pin actions have a dict with some information
                 channel_id = int(self.extra['channel_id'])
-                message_id = int(self.extra['message_id'])
                 elems = {
                     'channel': self.guild.get_channel(channel_id) or Object(id=channel_id),
-                    'message_id': message_id
+                    'message_id': int(self.extra['message_id']),
                 }
-                self.extra = type('_AuditLogProxy', (), elems)()
+                self.extra: _AuditLogProxyPinAction = type('_AuditLogProxy', (), elems)()
             elif self.action.name.startswith('overwrite_'):
                 # the overwrite_ actions have a dict with some information
                 instance_id = int(self.extra['id'])
                 the_type = self.extra.get('type')
-                if the_type == 'member':
+                if the_type == '1':
                     self.extra = self._get_member(instance_id)
-                else:
+                elif the_type == '0':
                     role = self.guild.get_role(instance_id)
                     if role is None:
                         role = Object(id=instance_id)
-                        role.name = self.extra.get('role_name')
-                    self.extra = role
+                        role.name = self.extra.get('role_name')  # type: ignore
+                    self.extra: Role = role
+            elif self.action.name.startswith('stage_instance'):
+                channel_id = int(self.extra['channel_id'])
+                elems = {'channel': self.guild.get_channel(channel_id) or Object(id=channel_id)}
+                self.extra: _AuditLogProxyStageInstanceAction = type('_AuditLogProxy', (), elems)()
+
+        # fmt: off
+        self.extra: Union[
+            _AuditLogProxyMemberPrune,
+            _AuditLogProxyMemberMoveOrMessageDelete,
+            _AuditLogProxyMemberDisconnect,
+            _AuditLogProxyPinAction,
+            _AuditLogProxyStageInstanceAction,
+            Member, User, None,
+            Role,
+        ]
+        # fmt: on
 
         # this key is not present when the above is present, typically.
         # It's a list of { new_value: a, old_value: b, key: c }
@@ -294,22 +435,22 @@ class AuditLogEntry(Hashable):
         # into meaningful data when requested
         self._changes = data.get('changes', [])
 
-        self.user = self._get_member(utils._get_as_snowflake(data, 'user_id'))
+        self.user = self._get_member(utils._get_as_snowflake(data, 'user_id'))  # type: ignore
         self._target_id = utils._get_as_snowflake(data, 'target_id')
 
-    def _get_member(self, user_id):
+    def _get_member(self, user_id: int) -> Union[Member, User, None]:
         return self.guild.get_member(user_id) or self._users.get(user_id)
 
-    def __repr__(self):
-        return '<AuditLogEntry id={0.id} action={0.action} user={0.user!r}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<AuditLogEntry id={self.id} action={self.action} user={self.user!r}>'
 
     @utils.cached_property
-    def created_at(self):
+    def created_at(self) -> datetime.datetime:
         """:class:`datetime.datetime`: Returns the entry's creation time in UTC."""
         return utils.snowflake_time(self.id)
 
     @utils.cached_property
-    def target(self):
+    def target(self) -> Union[Guild, abc.GuildChannel, Member, User, Role, Invite, Emoji, StageInstance, GuildSticker, Thread, Object, None]:
         try:
             converter = getattr(self, '_convert_target_' + self.action.target_type)
         except AttributeError:
@@ -318,46 +459,40 @@ class AuditLogEntry(Hashable):
             return converter(self._target_id)
 
     @utils.cached_property
-    def category(self):
+    def category(self) -> enums.AuditLogActionCategory:
         """Optional[:class:`AuditLogActionCategory`]: The category of the action, if applicable."""
         return self.action.category
 
     @utils.cached_property
-    def changes(self):
+    def changes(self) -> AuditLogChanges:
         """:class:`AuditLogChanges`: The list of changes this entry has."""
         obj = AuditLogChanges(self, self._changes)
         del self._changes
         return obj
 
     @utils.cached_property
-    def before(self):
+    def before(self) -> AuditLogDiff:
         """:class:`AuditLogDiff`: The target's prior state."""
         return self.changes.before
 
     @utils.cached_property
-    def after(self):
+    def after(self) -> AuditLogDiff:
         """:class:`AuditLogDiff`: The target's subsequent state."""
         return self.changes.after
 
-    def _convert_target_guild(self, target_id):
+    def _convert_target_guild(self, target_id: int) -> Guild:
         return self.guild
 
-    def _convert_target_channel(self, target_id):
-        ch = self.guild.get_channel(target_id)
-        if ch is None:
-            return Object(id=target_id)
-        return ch
+    def _convert_target_channel(self, target_id: int) -> Union[abc.GuildChannel, Object]:
+        return self.guild.get_channel(target_id) or Object(id=target_id)
 
-    def _convert_target_user(self, target_id):
+    def _convert_target_user(self, target_id: int) -> Union[Member, User, None]:
         return self._get_member(target_id)
 
-    def _convert_target_role(self, target_id):
-        role = self.guild.get_role(target_id)
-        if role is None:
-            return Object(id=target_id)
-        return role
+    def _convert_target_role(self, target_id: int) -> Union[Role, Object]:
+        return self.guild.get_role(target_id) or Object(id=target_id)
 
-    def _convert_target_invite(self, target_id):
+    def _convert_target_invite(self, target_id: int) -> Invite:
         # invites have target_id set to null
         # so figure out which change has the full invite data
         changeset = self.before if self.action is enums.AuditLogAction.invite_delete else self.after
@@ -367,20 +502,27 @@ class AuditLogEntry(Hashable):
             'max_uses': changeset.max_uses,
             'code': changeset.code,
             'temporary': changeset.temporary,
-            'channel': changeset.channel,
             'uses': changeset.uses,
-            'guild': self.guild,
         }
 
-        obj = Invite(state=self._state, data=fake_payload)
+        obj = Invite(state=self._state, data=fake_payload, guild=self.guild, channel=changeset.channel)  # type: ignore
         try:
             obj.inviter = changeset.inviter
         except AttributeError:
             pass
         return obj
 
-    def _convert_target_emoji(self, target_id):
+    def _convert_target_emoji(self, target_id: int) -> Union[Emoji, Object]:
         return self._state.get_emoji(target_id) or Object(id=target_id)
 
-    def _convert_target_message(self, target_id):
+    def _convert_target_message(self, target_id: int) -> Union[Member, User, None]:
         return self._get_member(target_id)
+
+    def _convert_target_stage_instance(self, target_id: int) -> Union[StageInstance, Object]:
+        return self.guild.get_stage_instance(target_id) or Object(id=target_id)
+
+    def _convert_target_sticker(self, target_id: int) -> Union[GuildSticker, Object]:
+        return self._state.get_sticker(target_id) or Object(id=target_id)
+
+    def _convert_target_thread(self, target_id: int) -> Union[Thread, Object]:
+        return self.guild.get_thread(target_id) or Object(id=target_id)

discord/backoff.py

@@ -22,14 +22,20 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+
 import time
 import random
+from typing import Callable, Generic, Literal, TypeVar, overload, Union
+
+T = TypeVar('T', bool, Literal[True], Literal[False])
 
 __all__ = (
     'ExponentialBackoff',
 )
 
-class ExponentialBackoff:
+class ExponentialBackoff(Generic[T]):
     """An implementation of the exponential backoff algorithm
 
     Provides a convenient interface to implement an exponential backoff
@@ -51,21 +57,33 @@ class ExponentialBackoff:
         number in between may be returned.
     """
 
-    def __init__(self, base=1, *, integral=False):
-        self._base = base
+    def __init__(self, base: int = 1, *, integral: T = False):
+        self._base: int = base
 
-        self._exp = 0
-        self._max = 10
-        self._reset_time = base * 2 ** 11
-        self._last_invocation = time.monotonic()
+        self._exp: int = 0
+        self._max: int = 10
+        self._reset_time: int = base * 2 ** 11
+        self._last_invocation: float = time.monotonic()
 
         # Use our own random instance to avoid messing with global one
         rand = random.Random()
         rand.seed()
 
-        self._randfunc = rand.randrange if integral else rand.uniform
+        self._randfunc: Callable[..., Union[int, float]] = rand.randrange if integral else rand.uniform   # type: ignore
 
-    def delay(self):
+    @overload
+    def delay(self: ExponentialBackoff[Literal[False]]) -> float:
+        ...
+
+    @overload
+    def delay(self: ExponentialBackoff[Literal[True]]) -> int:
+        ...
+
+    @overload
+    def delay(self: ExponentialBackoff[bool]) -> Union[int, float]:
+        ...
+
+    def delay(self) -> Union[int, float]:
         """Compute the next delay
 
         Returns the next delay to wait according to the exponential

discord/colour.py

@@ -25,11 +25,23 @@ DEALINGS IN THE SOFTWARE.
 import colorsys
 import random
 
+from typing import (
+    Any,
+    Optional,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+)
+
 __all__ = (
     'Colour',
     'Color',
 )
 
+CT = TypeVar('CT', bound='Colour')
+
+
 class Colour:
     """Represents a Discord role colour. This class is similar
     to a (red, green, blue) :class:`tuple`.
@@ -54,6 +66,10 @@ class Colour:
 
              Returns the hex format for the colour.
 
+        .. describe:: int(x)
+
+             Returns the raw colour value.
+
     Attributes
     ------------
     value: :class:`int`
@@ -62,67 +78,70 @@ class Colour:
 
     __slots__ = ('value',)
 
-    def __init__(self, value):
+    def __init__(self, value: int):
         if not isinstance(value, int):
             raise TypeError(f'Expected int parameter, received {value.__class__.__name__} instead.')
 
-        self.value = value
+        self.value: int = value
 
-    def _get_byte(self, byte):
+    def _get_byte(self, byte: int) -> int:
         return (self.value >> (8 * byte)) & 0xff
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         return isinstance(other, Colour) and self.value == other.value
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f'#{self.value:0>6x}'
 
-    def __repr__(self):
+    def __int__(self) -> int:
+        return self.value
+
+    def __repr__(self) -> str:
         return f'<Colour value={self.value}>'
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.value)
 
     @property
-    def r(self):
+    def r(self) -> int:
         """:class:`int`: Returns the red component of the colour."""
         return self._get_byte(2)
 
     @property
-    def g(self):
+    def g(self) -> int:
         """:class:`int`: Returns the green component of the colour."""
         return self._get_byte(1)
 
     @property
-    def b(self):
+    def b(self) -> int:
         """:class:`int`: Returns the blue component of the colour."""
         return self._get_byte(0)
 
-    def to_rgb(self):
+    def to_rgb(self) -> Tuple[int, int, int]:
         """Tuple[:class:`int`, :class:`int`, :class:`int`]: Returns an (r, g, b) tuple representing the colour."""
         return (self.r, self.g, self.b)
 
     @classmethod
-    def from_rgb(cls, r, g, b):
+    def from_rgb(cls: Type[CT], r: int, g: int, b: int) -> CT:
         """Constructs a :class:`Colour` from an RGB tuple."""
         return cls((r << 16) + (g << 8) + b)
 
     @classmethod
-    def from_hsv(cls, h, s, v):
+    def from_hsv(cls: Type[CT], h: float, s: float, v: float) -> CT:
         """Constructs a :class:`Colour` from an HSV tuple."""
         rgb = colorsys.hsv_to_rgb(h, s, v)
         return cls.from_rgb(*(int(x * 255) for x in rgb))
 
     @classmethod
-    def default(cls):
+    def default(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0``."""
         return cls(0)
 
     @classmethod
-    def random(cls, *, seed=None):
+    def random(cls: Type[CT], *, seed: Optional[Union[int, str, float, bytes, bytearray]] = None) -> CT:
         """A factory method that returns a :class:`Colour` with a random hue.
 
         .. note::
@@ -143,125 +162,146 @@ class Colour:
         return cls.from_hsv(rand.random(), 1, 1)
 
     @classmethod
-    def teal(cls):
+    def teal(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x1abc9c``."""
         return cls(0x1abc9c)
 
     @classmethod
-    def dark_teal(cls):
+    def dark_teal(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x11806a``."""
         return cls(0x11806a)
 
     @classmethod
-    def green(cls):
+    def brand_green(cls: Type[CT]) -> CT:
+        """A factory method that returns a :class:`Colour` with a value of ``0x57F287``.
+
+        .. versionadded:: 2.0
+        """
+        return cls(0x57F287)
+
+    @classmethod
+    def green(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x2ecc71``."""
         return cls(0x2ecc71)
 
     @classmethod
-    def dark_green(cls):
+    def dark_green(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x1f8b4c``."""
         return cls(0x1f8b4c)
 
     @classmethod
-    def blue(cls):
+    def blue(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x3498db``."""
         return cls(0x3498db)
 
     @classmethod
-    def dark_blue(cls):
+    def dark_blue(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x206694``."""
         return cls(0x206694)
 
     @classmethod
-    def purple(cls):
+    def purple(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x9b59b6``."""
         return cls(0x9b59b6)
 
     @classmethod
-    def dark_purple(cls):
+    def dark_purple(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x71368a``."""
         return cls(0x71368a)
 
     @classmethod
-    def magenta(cls):
+    def magenta(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xe91e63``."""
         return cls(0xe91e63)
 
     @classmethod
-    def dark_magenta(cls):
+    def dark_magenta(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xad1457``."""
         return cls(0xad1457)
 
     @classmethod
-    def gold(cls):
+    def gold(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xf1c40f``."""
         return cls(0xf1c40f)
 
     @classmethod
-    def dark_gold(cls):
+    def dark_gold(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xc27c0e``."""
         return cls(0xc27c0e)
 
     @classmethod
-    def orange(cls):
+    def orange(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xe67e22``."""
         return cls(0xe67e22)
 
     @classmethod
-    def dark_orange(cls):
+    def dark_orange(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xa84300``."""
         return cls(0xa84300)
 
     @classmethod
-    def red(cls):
+    def brand_red(cls: Type[CT]) -> CT:
+        """A factory method that returns a :class:`Colour` with a value of ``0xED4245``.
+
+        .. versionadded:: 2.0
+        """
+        return cls(0xED4245)
+
+    @classmethod
+    def red(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0xe74c3c``."""
         return cls(0xe74c3c)
 
     @classmethod
-    def dark_red(cls):
+    def dark_red(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x992d22``."""
         return cls(0x992d22)
 
     @classmethod
-    def lighter_grey(cls):
+    def lighter_grey(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x95a5a6``."""
         return cls(0x95a5a6)
 
     lighter_gray = lighter_grey
 
     @classmethod
-    def dark_grey(cls):
+    def dark_grey(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x607d8b``."""
         return cls(0x607d8b)
 
     dark_gray = dark_grey
 
     @classmethod
-    def light_grey(cls):
+    def light_grey(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x979c9f``."""
         return cls(0x979c9f)
 
     light_gray = light_grey
 
     @classmethod
-    def darker_grey(cls):
+    def darker_grey(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x546e7a``."""
         return cls(0x546e7a)
 
     darker_gray = darker_grey
 
     @classmethod
-    def blurple(cls):
+    def og_blurple(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x7289da``."""
         return cls(0x7289da)
 
     @classmethod
-    def greyple(cls):
+    def blurple(cls: Type[CT]) -> CT:
+        """A factory method that returns a :class:`Colour` with a value of ``0x5865F2``."""
+        return cls(0x5865F2)
+
+    @classmethod
+    def greyple(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x99aab5``."""
         return cls(0x99aab5)
 
     @classmethod
-    def dark_theme(cls):
+    def dark_theme(cls: Type[CT]) -> CT:
         """A factory method that returns a :class:`Colour` with a value of ``0x36393F``.
         This will appear transparent on Discord's dark theme.
 
@@ -269,4 +309,30 @@ class Colour:
         """
         return cls(0x36393F)
 
+    @classmethod
+    def fuchsia(cls: Type[CT]) -> CT:
+        """A factory method that returns a :class:`Colour` with a value of ``0xEB459E``.
+
+        .. versionadded:: 2.0
+        """
+        return cls(0xEB459E)
+
+    @classmethod
+    def yellow(cls: Type[CT]) -> CT:
+        """A factory method that returns a :class:`Colour` with a value of ``0xFEE75C``.
+
+        .. versionadded:: 2.0
+        """
+        return cls(0xFEE75C)
+    
+    @classmethod
+    def dark_blurple(cls: Type[CT]) -> CT:
+        """A factory method that returns a :class:`Colour` with a value of ``0x4E5D94``.
+        This is the original Dark Blurple branding.
+
+        .. versionadded:: 2.0
+        """
+        return cls(0x4E5D94)
+
+
 Color = Colour

discord/components.py

@@ -0,0 +1,383 @@
+"""
+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
+
+from typing import Any, ClassVar, Dict, List, Optional, TYPE_CHECKING, Tuple, Type, TypeVar, Union
+from .enums import try_enum, ComponentType, ButtonStyle
+from .utils import get_slots, MISSING
+from .partial_emoji import PartialEmoji, _EmojiTag
+
+if TYPE_CHECKING:
+    from .types.components import (
+        Component as ComponentPayload,
+        ButtonComponent as ButtonComponentPayload,
+        SelectMenu as SelectMenuPayload,
+        SelectOption as SelectOptionPayload,
+        ActionRow as ActionRowPayload,
+    )
+    from .emoji import Emoji
+
+
+__all__ = (
+    'Component',
+    'ActionRow',
+    'Button',
+    'SelectMenu',
+    'SelectOption',
+)
+
+C = TypeVar('C', bound='Component')
+
+
+class Component:
+    """Represents a Discord Bot UI Kit Component.
+
+    Currently, the only components supported by Discord are:
+
+    - :class:`ActionRow`
+    - :class:`Button`
+    - :class:`SelectMenu`
+
+    This class is abstract and cannot be instantiated.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ------------
+    type: :class:`ComponentType`
+        The type of component.
+    """
+
+    __slots__: Tuple[str, ...] = ('type',)
+
+    __repr_info__: ClassVar[Tuple[str, ...]]
+    type: ComponentType
+
+    def __repr__(self) -> str:
+        attrs = ' '.join(f'{key}={getattr(self, key)!r}' for key in self.__repr_info__)
+        return f'<{self.__class__.__name__} {attrs}>'
+
+    @classmethod
+    def _raw_construct(cls: Type[C], **kwargs) -> C:
+        self: C = cls.__new__(cls)
+        for slot in get_slots(cls):
+            try:
+                value = kwargs[slot]
+            except KeyError:
+                pass
+            else:
+                setattr(self, slot, value)
+        return self
+
+    def to_dict(self) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+class ActionRow(Component):
+    """Represents a Discord Bot UI Kit Action Row.
+
+    This is a component that holds up to 5 children components in a row.
+
+    This inherits from :class:`Component`.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ------------
+    type: :class:`ComponentType`
+        The type of component.
+    children: List[:class:`Component`]
+        The children components that this holds, if any.
+    """
+
+    __slots__: Tuple[str, ...] = ('children',)
+
+    __repr_info__: ClassVar[Tuple[str, ...]] = __slots__
+
+    def __init__(self, data: ComponentPayload):
+        self.type: ComponentType = try_enum(ComponentType, data['type'])
+        self.children: List[Component] = [_component_factory(d) for d in data.get('components', [])]
+
+    def to_dict(self) -> ActionRowPayload:
+        return {
+            'type': int(self.type),
+            'components': [child.to_dict() for child in self.children],
+        }  # type: ignore
+
+
+class Button(Component):
+    """Represents a button from the Discord Bot UI Kit.
+
+    This inherits from :class:`Component`.
+
+    .. note::
+
+        The user constructible and usable type to create a button is :class:`discord.ui.Button`
+        not this one.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    style: :class:`.ButtonStyle`
+        The style of the button.
+    custom_id: Optional[:class:`str`]
+        The ID of the button that gets received during an interaction.
+        If this button is for a URL, it does not have a custom ID.
+    url: Optional[:class:`str`]
+        The URL this button sends you to.
+    disabled: :class:`bool`
+        Whether the button is disabled or not.
+    label: Optional[:class:`str`]
+        The label of the button, if any.
+    emoji: Optional[:class:`PartialEmoji`]
+        The emoji of the button, if available.
+    """
+
+    __slots__: Tuple[str, ...] = (
+        'style',
+        'custom_id',
+        'url',
+        'disabled',
+        'label',
+        'emoji',
+    )
+
+    __repr_info__: ClassVar[Tuple[str, ...]] = __slots__
+
+    def __init__(self, data: ButtonComponentPayload):
+        self.type: ComponentType = try_enum(ComponentType, data['type'])
+        self.style: ButtonStyle = try_enum(ButtonStyle, data['style'])
+        self.custom_id: Optional[str] = data.get('custom_id')
+        self.url: Optional[str] = data.get('url')
+        self.disabled: bool = data.get('disabled', False)
+        self.label: Optional[str] = data.get('label')
+        self.emoji: Optional[PartialEmoji]
+        try:
+            self.emoji = PartialEmoji.from_dict(data['emoji'])
+        except KeyError:
+            self.emoji = None
+
+    def to_dict(self) -> ButtonComponentPayload:
+        payload = {
+            'type': 2,
+            'style': int(self.style),
+            'label': self.label,
+            'disabled': self.disabled,
+        }
+        if self.custom_id:
+            payload['custom_id'] = self.custom_id
+
+        if self.url:
+            payload['url'] = self.url
+
+        if self.emoji:
+            payload['emoji'] = self.emoji.to_dict()
+
+        return payload  # type: ignore
+
+
+class SelectMenu(Component):
+    """Represents a select menu from the Discord Bot UI Kit.
+
+    A select menu is functionally the same as a dropdown, however
+    on mobile it renders a bit differently.
+
+    .. note::
+
+        The user constructible and usable type to create a select menu is
+        :class:`discord.ui.Select` not this one.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ------------
+    custom_id: Optional[:class:`str`]
+        The ID of the select menu that gets received during an interaction.
+    placeholder: Optional[:class:`str`]
+        The placeholder text that is shown if nothing is selected, if any.
+    min_values: :class:`int`
+        The minimum number of items that must be chosen for this select menu.
+        Defaults to 1 and must be between 1 and 25.
+    max_values: :class:`int`
+        The maximum number of items that must be chosen for this select menu.
+        Defaults to 1 and must be between 1 and 25.
+    options: List[:class:`SelectOption`]
+        A list of options that can be selected in this menu.
+    disabled: :class:`bool`
+        Whether the select is disabled or not.
+    """
+
+    __slots__: Tuple[str, ...] = (
+        'custom_id',
+        'placeholder',
+        'min_values',
+        'max_values',
+        'options',
+        'disabled',
+    )
+
+    __repr_info__: ClassVar[Tuple[str, ...]] = __slots__
+
+    def __init__(self, data: SelectMenuPayload):
+        self.type = ComponentType.select
+        self.custom_id: str = data['custom_id']
+        self.placeholder: Optional[str] = data.get('placeholder')
+        self.min_values: int = data.get('min_values', 1)
+        self.max_values: int = data.get('max_values', 1)
+        self.options: List[SelectOption] = [SelectOption.from_dict(option) for option in data.get('options', [])]
+        self.disabled: bool = data.get('disabled', False)
+
+    def to_dict(self) -> SelectMenuPayload:
+        payload: SelectMenuPayload = {
+            'type': self.type.value,
+            'custom_id': self.custom_id,
+            'min_values': self.min_values,
+            'max_values': self.max_values,
+            'options': [op.to_dict() for op in self.options],
+            'disabled': self.disabled,
+        }
+
+        if self.placeholder:
+            payload['placeholder'] = self.placeholder
+
+        return payload
+
+
+class SelectOption:
+    """Represents a select menu's option.
+
+    These can be created by users.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    label: :class:`str`
+        The label of the option. This is displayed to users.
+        Can only be up to 100 characters.
+    value: :class:`str`
+        The value of the option. This is not displayed to users.
+        If not provided when constructed then it defaults to the
+        label. Can only be up to 100 characters.
+    description: Optional[:class:`str`]
+        An additional description of the option, if any.
+        Can only be up to 100 characters.
+    emoji: Optional[Union[:class:`str`, :class:`Emoji`, :class:`PartialEmoji`]]
+        The emoji of the option, if available.
+    default: :class:`bool`
+        Whether this option is selected by default.
+    """
+
+    __slots__: Tuple[str, ...] = (
+        'label',
+        'value',
+        'description',
+        'emoji',
+        'default',
+    )
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        value: str = MISSING,
+        description: Optional[str] = None,
+        emoji: Optional[Union[str, Emoji, PartialEmoji]] = None,
+        default: bool = False,
+    ) -> None:
+        self.label = label
+        self.value = label if value is MISSING else value
+        self.description = description
+
+        if emoji is not None:
+            if isinstance(emoji, str):
+                emoji = PartialEmoji.from_str(emoji)
+            elif isinstance(emoji, _EmojiTag):
+                emoji = emoji._to_partial()
+            else:
+                raise TypeError(f'expected emoji to be str, Emoji, or PartialEmoji not {emoji.__class__}')
+
+        self.emoji = emoji
+        self.default = default
+
+    def __repr__(self) -> str:
+        return (
+            f'<SelectOption label={self.label!r} value={self.value!r} description={self.description!r} '
+            f'emoji={self.emoji!r} default={self.default!r}>'
+        )
+
+    def __str__(self) -> str:
+        if self.emoji:
+            base = f'{self.emoji} {self.label}'
+        else:
+            base = self.label
+
+        if self.description:
+            return f'{base}\n{self.description}'
+        return base
+
+    @classmethod
+    def from_dict(cls, data: SelectOptionPayload) -> SelectOption:
+        try:
+            emoji = PartialEmoji.from_dict(data['emoji'])
+        except KeyError:
+            emoji = None
+
+        return cls(
+            label=data['label'],
+            value=data['value'],
+            description=data.get('description'),
+            emoji=emoji,
+            default=data.get('default', False),
+        )
+
+    def to_dict(self) -> SelectOptionPayload:
+        payload: SelectOptionPayload = {
+            'label': self.label,
+            'value': self.value,
+            'default': self.default,
+        }
+
+        if self.emoji:
+            payload['emoji'] = self.emoji.to_dict()  # type: ignore
+
+        if self.description:
+            payload['description'] = self.description
+
+        return payload
+
+
+def _component_factory(data: ComponentPayload) -> Component:
+    component_type = data['type']
+    if component_type == 1:
+        return ActionRow(data)
+    elif component_type == 2:
+        return Button(data)  # type: ignore
+    elif component_type == 3:
+        return SelectMenu(data)  # type: ignore
+    else:
+        as_enum = try_enum(ComponentType, component_type)
+        return Component._raw_construct(type=as_enum)

discord/context_managers.py

@@ -22,13 +22,23 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 import asyncio
+from typing import TYPE_CHECKING, TypeVar, Optional, Type
+
+if TYPE_CHECKING:
+    from .abc import Messageable
+
+    from types import TracebackType
+
+    TypingT = TypeVar('TypingT', bound='Typing')
 
 __all__ = (
     'Typing',
 )
 
-def _typing_done_callback(fut):
+def _typing_done_callback(fut: asyncio.Future) -> None:
     # just retrieve any exception and call it a day
     try:
         fut.exception()
@@ -36,11 +46,11 @@ def _typing_done_callback(fut):
         pass
 
 class Typing:
-    def __init__(self, messageable):
-        self.loop = messageable._state.loop
-        self.messageable = messageable
+    def __init__(self, messageable: Messageable) -> None:
+        self.loop: asyncio.AbstractEventLoop = messageable._state.loop
+        self.messageable: Messageable = messageable
 
-    async def do_typing(self):
+    async def do_typing(self) -> None:
         try:
             channel = self._channel
         except AttributeError:
@@ -52,18 +62,26 @@ class Typing:
             await typing(channel.id)
             await asyncio.sleep(5)
 
-    def __enter__(self):
-        self.task = asyncio.ensure_future(self.do_typing(), loop=self.loop)
+    def __enter__(self: TypingT) -> TypingT:
+        self.task: asyncio.Task = self.loop.create_task(self.do_typing())
         self.task.add_done_callback(_typing_done_callback)
         return self
 
-    def __exit__(self, exc_type, exc, tb):
+    def __exit__(self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
         self.task.cancel()
 
-    async def __aenter__(self):
+    async def __aenter__(self: TypingT) -> TypingT:
         self._channel = channel = await self.messageable._get_channel()
         await channel._state.http.send_typing(channel.id)
         return self.__enter__()
 
-    async def __aexit__(self, exc_type, exc, tb):
+    async def __aexit__(self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
         self.task.cancel()

discord/embeds.py

@@ -25,7 +25,7 @@ DEALINGS IN THE SOFTWARE.
 from __future__ import annotations
 
 import datetime
-from typing import Any, Dict, Final, List, Protocol, TYPE_CHECKING, Type, TypeVar, Union
+from typing import Any, Dict, Final, List, Mapping, Protocol, TYPE_CHECKING, Type, TypeVar, Union
 
 from . import utils
 from .colour import Colour
@@ -72,30 +72,36 @@ if TYPE_CHECKING:
     T = TypeVar('T')
     MaybeEmpty = Union[T, _EmptyEmbed]
 
+
     class _EmbedFooterProxy(Protocol):
         text: MaybeEmpty[str]
         icon_url: MaybeEmpty[str]
 
+
     class _EmbedFieldProxy(Protocol):
         name: MaybeEmpty[str]
         value: MaybeEmpty[str]
         inline: bool
 
+
     class _EmbedMediaProxy(Protocol):
         url: MaybeEmpty[str]
         proxy_url: MaybeEmpty[str]
         height: MaybeEmpty[int]
         width: MaybeEmpty[int]
 
+
     class _EmbedVideoProxy(Protocol):
         url: MaybeEmpty[str]
         height: MaybeEmpty[int]
         width: MaybeEmpty[int]
 
+
     class _EmbedProviderProxy(Protocol):
         name: MaybeEmpty[str]
         url: MaybeEmpty[str]
 
+
     class _EmbedAuthorProxy(Protocol):
         name: MaybeEmpty[str]
         url: MaybeEmpty[str]
@@ -175,15 +181,15 @@ class Embed:
     Empty: Final = EmptyEmbed
 
     def __init__(
-        self,
-        *,
-        colour: Union[int, Colour, _EmptyEmbed] = EmptyEmbed,
-        color: Union[int, Colour, _EmptyEmbed] = EmptyEmbed,
-        title: MaybeEmpty[str] = EmptyEmbed,
-        type: EmbedType = 'rich',
-        url: MaybeEmpty[str] = EmptyEmbed,
-        description: MaybeEmpty[str] = EmptyEmbed,
-        timestamp: datetime.datetime = None,
+            self,
+            *,
+            colour: Union[int, Colour, _EmptyEmbed] = EmptyEmbed,
+            color: Union[int, Colour, _EmptyEmbed] = EmptyEmbed,
+            title: MaybeEmpty[Any] = EmptyEmbed,
+            type: EmbedType = 'rich',
+            url: MaybeEmpty[Any] = EmptyEmbed,
+            description: MaybeEmpty[Any] = EmptyEmbed,
+            timestamp: datetime.datetime = None,
     ):
 
         self.colour = colour if colour is not EmptyEmbed else color
@@ -202,12 +208,10 @@ class Embed:
             self.url = str(self.url)
 
         if timestamp:
-            if timestamp.tzinfo is None:
-                timestamp = timestamp.astimezone()
             self.timestamp = timestamp
 
     @classmethod
-    def from_dict(cls: Type[E], data: EmbedData) -> E:
+    def from_dict(cls: Type[E], data: Mapping[str, Any]) -> E:
         """Converts a :class:`dict` to a :class:`Embed` provided it is in the
         format that Discord expects it to be in.
 
@@ -273,11 +277,11 @@ class Embed:
             total += len(field['name']) + len(field['value'])
 
         try:
-            footer = self._footer
-        except AttributeError:
+            footer_text = self._footer['text']
+        except (AttributeError, KeyError):
             pass
         else:
-            total += len(footer['text'])
+            total += len(footer_text)
 
         try:
             author = self._author
@@ -327,7 +331,11 @@ class Embed:
 
     @timestamp.setter
     def timestamp(self, value: MaybeEmpty[datetime.datetime]):
-        if isinstance(value, (datetime.datetime, _EmptyEmbed)):
+        if isinstance(value, datetime.datetime):
+            if value.tzinfo is None:
+                value = value.astimezone()
+            self._timestamp = value
+        elif isinstance(value, _EmptyEmbed):
             self._timestamp = value
         else:
             raise TypeError(f"Expected datetime.datetime or Embed.Empty received {value.__class__.__name__} instead")
@@ -342,7 +350,7 @@ class Embed:
         """
         return EmbedProxy(getattr(self, '_footer', {}))  # type: ignore
 
-    def set_footer(self: E, *, text: MaybeEmpty[str] = EmptyEmbed, icon_url: MaybeEmpty[str] = EmptyEmbed) -> E:
+    def set_footer(self: E, *, text: MaybeEmpty[Any] = EmptyEmbed, icon_url: MaybeEmpty[Any] = EmptyEmbed) -> E:
         """Sets the footer for the embed content.
 
         This function returns the class instance to allow for fluent-style
@@ -365,6 +373,21 @@ class Embed:
 
         return self
 
+    def remove_footer(self: E) -> E:
+        """Clears embed's footer information.
+
+        This function returns the class instance to allow for fluent-style
+        chaining.
+
+        .. versionadded:: 2.0
+        """
+        try:
+            del self._footer
+        except AttributeError:
+            pass
+
+        return self
+
     @property
     def image(self) -> _EmbedMediaProxy:
         """Returns an ``EmbedProxy`` denoting the image contents.
@@ -380,7 +403,20 @@ class Embed:
         """
         return EmbedProxy(getattr(self, '_image', {}))  # type: ignore
 
-    def set_image(self: E, *, url: MaybeEmpty[str]) -> E:
+    @image.setter
+    def image(self: E, *, url: Any):
+        self._image = {
+            'url': str(url),
+        }
+
+    @image.deleter
+    def image(self: E):
+        try:
+            del self._image
+        except AttributeError:
+            pass
+
+    def set_image(self: E, *, url: MaybeEmpty[Any]) -> E:
         """Sets the image for the embed content.
 
         This function returns the class instance to allow for fluent-style
@@ -396,14 +432,9 @@ class Embed:
         """
 
         if url is EmptyEmbed:
-            try:
-                del self._image
-            except AttributeError:
-                pass
+            del self.image
         else:
-            self._image = {
-                'url': str(url),
-            }
+            self.image = url
 
         return self
 
@@ -422,7 +453,25 @@ class Embed:
         """
         return EmbedProxy(getattr(self, '_thumbnail', {}))  # type: ignore
 
-    def set_thumbnail(self: E, *, url: MaybeEmpty[str]) -> E:
+    @thumbnail.setter
+    def thumbnail(self: E, *, url: Any):
+        """Sets the thumbnail for the embed content.
+        """
+
+        self._thumbnail = {
+            'url': str(url),
+        }
+
+        return
+
+    @thumbnail.deleter
+    def thumbnail(self):
+        try:
+            del self.thumbnail
+        except AttributeError:
+            pass
+
+    def set_thumbnail(self: E, *, url: MaybeEmpty[Any]):
         """Sets the thumbnail for the embed content.
 
         This function returns the class instance to allow for fluent-style
@@ -436,16 +485,10 @@ class Embed:
         url: :class:`str`
             The source URL for the thumbnail. Only HTTP(S) is supported.
         """
-
         if url is EmptyEmbed:
-            try:
-                del self._thumbnail
-            except AttributeError:
-                pass
+            del self.thumbnail
         else:
-            self._thumbnail = {
-                'url': str(url),
-            }
+            self.thumbnail = url
 
         return self
 
@@ -483,7 +526,7 @@ class Embed:
         """
         return EmbedProxy(getattr(self, '_author', {}))  # type: ignore
 
-    def set_author(self: E, *, name: str, url: MaybeEmpty[str] = EmptyEmbed, icon_url: MaybeEmpty[str] = EmptyEmbed) -> E:
+    def set_author(self: E, *, name: Any, url: MaybeEmpty[Any] = EmptyEmbed, icon_url: MaybeEmpty[Any] = EmptyEmbed) -> E:
         """Sets the author for the embed content.
 
         This function returns the class instance to allow for fluent-style
@@ -528,7 +571,7 @@ class Embed:
 
     @property
     def fields(self) -> List[_EmbedFieldProxy]:
-        """Union[List[:class:`EmbedProxy`], :attr:`Empty`]: Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
+        """List[Union[``EmbedProxy``, :attr:`Empty`]]: Returns a :class:`list` of ``EmbedProxy`` denoting the field contents.
 
         See :meth:`add_field` for possible values you can access.
 
@@ -536,7 +579,7 @@ class Embed:
         """
         return [EmbedProxy(d) for d in getattr(self, '_fields', [])]  # type: ignore
 
-    def add_field(self: E, *, name: str, value: str, inline: bool = True) -> E:
+    def add_field(self: E, *, name: Any, value: Any, inline: bool = True) -> E:
         """Adds a field to the embed object.
 
         This function returns the class instance to allow for fluent-style
@@ -565,7 +608,7 @@ class Embed:
 
         return self
 
-    def insert_field_at(self: E, index: int, *, name: str, value: str, inline: bool = True) -> E:
+    def insert_field_at(self: E, index: int, *, name: Any, value: Any, inline: bool = True) -> E:
         """Inserts a field before a specified index to the embed.
 
         This function returns the class instance to allow for fluent-style
@@ -626,7 +669,7 @@ class Embed:
         except (AttributeError, IndexError):
             pass
 
-    def set_field_at(self: E, index: int, *, name: str, value: str, inline: bool = True) -> E:
+    def set_field_at(self: E, index: int, *, name: Any, value: Any, inline: bool = True) -> E:
         """Modifies a field to the embed object.
 
         The index must point to a valid pre-existing field.

discord/emoji.py

@@ -22,16 +22,28 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
-from .asset import Asset
-from . import utils
-from .partial_emoji import _EmojiTag
+from __future__ import annotations
+from typing import Any, Iterator, List, Optional, TYPE_CHECKING, Tuple
+
+from .asset import Asset, AssetMixin
+from .utils import SnowflakeList, snowflake_time, MISSING
+from .partial_emoji import _EmojiTag, PartialEmoji
 from .user import User
 
 __all__ = (
     'Emoji',
 )
 
-class Emoji(_EmojiTag):
+if TYPE_CHECKING:
+    from .types.emoji import Emoji as EmojiPayload
+    from .guild import Guild
+    from .state import ConnectionState
+    from .abc import Snowflake
+    from .role import Role
+    from datetime import datetime
+
+
+class Emoji(_EmojiTag, AssetMixin):
     """Represents a custom emoji.
 
     Depending on the way this object was created, some of the attributes can
@@ -60,6 +72,10 @@ class Emoji(_EmojiTag):
 
             Returns the emoji rendered for discord.
 
+        .. describe:: int(x)
+
+            Returns the emoji ID.
+
     Attributes
     -----------
     name: :class:`str`
@@ -80,68 +96,79 @@ class Emoji(_EmojiTag):
         The user that created the emoji. This can only be retrieved using :meth:`Guild.fetch_emoji` and
         having the :attr:`~Permissions.manage_emojis` permission.
     """
-    __slots__ = ('require_colons', 'animated', 'managed', 'id', 'name', '_roles', 'guild_id',
-                 '_state', 'user', 'available')
 
-    def __init__(self, *, guild, state, data):
-        self.guild_id = guild.id
-        self._state = state
+    __slots__: Tuple[str, ...] = (
+        'require_colons',
+        'animated',
+        'managed',
+        'id',
+        'name',
+        '_roles',
+        'guild_id',
+        '_state',
+        'user',
+        'available',
+    )
+
+    def __init__(self, *, guild: Guild, state: ConnectionState, data: EmojiPayload):
+        self.guild_id: int = guild.id
+        self._state: ConnectionState = state
         self._from_data(data)
 
-    def _from_data(self, emoji):
-        self.require_colons = emoji['require_colons']
-        self.managed = emoji['managed']
-        self.id = int(emoji['id'])
-        self.name = emoji['name']
-        self.animated = emoji.get('animated', False)
-        self.available = emoji.get('available', True)
-        self._roles = utils.SnowflakeList(map(int, emoji.get('roles', [])))
+    def _from_data(self, emoji: EmojiPayload):
+        self.require_colons: bool = emoji.get('require_colons', False)
+        self.managed: bool = emoji.get('managed', False)
+        self.id: int = int(emoji['id'])  # type: ignore
+        self.name: str = emoji['name']  # type: ignore
+        self.animated: bool = emoji.get('animated', False)
+        self.available: bool = emoji.get('available', True)
+        self._roles: SnowflakeList = SnowflakeList(map(int, emoji.get('roles', [])))
         user = emoji.get('user')
-        self.user = User(state=self._state, data=user) if user else None
+        self.user: Optional[User] = User(state=self._state, data=user) if user else None
 
-    def _iterator(self):
+    def _to_partial(self) -> PartialEmoji:
+        return PartialEmoji(name=self.name, animated=self.animated, id=self.id)
+
+    def __iter__(self) -> Iterator[Tuple[str, Any]]:
         for attr in self.__slots__:
             if attr[0] != '_':
                 value = getattr(self, attr, None)
                 if value is not None:
                     yield (attr, value)
 
-    def __iter__(self):
-        return self._iterator()
-
-    def __str__(self):
+    def __str__(self) -> str:
         if self.animated:
-            return '<a:{0.name}:{0.id}>'.format(self)
-        return "<:{0.name}:{0.id}>".format(self)
+            return f'<a:{self.name}:{self.id}>'
+        return f'<:{self.name}:{self.id}>'
 
-    def __repr__(self):
-        return '<Emoji id={0.id} name={0.name!r} animated={0.animated} managed={0.managed}>'.format(self)
+    def __int__(self) -> int:
+        return self.id
 
-    def __eq__(self, other):
+    def __repr__(self) -> str:
+        return f'<Emoji id={self.id} name={self.name!r} animated={self.animated} managed={self.managed}>'
+
+    def __eq__(self, other: Any) -> bool:
         return isinstance(other, _EmojiTag) and self.id == other.id
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return self.id >> 22
 
     @property
-    def created_at(self):
+    def created_at(self) -> datetime:
         """:class:`datetime.datetime`: Returns the emoji's creation time in UTC."""
-        return utils.snowflake_time(self.id)
+        return snowflake_time(self.id)
 
     @property
-    def url(self):
-        """:class:`Asset`: Returns the asset of the emoji.
-
-        This is equivalent to calling :meth:`url_as` with
-        the default parameters (i.e. png/gif detection).
-        """
-        return self.url_as(format=None)
+    def url(self) -> str:
+        """:class:`str`: Returns the URL of the emoji."""
+        fmt = 'gif' if self.animated else 'png'
+        return f'{Asset.BASE}/emojis/{self.id}.{fmt}'
 
     @property
-    def roles(self):
+    def roles(self) -> List[Role]:
         """List[:class:`Role`]: A :class:`list` of roles that is allowed to use this emoji.
 
         If roles is empty, the emoji is unrestricted.
@@ -153,44 +180,11 @@ class Emoji(_EmojiTag):
         return [role for role in guild.roles if self._roles.has(role.id)]
 
     @property
-    def guild(self):
+    def guild(self) -> Guild:
         """:class:`Guild`: The guild this emoji belongs to."""
         return self._state._get_guild(self.guild_id)
 
-
-    def url_as(self, *, format=None, static_format="png"):
-        """Returns an :class:`Asset` for the emoji's url.
-
-        The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif'.
-        'gif' is only valid for animated emojis.
-
-        .. versionadded:: 1.6
-
-        Parameters
-        -----------
-        format: Optional[:class:`str`]
-            The format to attempt to convert the emojis to.
-            If the format is ``None``, then it is automatically
-            detected as either 'gif' or static_format, depending on whether the
-            emoji is animated or not.
-        static_format: Optional[:class:`str`]
-            Format to attempt to convert only non-animated emoji's to.
-            Defaults to 'png'
-
-        Raises
-        -------
-        InvalidArgument
-            Bad image format passed to ``format`` or ``static_format``.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_emoji(self._state, self, format=format, static_format=static_format)
-
-
-    def is_usable(self):
+    def is_usable(self) -> bool:
         """:class:`bool`: Whether the bot can use this emoji.
 
         .. versionadded:: 1.3
@@ -202,7 +196,7 @@ class Emoji(_EmojiTag):
         emoji_roles, my_roles = self._roles, self.guild.me._roles
         return any(my_roles.has(role_id) for role_id in emoji_roles)
 
-    async def delete(self, *, reason=None):
+    async def delete(self, *, reason: Optional[str] = None) -> None:
         """|coro|
 
         Deletes the custom emoji.
@@ -225,7 +219,7 @@ class Emoji(_EmojiTag):
 
         await self._state.http.delete_custom_emoji(self.guild.id, self.id, reason=reason)
 
-    async def edit(self, *, name=None, roles=None, reason=None):
+    async def edit(self, *, name: str = MISSING, roles: List[Snowflake] = MISSING, reason: Optional[str] = None) -> Emoji:
         r"""|coro|
 
         Edits the custom emoji.
@@ -233,12 +227,15 @@ class Emoji(_EmojiTag):
         You must have :attr:`~Permissions.manage_emojis` permission to
         do this.
 
+        .. versionchanged:: 2.0
+            The newly updated emoji is returned.
+
         Parameters
         -----------
         name: :class:`str`
             The new emoji name.
-        roles: Optional[list[:class:`Role`]]
-            A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone.
+        roles: Optional[List[:class:`~discord.abc.Snowflake`]]
+            A list of roles that can use this emoji. An empty list can be passed to make it available to everyone.
         reason: Optional[:class:`str`]
             The reason for editing this emoji. Shows up on the audit log.
 
@@ -248,9 +245,18 @@ class Emoji(_EmojiTag):
             You are not allowed to edit emojis.
         HTTPException
             An error occurred editing the emoji.
+
+        Returns
+        --------
+        :class:`Emoji`
+            The newly updated emoji.
         """
 
-        name = name or self.name
-        if roles:
-            roles = [role.id for role in roles]
-        await self._state.http.edit_custom_emoji(self.guild.id, self.id, name=name, roles=roles, reason=reason)
+        payload = {}
+        if name is not MISSING:
+            payload['name'] = name
+        if roles is not MISSING:
+            payload['roles'] = [role.id for role in roles]
+
+        data = await self._state.http.edit_custom_emoji(self.guild.id, self.id, payload=payload, reason=reason)
+        return Emoji(guild=self.guild, data=data, state=self._state)

discord/enums.py

@@ -24,7 +24,7 @@ DEALINGS IN THE SOFTWARE.
 
 import types
 from collections import namedtuple
-from typing import Any, TYPE_CHECKING, Type, TypeVar
+from typing import Any, ClassVar, Dict, List, Optional, TYPE_CHECKING, Type, TypeVar
 
 __all__ = (
     'Enum',
@@ -46,24 +46,46 @@ __all__ = (
     'ExpireBehaviour',
     'ExpireBehavior',
     'StickerType',
+    'StickerFormatType',
+    'InviteTarget',
+    'VideoQualityMode',
+    'ComponentType',
+    'ButtonStyle',
+    'StagePrivacyLevel',
+    'InteractionType',
+    'InteractionResponseType',
+    'NSFWLevel',
 )
 
-def _create_value_cls(name):
+
+def _create_value_cls(name, comparable):
     cls = namedtuple('_EnumValue_' + name, 'name value')
     cls.__repr__ = lambda self: f'<{name}.{self.name}: {self.value!r}>'
     cls.__str__ = lambda self: f'{name}.{self.name}'
+    if comparable:
+        cls.__le__ = lambda self, other: isinstance(other, self.__class__) and self.value <= other.value
+        cls.__ge__ = lambda self, other: isinstance(other, self.__class__) and self.value >= other.value
+        cls.__lt__ = lambda self, other: isinstance(other, self.__class__) and self.value < other.value
+        cls.__gt__ = lambda self, other: isinstance(other, self.__class__) and self.value > other.value
     return cls
 
 def _is_descriptor(obj):
     return hasattr(obj, '__get__') or hasattr(obj, '__set__') or hasattr(obj, '__delete__')
 
+
 class EnumMeta(type):
-    def __new__(cls, name, bases, attrs):
+    if TYPE_CHECKING:
+        __name__: ClassVar[str]
+        _enum_member_names_: ClassVar[List[str]]
+        _enum_member_map_: ClassVar[Dict[str, Any]]
+        _enum_value_map_: ClassVar[Dict[Any, Any]]
+
+    def __new__(cls, name, bases, attrs, *, comparable: bool = False):
         value_mapping = {}
         member_mapping = {}
         member_names = []
 
-        value_cls = _create_value_cls(name)
+        value_cls = _create_value_cls(name, comparable)
         for key, value in list(attrs.items()):
             is_descriptor = _is_descriptor(value)
             if key[0] == '_' and not is_descriptor:
@@ -93,7 +115,7 @@ class EnumMeta(type):
         attrs['_enum_member_names_'] = member_names
         attrs['_enum_value_cls_'] = value_cls
         actual_cls = super().__new__(cls, name, bases, attrs)
-        value_cls._actual_enum_cls_ = actual_cls
+        value_cls._actual_enum_cls_ = actual_cls  # type: ignore
         return actual_cls
 
     def __iter__(cls):
@@ -135,9 +157,11 @@ class EnumMeta(type):
         except AttributeError:
             return False
 
+
 if TYPE_CHECKING:
     from enum import Enum
 else:
+
     class Enum(metaclass=EnumMeta):
         @classmethod
         def try_value(cls, value):
@@ -146,72 +170,84 @@ else:
             except (KeyError, TypeError):
                 return value
 
+
 class ChannelType(Enum):
-    text     = 0
-    private  = 1
-    voice    = 2
-    group    = 3
+    text = 0
+    private = 1
+    voice = 2
+    group = 3
     category = 4
-    news     = 5
-    store    = 6
+    news = 5
+    store = 6
+    news_thread = 10
+    public_thread = 11
+    private_thread = 12
     stage_voice = 13
 
     def __str__(self):
         return self.name
 
+
 class MessageType(Enum):
-    default                                      = 0
-    recipient_add                                = 1
-    recipient_remove                             = 2
-    call                                         = 3
-    channel_name_change                          = 4
-    channel_icon_change                          = 5
-    pins_add                                     = 6
-    new_member                                   = 7
-    premium_guild_subscription                   = 8
-    premium_guild_tier_1                         = 9
-    premium_guild_tier_2                         = 10
-    premium_guild_tier_3                         = 11
-    channel_follow_add                           = 12
-    guild_stream                                 = 13
-    guild_discovery_disqualified                 = 14
-    guild_discovery_requalified                  = 15
+    default = 0
+    recipient_add = 1
+    recipient_remove = 2
+    call = 3
+    channel_name_change = 4
+    channel_icon_change = 5
+    pins_add = 6
+    new_member = 7
+    premium_guild_subscription = 8
+    premium_guild_tier_1 = 9
+    premium_guild_tier_2 = 10
+    premium_guild_tier_3 = 11
+    channel_follow_add = 12
+    guild_stream = 13
+    guild_discovery_disqualified = 14
+    guild_discovery_requalified = 15
     guild_discovery_grace_period_initial_warning = 16
-    guild_discovery_grace_period_final_warning   = 17
+    guild_discovery_grace_period_final_warning = 17
+    thread_created = 18
+    reply = 19
+    application_command = 20
+    thread_starter_message = 21
+    guild_invite_reminder = 22
+
 
 class VoiceRegion(Enum):
-    us_west       = 'us-west'
-    us_east       = 'us-east'
-    us_south      = 'us-south'
-    us_central    = 'us-central'
-    eu_west       = 'eu-west'
-    eu_central    = 'eu-central'
-    singapore     = 'singapore'
-    london        = 'london'
-    sydney        = 'sydney'
-    amsterdam     = 'amsterdam'
-    frankfurt     = 'frankfurt'
-    brazil        = 'brazil'
-    hongkong      = 'hongkong'
-    russia        = 'russia'
-    japan         = 'japan'
-    southafrica   = 'southafrica'
-    south_korea   = 'south-korea'
-    india         = 'india'
-    europe        = 'europe'
-    dubai         = 'dubai'
-    vip_us_east   = 'vip-us-east'
-    vip_us_west   = 'vip-us-west'
+    us_west = 'us-west'
+    us_east = 'us-east'
+    us_south = 'us-south'
+    us_central = 'us-central'
+    eu_west = 'eu-west'
+    eu_central = 'eu-central'
+    singapore = 'singapore'
+    london = 'london'
+    sydney = 'sydney'
+    amsterdam = 'amsterdam'
+    frankfurt = 'frankfurt'
+    brazil = 'brazil'
+    hongkong = 'hongkong'
+    russia = 'russia'
+    japan = 'japan'
+    southafrica = 'southafrica'
+    south_korea = 'south-korea'
+    india = 'india'
+    europe = 'europe'
+    dubai = 'dubai'
+    vip_us_east = 'vip-us-east'
+    vip_us_west = 'vip-us-west'
     vip_amsterdam = 'vip-amsterdam'
 
     def __str__(self):
         return self.value
 
+
 class SpeakingState(Enum):
-    none       = 0
-    voice      = 1
+    none = 0
+    voice = 1
     soundshare = 2
-    priority   = 4
+    priority = 4
 
     def __str__(self):
         return self.name
@@ -219,27 +255,27 @@ class SpeakingState(Enum):
     def __int__(self):
         return self.value
 
-class VerificationLevel(Enum):
-    none              = 0
-    low               = 1
-    medium            = 2
-    high              = 3
-    table_flip        = 3
-    extreme           = 4
-    double_table_flip = 4
-    very_high         = 4
+
+class VerificationLevel(Enum, comparable=True):
+    none = 0
+    low = 1
+    medium = 2
+    high = 3
+    highest = 4
 
     def __str__(self):
         return self.name
 
-class ContentFilter(Enum):
-    disabled    = 0
-    no_role     = 1
+
+class ContentFilter(Enum, comparable=True):
+    disabled = 0
+    no_role = 1
     all_members = 2
 
     def __str__(self):
         return self.name
 
+
 class Status(Enum):
     online = 'online'
     offline = 'offline'
@@ -251,27 +287,32 @@ class Status(Enum):
     def __str__(self):
         return self.value
 
+
 class DefaultAvatar(Enum):
     blurple = 0
-    grey    = 1
-    gray    = 1
-    green   = 2
-    orange  = 3
-    red     = 4
+    grey = 1
+    gray = 1
+    green = 2
+    orange = 3
+    red = 4
 
     def __str__(self):
         return self.name
 
-class NotificationLevel(Enum):
-    all_messages  = 0
+
+class NotificationLevel(Enum, comparable=True):
+    all_messages = 0
     only_mentions = 1
 
+
 class AuditLogActionCategory(Enum):
     create = 1
     delete = 2
     update = 3
 
+
 class AuditLogAction(Enum):
+    # fmt: off
     guild_update             = 1
     channel_create           = 10
     channel_update           = 11
@@ -307,50 +348,71 @@ class AuditLogAction(Enum):
     integration_create       = 80
     integration_update       = 81
     integration_delete       = 82
+    stage_instance_create    = 83
+    stage_instance_update    = 84
+    stage_instance_delete    = 85
+    sticker_create           = 90
+    sticker_update           = 91
+    sticker_delete           = 92
+    thread_create            = 110
+    thread_update            = 111
+    thread_delete            = 112
+    # fmt: on
 
     @property
-    def category(self):
-        lookup = {
-            AuditLogAction.guild_update:        AuditLogActionCategory.update,
-            AuditLogAction.channel_create:      AuditLogActionCategory.create,
-            AuditLogAction.channel_update:      AuditLogActionCategory.update,
-            AuditLogAction.channel_delete:      AuditLogActionCategory.delete,
-            AuditLogAction.overwrite_create:    AuditLogActionCategory.create,
-            AuditLogAction.overwrite_update:    AuditLogActionCategory.update,
-            AuditLogAction.overwrite_delete:    AuditLogActionCategory.delete,
-            AuditLogAction.kick:                None,
-            AuditLogAction.member_prune:        None,
-            AuditLogAction.ban:                 None,
-            AuditLogAction.unban:               None,
-            AuditLogAction.member_update:       AuditLogActionCategory.update,
-            AuditLogAction.member_role_update:  AuditLogActionCategory.update,
-            AuditLogAction.member_move:         None,
-            AuditLogAction.member_disconnect:   None,
-            AuditLogAction.bot_add:             None,
-            AuditLogAction.role_create:         AuditLogActionCategory.create,
-            AuditLogAction.role_update:         AuditLogActionCategory.update,
-            AuditLogAction.role_delete:         AuditLogActionCategory.delete,
-            AuditLogAction.invite_create:       AuditLogActionCategory.create,
-            AuditLogAction.invite_update:       AuditLogActionCategory.update,
-            AuditLogAction.invite_delete:       AuditLogActionCategory.delete,
-            AuditLogAction.webhook_create:      AuditLogActionCategory.create,
-            AuditLogAction.webhook_update:      AuditLogActionCategory.update,
-            AuditLogAction.webhook_delete:      AuditLogActionCategory.delete,
-            AuditLogAction.emoji_create:        AuditLogActionCategory.create,
-            AuditLogAction.emoji_update:        AuditLogActionCategory.update,
-            AuditLogAction.emoji_delete:        AuditLogActionCategory.delete,
-            AuditLogAction.message_delete:      AuditLogActionCategory.delete,
-            AuditLogAction.message_bulk_delete: AuditLogActionCategory.delete,
-            AuditLogAction.message_pin:         None,
-            AuditLogAction.message_unpin:       None,
-            AuditLogAction.integration_create:  AuditLogActionCategory.create,
-            AuditLogAction.integration_update:  AuditLogActionCategory.update,
-            AuditLogAction.integration_delete:  AuditLogActionCategory.delete,
+    def category(self) -> Optional[AuditLogActionCategory]:
+        # fmt: off
+        lookup: Dict[AuditLogAction, Optional[AuditLogActionCategory]] = {
+            AuditLogAction.guild_update:          AuditLogActionCategory.update,
+            AuditLogAction.channel_create:        AuditLogActionCategory.create,
+            AuditLogAction.channel_update:        AuditLogActionCategory.update,
+            AuditLogAction.channel_delete:        AuditLogActionCategory.delete,
+            AuditLogAction.overwrite_create:      AuditLogActionCategory.create,
+            AuditLogAction.overwrite_update:      AuditLogActionCategory.update,
+            AuditLogAction.overwrite_delete:      AuditLogActionCategory.delete,
+            AuditLogAction.kick:                  None,
+            AuditLogAction.member_prune:          None,
+            AuditLogAction.ban:                   None,
+            AuditLogAction.unban:                 None,
+            AuditLogAction.member_update:         AuditLogActionCategory.update,
+            AuditLogAction.member_role_update:    AuditLogActionCategory.update,
+            AuditLogAction.member_move:           None,
+            AuditLogAction.member_disconnect:     None,
+            AuditLogAction.bot_add:               None,
+            AuditLogAction.role_create:           AuditLogActionCategory.create,
+            AuditLogAction.role_update:           AuditLogActionCategory.update,
+            AuditLogAction.role_delete:           AuditLogActionCategory.delete,
+            AuditLogAction.invite_create:         AuditLogActionCategory.create,
+            AuditLogAction.invite_update:         AuditLogActionCategory.update,
+            AuditLogAction.invite_delete:         AuditLogActionCategory.delete,
+            AuditLogAction.webhook_create:        AuditLogActionCategory.create,
+            AuditLogAction.webhook_update:        AuditLogActionCategory.update,
+            AuditLogAction.webhook_delete:        AuditLogActionCategory.delete,
+            AuditLogAction.emoji_create:          AuditLogActionCategory.create,
+            AuditLogAction.emoji_update:          AuditLogActionCategory.update,
+            AuditLogAction.emoji_delete:          AuditLogActionCategory.delete,
+            AuditLogAction.message_delete:        AuditLogActionCategory.delete,
+            AuditLogAction.message_bulk_delete:   AuditLogActionCategory.delete,
+            AuditLogAction.message_pin:           None,
+            AuditLogAction.message_unpin:         None,
+            AuditLogAction.integration_create:    AuditLogActionCategory.create,
+            AuditLogAction.integration_update:    AuditLogActionCategory.update,
+            AuditLogAction.integration_delete:    AuditLogActionCategory.delete,
+            AuditLogAction.stage_instance_create: AuditLogActionCategory.create,
+            AuditLogAction.stage_instance_update: AuditLogActionCategory.update,
+            AuditLogAction.stage_instance_delete: AuditLogActionCategory.delete,
+            AuditLogAction.sticker_create:        AuditLogActionCategory.create,
+            AuditLogAction.sticker_update:        AuditLogActionCategory.update,
+            AuditLogAction.sticker_delete:        AuditLogActionCategory.delete,
+            AuditLogAction.thread_create:         AuditLogActionCategory.create,
+            AuditLogAction.thread_update:         AuditLogActionCategory.update,
+            AuditLogAction.thread_delete:         AuditLogActionCategory.delete,
         }
+        # fmt: on
         return lookup[self]
 
     @property
-    def target_type(self):
+    def target_type(self) -> Optional[str]:
         v = self.value
         if v == -1:
             return 'all'
@@ -368,10 +430,19 @@ class AuditLogAction(Enum):
             return 'webhook'
         elif v < 70:
             return 'emoji'
+        elif v == 73:
+            return 'channel'
         elif v < 80:
             return 'message'
-        elif v < 90:
+        elif v < 83:
             return 'integration'
+        elif v < 90:
+            return 'stage_instance'
+        elif v < 93:
+            return 'sticker'
+        elif v < 113:
+            return 'thread'
+
 
 class UserFlags(Enum):
     staff = 1
@@ -390,6 +461,8 @@ class UserFlags(Enum):
     bug_hunter_level_2 = 16384
     verified_bot = 65536
     verified_bot_developer = 131072
+    discord_certified_moderator = 262144
+
 
 class ActivityType(Enum):
     unknown = -1
@@ -403,36 +476,128 @@ class ActivityType(Enum):
     def __int__(self):
         return self.value
 
+
 class TeamMembershipState(Enum):
     invited = 1
     accepted = 2
 
+
 class WebhookType(Enum):
     incoming = 1
     channel_follower = 2
+    application = 3
+
 
 class ExpireBehaviour(Enum):
     remove_role = 0
     kick = 1
 
+
 ExpireBehavior = ExpireBehaviour
 
+
 class StickerType(Enum):
+    standard = 1
+    guild = 2
+
+
+class StickerFormatType(Enum):
     png = 1
     apng = 2
     lottie = 3
 
+    @property
+    def file_extension(self) -> str:
+        # fmt: off
+        lookup: Dict[StickerFormatType, str] = {
+            StickerFormatType.png: 'png',
+            StickerFormatType.apng: 'png',
+            StickerFormatType.lottie: 'json',
+        }
+        # fmt: on
+        return lookup[self]
+
+
+class InviteTarget(Enum):
+    unknown = 0
+    stream = 1
+    embedded_application = 2
+
+
 class InteractionType(Enum):
     ping = 1
     application_command = 2
+    component = 3
+
+
+class InteractionResponseType(Enum):
+    pong = 1
+    # ack = 2 (deprecated)
+    # channel_message = 3 (deprecated)
+    channel_message = 4  # (with source)
+    deferred_channel_message = 5  # (with source)
+    deferred_message_update = 6  # for components
+    message_update = 7  # for components
+
+
+class VideoQualityMode(Enum):
+    auto = 1
+    full = 2
+
+    def __int__(self):
+        return self.value
+
+
+class ComponentType(Enum):
+    action_row = 1
+    button = 2
+    select = 3
+
+    def __int__(self):
+        return self.value
+
+
+class ButtonStyle(Enum):
+    primary = 1
+    secondary = 2
+    success = 3
+    danger = 4
+    link = 5
+
+    # Aliases
+    blurple = 1
+    grey = 2
+    gray = 2
+    green = 3
+    red = 4
+    url = 5
+
+    def __int__(self):
+        return self.value
+
+
+class StagePrivacyLevel(Enum):
+    public = 1
+    closed = 2
+    guild_only = 2
+
+
+class NSFWLevel(Enum, comparable=True):
+    default = 0
+    explicit = 1
+    safe = 2
+    age_restricted = 3
+
 
 T = TypeVar('T')
 
+
 def create_unknown_value(cls: Type[T], val: Any) -> T:
-    value_cls = cls._enum_value_cls_ # type: ignore
+    value_cls = cls._enum_value_cls_  # type: ignore
     name = f'unknown_{val}'
     return value_cls(name=name, value=val)
 
+
 def try_enum(cls: Type[T], val: Any) -> T:
     """A function that tries to turn the value into enum ``cls``.
 
@@ -440,6 +605,6 @@ def try_enum(cls: Type[T], val: Any) -> T:
     """
 
     try:
-        return cls._enum_value_map_[val] # type: ignore
+        return cls._enum_value_map_[val]  # type: ignore
     except (KeyError, TypeError, AttributeError):
         return create_unknown_value(cls, val)

discord/errors.py

@@ -22,6 +22,21 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+from typing import Dict, List, Optional, TYPE_CHECKING, Any, Tuple, Union
+
+if TYPE_CHECKING:
+    from aiohttp import ClientResponse, ClientWebSocketResponse
+
+    try:
+        from requests import Response
+
+        _ResponseType = Union[ClientResponse, Response]
+    except ModuleNotFoundError:
+        _ResponseType = ClientResponse
+
+    from .interactions import Interaction
+
 __all__ = (
     'DiscordException',
     'ClientException',
@@ -36,44 +51,52 @@ __all__ = (
     'LoginFailure',
     'ConnectionClosed',
     'PrivilegedIntentsRequired',
+    'InteractionResponded',
 )
 
+
 class DiscordException(Exception):
     """Base exception class for discord.py
 
-    Ideally speaking, this could be caught to handle any exceptions thrown from this library.
+    Ideally speaking, this could be caught to handle any exceptions raised from this library.
     """
+
     pass
 
+
 class ClientException(DiscordException):
-    """Exception that's thrown when an operation in the :class:`Client` fails.
+    """Exception that's raised when an operation in the :class:`Client` fails.
 
     These are usually for exceptions that happened due to user input.
     """
+
     pass
 
+
 class NoMoreItems(DiscordException):
-    """Exception that is thrown when an async iteration operation has no more
-    items."""
+    """Exception that is raised when an async iteration operation has no more items."""
+
     pass
 
+
 class GatewayNotFound(DiscordException):
-    """An exception that is usually thrown when the gateway hub
-    for the :class:`Client` websocket is not found."""
+    """An exception that is raised when the gateway for Discord could not be found"""
+
     def __init__(self):
         message = 'The gateway to connect to discord was not found.'
         super().__init__(message)
 
-def flatten_error_dict(d, key=''):
-    items = []
+
+def _flatten_error_dict(d: Dict[str, Any], key: str = '') -> Dict[str, str]:
+    items: List[Tuple[str, str]] = []
     for k, v in d.items():
         new_key = key + '.' + k if key else k
 
         if isinstance(v, dict):
             try:
-                _errors = v['_errors']
+                _errors: List[Dict[str, Any]] = v['_errors']
             except KeyError:
-                items.extend(flatten_error_dict(v, new_key).items())
+                items.extend(_flatten_error_dict(v, new_key).items())
             else:
                 items.append((new_key, ' '.join(x.get('message', '') for x in _errors)))
         else:
@@ -81,8 +104,9 @@ def flatten_error_dict(d, key=''):
 
     return dict(items)
 
+
 class HTTPException(DiscordException):
-    """Exception that's thrown when an HTTP request operation fails.
+    """Exception that's raised when an HTTP request operation fails.
 
     Attributes
     ------------
@@ -99,21 +123,23 @@ class HTTPException(DiscordException):
         The Discord specific error code for the failure.
     """
 
-    def __init__(self, response, message):
-        self.response = response
-        self.status = response.status
+    def __init__(self, response: _ResponseType, message: Optional[Union[str, Dict[str, Any]]]):
+        self.response: _ResponseType = response
+        self.status: int = response.status  # type: ignore
+        self.code: int
+        self.text: str
         if isinstance(message, dict):
             self.code = message.get('code', 0)
             base = message.get('message', '')
             errors = message.get('errors')
             if errors:
-                errors = flatten_error_dict(errors)
+                errors = _flatten_error_dict(errors)
                 helpful = '\n'.join('In %s: %s' % t for t in errors.items())
                 self.text = base + '\n' + helpful
             else:
                 self.text = base
         else:
-            self.text = message
+            self.text = message or ''
             self.code = 0
 
         fmt = '{0.status} {0.reason} (error code: {1})'
@@ -122,54 +148,67 @@ class HTTPException(DiscordException):
 
         super().__init__(fmt.format(self.response, self.code, self.text))
 
+
 class Forbidden(HTTPException):
-    """Exception that's thrown for when status code 403 occurs.
+    """Exception that's raised for when status code 403 occurs.
 
     Subclass of :exc:`HTTPException`
     """
+
     pass
 
+
 class NotFound(HTTPException):
-    """Exception that's thrown for when status code 404 occurs.
+    """Exception that's raised for when status code 404 occurs.
 
     Subclass of :exc:`HTTPException`
     """
+
     pass
 
+
 class DiscordServerError(HTTPException):
-    """Exception that's thrown for when a 500 range status code occurs.
+    """Exception that's raised for when a 500 range status code occurs.
 
     Subclass of :exc:`HTTPException`.
 
     .. versionadded:: 1.5
     """
+
     pass
 
+
 class InvalidData(ClientException):
     """Exception that's raised when the library encounters unknown
     or invalid data from Discord.
     """
+
     pass
 
+
 class InvalidArgument(ClientException):
-    """Exception that's thrown when an argument to a function
+    """Exception that's raised when an argument to a function
     is invalid some way (e.g. wrong value or wrong type).
 
     This could be considered the analogous of ``ValueError`` and
     ``TypeError`` except inherited from :exc:`ClientException` and thus
     :exc:`DiscordException`.
     """
+
     pass
 
+
 class LoginFailure(ClientException):
-    """Exception that's thrown when the :meth:`Client.login` function
+    """Exception that's raised when the :meth:`Client.login` function
     fails to log you in from improper credentials or some other misc.
     failure.
     """
+
     pass
 
+
 class ConnectionClosed(ClientException):
-    """Exception that's thrown when the gateway connection is
+    """Exception that's raised when the gateway connection is
     closed for reasons that could not be handled internally.
 
     Attributes
@@ -181,17 +220,19 @@ class ConnectionClosed(ClientException):
     shard_id: Optional[:class:`int`]
         The shard ID that got closed if applicable.
     """
-    def __init__(self, socket, *, shard_id, code=None):
+
+    def __init__(self, socket: ClientWebSocketResponse, *, shard_id: Optional[int], code: Optional[int] = None):
         # This exception is just the same exception except
         # reconfigured to subclass ClientException for users
-        self.code = code or socket.close_code
+        self.code: int = code or socket.close_code or -1
         # aiohttp doesn't seem to consistently provide close reason
-        self.reason = ''
-        self.shard_id = shard_id
+        self.reason: str = ''
+        self.shard_id: Optional[int] = shard_id
         super().__init__(f'Shard ID {self.shard_id} WebSocket closed with {self.code}')
 
+
 class PrivilegedIntentsRequired(ClientException):
-    """Exception that's thrown when the gateway is requesting privileged intents
+    """Exception that's raised when the gateway is requesting privileged intents
     but they're not ticked in the developer page yet.
 
     Go to https://discord.com/developers/applications/ and enable the intents
@@ -206,10 +247,31 @@ class PrivilegedIntentsRequired(ClientException):
         The shard ID that got closed if applicable.
     """
 
-    def __init__(self, shard_id):
-        self.shard_id = shard_id
-        msg = 'Shard ID %s is requesting privileged intents that have not been explicitly enabled in the ' \
-              'developer portal. It is recommended to go to https://discord.com/developers/applications/ ' \
-              'and explicitly enable the privileged intents within your application\'s page. If this is not ' \
-              'possible, then consider disabling the privileged intents instead.'
+    def __init__(self, shard_id: Optional[int]):
+        self.shard_id: Optional[int] = shard_id
+        msg = (
+            'Shard ID %s is requesting privileged intents that have not been explicitly enabled in the '
+            'developer portal. It is recommended to go to https://discord.com/developers/applications/ '
+            'and explicitly enable the privileged intents within your application\'s page. If this is not '
+            'possible, then consider disabling the privileged intents instead.'
+        )
         super().__init__(msg % shard_id)
+
+
+class InteractionResponded(ClientException):
+    """Exception that's raised when sending another interaction response using
+    :class:`InteractionResponse` when one has already been done before.
+
+    An interaction can only respond once.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    interaction: :class:`Interaction`
+        The interaction that's already been responded to.
+    """
+
+    def __init__(self, interaction: Interaction):
+        self.interaction: Interaction = interaction
+        super().__init__('This interaction has already been responded to before')

discord/ext/commands/__init__.py

@@ -16,3 +16,4 @@ from .help import *
 from .converter import *
 from .cooldowns import *
 from .cog import *
+from .flags import *

discord/ext/commands/_types.py

@@ -22,6 +22,26 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+
+from typing import Any, Callable, Coroutine, TYPE_CHECKING, TypeVar, Union
+
+
+if TYPE_CHECKING:
+    from .context import Context
+    from .cog import Cog
+    from .errors import CommandError
+
+T = TypeVar('T')
+
+Coro = Coroutine[Any, Any, T]
+MaybeCoro = Union[T, Coro[T]]
+CoroFunc = Callable[..., Coro[Any]]
+
+Check = Union[Callable[["Cog", "Context[Any]"], MaybeCoro[bool]], Callable[["Context[Any]"], MaybeCoro[bool]]]
+Hook = Union[Callable[["Cog", "Context[Any]"], Coro[Any]], Callable[["Context[Any]"], Coro[Any]]]
+Error = Union[Callable[["Cog", "Context[Any]", "CommandError"], Coro[Any]], Callable[["Context[Any]", "CommandError"], Coro[Any]]]
+
+
 # This is merely a tag type to avoid circular import issues.
 # Yes, this is a terrible solution but ultimately it is the only solution.
 class _BaseCommand:

discord/ext/commands/bot.py

@@ -22,13 +22,18 @@ 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 collections
+import collections.abc
 import inspect
 import importlib.util
 import sys
 import traceback
 import types
+from typing import Any, Callable, Mapping, List, Dict, TYPE_CHECKING, Optional, TypeVar, Type, Union
 
 import discord
 
@@ -39,6 +44,15 @@ from . import errors
 from .help import HelpCommand, DefaultHelpCommand
 from .cog import Cog
 
+if TYPE_CHECKING:
+    import importlib.machinery
+
+    from discord.message import Message
+    from ._types import (
+        Check,
+        CoroFunc,
+    )
+
 __all__ = (
     'when_mentioned',
     'when_mentioned_or',
@@ -46,14 +60,21 @@ __all__ = (
     'AutoShardedBot',
 )
 
-def when_mentioned(bot, msg):
+MISSING: Any = discord.utils.MISSING
+
+T = TypeVar('T')
+CFT = TypeVar('CFT', bound='CoroFunc')
+CXT = TypeVar('CXT', bound='Context')
+
+def when_mentioned(bot: Union[Bot, AutoShardedBot], msg: Message) -> List[str]:
     """A callable that implements a command prefix equivalent to being mentioned.
 
     These are meant to be passed into the :attr:`.Bot.command_prefix` attribute.
     """
-    return [f'<@{bot.user.id}> ', f'<@!{bot.user.id}> ']
+    # bot.user will never be None when this is called
+    return [f'<@{bot.user.id}> ', f'<@!{bot.user.id}> ']  # type: ignore
 
-def when_mentioned_or(*prefixes):
+def when_mentioned_or(*prefixes: str) -> Callable[[Union[Bot, AutoShardedBot], Message], List[str]]:
     """A callable that implements when mentioned or other prefixes provided.
 
     These are meant to be passed into the :attr:`.Bot.command_prefix` attribute.
@@ -89,7 +110,7 @@ def when_mentioned_or(*prefixes):
 
     return inner
 
-def _is_submodule(parent, child):
+def _is_submodule(parent: str, child: str) -> bool:
     return parent == child or child.startswith(parent + ".")
 
 class _DefaultRepr:
@@ -99,13 +120,13 @@ class _DefaultRepr:
 _default = _DefaultRepr()
 
 class BotBase(GroupMixin):
-    def __init__(self, command_prefix, help_command=_default, description=None, **options):
-        super().__init__(**options)
+    def __init__(self, command_prefix, help_command=_default, description=None, *, intents: discord.Intents, **options):
+        super().__init__(**options, intents=intents)
         self.command_prefix = command_prefix
-        self.extra_events = {}
-        self.__cogs = {}
-        self.__extensions = {}
-        self._checks = []
+        self.extra_events: Dict[str, List[CoroFunc]] = {}
+        self.__cogs: Dict[str, Cog] = {}
+        self.__extensions: Dict[str, types.ModuleType] = {}
+        self._checks: List[Check] = []
         self._check_once = []
         self._before_invoke = None
         self._after_invoke = None
@@ -121,11 +142,6 @@ class BotBase(GroupMixin):
         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}')
 
-        if options.pop('self_bot', False):
-            self._skip_check = lambda x, y: x != y
-        else:
-            self._skip_check = lambda x, y: x == y
-
         if help_command is _default:
             self.help_command = DefaultHelpCommand()
         else:
@@ -133,13 +149,15 @@ class BotBase(GroupMixin):
 
     # internal helpers
 
-    def dispatch(self, event_name, *args, **kwargs):
-        super().dispatch(event_name, *args, **kwargs)
+    def dispatch(self, event_name: str, *args: Any, **kwargs: Any) -> None:
+        # super() will resolve to Client
+        super().dispatch(event_name, *args, **kwargs)  # type: ignore
         ev = 'on_' + event_name
         for event in self.extra_events.get(ev, []):
-            self._schedule_event(event, ev, *args, **kwargs)
+            self._schedule_event(event, ev, *args, **kwargs)  # type: ignore
 
-    async def close(self):
+    @discord.utils.copy_doc(discord.Client.close)
+    async def close(self) -> None:
         for extension in tuple(self.__extensions):
             try:
                 self.unload_extension(extension)
@@ -152,9 +170,9 @@ class BotBase(GroupMixin):
             except Exception:
                 pass
 
-        await super().close()
+        await super().close()  # type: ignore
 
-    async def on_command_error(self, context, exception):
+    async def on_command_error(self, context: Context, exception: errors.CommandError) -> None:
         """|coro|
 
         The default command error handler provided by the bot.
@@ -167,11 +185,12 @@ class BotBase(GroupMixin):
         if self.extra_events.get('on_command_error', None):
             return
 
-        if hasattr(context.command, 'on_error'):
+        command = context.command
+        if command and command.has_error_handler():
             return
 
         cog = context.cog
-        if cog and Cog._get_overridden_method(cog.cog_command_error) is not None:
+        if cog and cog.has_error_handler():
             return
 
         print(f'Ignoring exception in command {context.command}:', file=sys.stderr)
@@ -179,7 +198,7 @@ class BotBase(GroupMixin):
 
     # global check registration
 
-    def check(self, func):
+    def check(self, func: T) -> T:
         r"""A decorator that adds a global check to the bot.
 
         A global check is similar to a :func:`.check` that is applied
@@ -204,10 +223,11 @@ class BotBase(GroupMixin):
                 return ctx.command.qualified_name in allowed_commands
 
         """
-        self.add_check(func)
+        # T was used instead of Check to ensure the type matches on return
+        self.add_check(func)  # type: ignore
         return func
 
-    def add_check(self, func, *, call_once=False):
+    def add_check(self, func: Check, *, call_once: bool = False) -> None:
         """Adds a global check to the bot.
 
         This is the non-decorator interface to :meth:`.check`
@@ -219,7 +239,7 @@ class BotBase(GroupMixin):
             The function that was used as a global check.
         call_once: :class:`bool`
             If the function should only be called once per
-            :meth:`.Command.invoke` call.
+            :meth:`.invoke` call.
         """
 
         if call_once:
@@ -227,7 +247,7 @@ class BotBase(GroupMixin):
         else:
             self._checks.append(func)
 
-    def remove_check(self, func, *, call_once=False):
+    def remove_check(self, func: Check, *, call_once: bool = False) -> None:
         """Removes a global check from the bot.
 
         This function is idempotent and will not raise an exception
@@ -248,11 +268,11 @@ class BotBase(GroupMixin):
         except ValueError:
             pass
 
-    def check_once(self, func):
+    def check_once(self, func: CFT) -> CFT:
         r"""A decorator that adds a "call once" global check to the bot.
 
         Unlike regular global checks, this one is called only once
-        per :meth:`.Command.invoke` call.
+        per :meth:`.invoke` call.
 
         Regular global checks are called whenever a command is called
         or :meth:`.Command.can_run` is called. This type of check
@@ -286,15 +306,16 @@ class BotBase(GroupMixin):
         self.add_check(func, call_once=True)
         return func
 
-    async def can_run(self, ctx, *, call_once=False):
+    async def can_run(self, ctx: Context, *, call_once: bool = False) -> bool:
         data = self._check_once if call_once else self._checks
 
         if len(data) == 0:
             return True
 
-        return await discord.utils.async_all(f(ctx) for f in data)
+        # type-checker doesn't distinguish between functions and methods
+        return await discord.utils.async_all(f(ctx) for f in data)  # type: ignore
 
-    async def is_owner(self, user):
+    async def is_owner(self, user: discord.User) -> bool:
         """|coro|
 
         Checks if a :class:`~discord.User` or :class:`~discord.Member` is the owner of
@@ -323,7 +344,8 @@ class BotBase(GroupMixin):
         elif self.owner_ids:
             return user.id in self.owner_ids
         else:
-            app = await self.application_info()
+
+            app = await self.application_info()  # type: ignore
             if app.team:
                 self.owner_ids = ids = {m.id for m in app.team.members}
                 return user.id in ids
@@ -331,7 +353,7 @@ class BotBase(GroupMixin):
                 self.owner_id = owner_id = app.owner.id
                 return user.id == owner_id
 
-    def before_invoke(self, coro):
+    def before_invoke(self, coro: CFT) -> CFT:
         """A decorator that registers a coroutine as a pre-invoke hook.
 
         A pre-invoke hook is called directly before the command is
@@ -363,7 +385,7 @@ class BotBase(GroupMixin):
         self._before_invoke = coro
         return coro
 
-    def after_invoke(self, coro):
+    def after_invoke(self, coro: CFT) -> CFT:
         r"""A decorator that registers a coroutine as a post-invoke hook.
 
         A post-invoke hook is called directly after the command is
@@ -398,14 +420,14 @@ class BotBase(GroupMixin):
 
     # listener registration
 
-    def add_listener(self, func, name=None):
+    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: Optional[:class:`str`]
+        name: :class:`str`
             The name of the event to listen for. Defaults to ``func.__name__``.
 
         Example
@@ -420,7 +442,7 @@ class BotBase(GroupMixin):
             bot.add_listener(my_message, 'on_message')
 
         """
-        name = func.__name__ if name is None else name
+        name = func.__name__ if name is MISSING else name
 
         if not asyncio.iscoroutinefunction(func):
             raise TypeError('Listeners must be coroutines')
@@ -430,7 +452,7 @@ class BotBase(GroupMixin):
         else:
             self.extra_events[name] = [func]
 
-    def remove_listener(self, func, name=None):
+    def remove_listener(self, func: CoroFunc, name: str = MISSING) -> None:
         """Removes a listener from the pool of listeners.
 
         Parameters
@@ -442,7 +464,7 @@ class BotBase(GroupMixin):
             ``func.__name__``.
         """
 
-        name = func.__name__ if name is None else name
+        name = func.__name__ if name is MISSING else name
 
         if name in self.extra_events:
             try:
@@ -450,7 +472,7 @@ class BotBase(GroupMixin):
             except ValueError:
                 pass
 
-    def listen(self, name=None):
+    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`
@@ -480,7 +502,7 @@ class BotBase(GroupMixin):
             The function being listened to is not a coroutine.
         """
 
-        def decorator(func):
+        def decorator(func: CFT) -> CFT:
             self.add_listener(func, name)
             return func
 
@@ -488,15 +510,25 @@ class BotBase(GroupMixin):
 
     # cogs
 
-    def add_cog(self, cog):
+    def add_cog(self, cog: Cog, *, override: bool = False) -> None:
         """Adds a "cog" to the bot.
 
         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 to the bot.
+        override: :class:`bool`
+            If a previously loaded cog with the same name should be ejected
+            instead of raising an error.
+
+            .. versionadded:: 2.0
 
         Raises
         -------
@@ -504,15 +536,25 @@ class BotBase(GroupMixin):
             The cog does not inherit from :class:`.Cog`.
         CommandError
             An error happened during loading.
+        .ClientException
+            A cog with the same name is already loaded.
         """
 
         if not isinstance(cog, Cog):
             raise TypeError('cogs must derive from Cog')
 
-        cog = cog._inject(self)
-        self.__cogs[cog.__cog_name__] = cog
+        cog_name = cog.__cog_name__
+        existing = self.__cogs.get(cog_name)
 
-    def get_cog(self, name):
+        if existing is not None:
+            if not override:
+                raise discord.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.
@@ -531,8 +573,8 @@ class BotBase(GroupMixin):
         """
         return self.__cogs.get(name)
 
-    def remove_cog(self, name):
-        """Removes a cog from the bot.
+    def remove_cog(self, name: str) -> Optional[Cog]:
+        """Removes a cog from the bot and returns it.
 
         All registered commands and event listeners that the
         cog has registered will be removed as well.
@@ -543,6 +585,11 @@ class BotBase(GroupMixin):
         -----------
         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)
@@ -554,14 +601,16 @@ class BotBase(GroupMixin):
             help_command.cog = None
         cog._eject(self)
 
+        return cog
+
     @property
-    def cogs(self):
+    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):
+    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():
@@ -585,7 +634,7 @@ class BotBase(GroupMixin):
             for index in reversed(remove):
                 del event_list[index]
 
-    def _call_module_finalizers(self, lib, key):
+    def _call_module_finalizers(self, lib: types.ModuleType, key: str) -> None:
         try:
             func = getattr(lib, 'teardown')
         except AttributeError:
@@ -603,12 +652,12 @@ class BotBase(GroupMixin):
                 if _is_submodule(name, module):
                     del sys.modules[module]
 
-    def _load_from_module_spec(self, spec, key):
+    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)
+            spec.loader.exec_module(lib)  # type: ignore
         except Exception as e:
             del sys.modules[key]
             raise errors.ExtensionFailed(key, e) from e
@@ -629,13 +678,13 @@ class BotBase(GroupMixin):
         else:
             self.__extensions[key] = lib
 
-    def _resolve_name(self, name, package):
+    def _resolve_name(self, name: str, package: Optional[str]) -> str:
         try:
             return importlib.util.resolve_name(name, package)
         except ImportError:
             raise errors.ExtensionNotFound(name)
 
-    def load_extension(self, name, *, package=None):
+    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
@@ -682,7 +731,7 @@ class BotBase(GroupMixin):
 
         self._load_from_module_spec(spec, name)
 
-    def unload_extension(self, name, *, package=None):
+    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
@@ -723,7 +772,7 @@ class BotBase(GroupMixin):
         self._remove_module_references(lib.__name__)
         self._call_module_finalizers(lib, name)
 
-    def reload_extension(self, name, *, package=None):
+    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
@@ -779,7 +828,7 @@ class BotBase(GroupMixin):
             # 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)
+            lib.setup(self)  # type: ignore
             self.__extensions[name] = lib
 
             # revert sys.modules back to normal and raise back to caller
@@ -787,18 +836,18 @@ class BotBase(GroupMixin):
             raise
 
     @property
-    def extensions(self):
+    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)
 
     # help command stuff
 
     @property
-    def help_command(self):
+    def help_command(self) -> Optional[HelpCommand]:
         return self._help_command
 
     @help_command.setter
-    def help_command(self, value):
+    def help_command(self, value: Optional[HelpCommand]) -> None:
         if value is not None:
             if not isinstance(value, HelpCommand):
                 raise TypeError('help_command must be a subclass of HelpCommand')
@@ -814,7 +863,7 @@ class BotBase(GroupMixin):
 
     # command processing
 
-    async def get_prefix(self, message):
+    async def get_prefix(self, message: Message) -> Union[List[str], str]:
         """|coro|
 
         Retrieves the prefix the bot is listening to
@@ -845,14 +894,14 @@ class BotBase(GroupMixin):
                     raise
 
                 raise TypeError("command_prefix must be plain string, iterable of strings, or callable "
-                                "returning either of these, not {}".format(ret.__class__.__name__))
+                                f"returning either of these, not {ret.__class__.__name__}")
 
             if not ret:
                 raise ValueError("Iterable command_prefix must contain at least one prefix")
 
         return ret
 
-    async def get_context(self, message, *, cls=Context):
+    async def get_context(self, message: Message, *, cls: Type[CXT] = Context) -> CXT:
         r"""|coro|
 
         Returns the invocation context from the message.
@@ -885,7 +934,7 @@ class BotBase(GroupMixin):
         view = StringView(message.content)
         ctx = cls(prefix=None, view=view, bot=self, message=message)
 
-        if self._skip_check(message.author.id, self.user.id):
+        if message.author.id == self.user.id:  # type: ignore
             return ctx
 
         prefix = await self.get_prefix(message)
@@ -906,13 +955,13 @@ class BotBase(GroupMixin):
             except TypeError:
                 if not isinstance(prefix, list):
                     raise TypeError("get_prefix must return either a string or a list of string, "
-                                    "not {}".format(prefix.__class__.__name__))
+                                    f"not {prefix.__class__.__name__}")
 
                 # It's possible a bad command_prefix got us here.
                 for value in prefix:
                     if not isinstance(value, str):
                         raise TypeError("Iterable command_prefix or list returned from get_prefix must "
-                                        "contain only strings, not {}".format(value.__class__.__name__))
+                                        f"contain only strings, not {value.__class__.__name__}")
 
                 # Getting here shouldn't happen
                 raise
@@ -922,11 +971,12 @@ class BotBase(GroupMixin):
 
         invoker = view.get_word()
         ctx.invoked_with = invoker
-        ctx.prefix = invoked_prefix
+        # type-checker fails to narrow invoked_prefix type.
+        ctx.prefix = invoked_prefix  # type: ignore
         ctx.command = self.all_commands.get(invoker)
         return ctx
 
-    async def invoke(self, ctx):
+    async def invoke(self, ctx: Context) -> None:
         """|coro|
 
         Invokes the command given under the invocation context and
@@ -952,7 +1002,7 @@ class BotBase(GroupMixin):
             exc = errors.CommandNotFound(f'Command "{ctx.invoked_with}" is not found')
             self.dispatch('command_error', ctx, exc)
 
-    async def process_commands(self, message):
+    async def process_commands(self, message: Message) -> None:
         """|coro|
 
         This function processes the commands that have been registered
@@ -1030,10 +1080,6 @@ class Bot(BotBase, discord.Client):
         you require group commands to be case insensitive as well.
     description: :class:`str`
         The content prefixed into the default help message.
-    self_bot: :class:`bool`
-        If ``True``, the bot will only listen to commands invoked by itself rather
-        than ignoring itself. If ``False`` (the default) then the bot will ignore
-        itself. This cannot be changed once initialised.
     help_command: Optional[:class:`.HelpCommand`]
         The help command implementation to use. This can be dynamically
         set at runtime. To remove the help command pass ``None``. For more

discord/ext/commands/cog.py

@@ -21,16 +21,30 @@ 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 inspect
-import copy
+import discord.utils
+
+from typing import Any, Callable, ClassVar, Dict, Generator, List, Optional, TYPE_CHECKING, Tuple, TypeVar, Type
+
 from ._types import _BaseCommand
 
+if TYPE_CHECKING:
+    from .bot import BotBase
+    from .context import Context
+    from .core import Command
+
 __all__ = (
     'CogMeta',
     'Cog',
 )
 
+CogT = TypeVar('CogT', bound='Cog')
+FuncT = TypeVar('FuncT', bound=Callable[..., Any])
+
+MISSING: Any = discord.utils.MISSING
+
 class CogMeta(type):
     """A metaclass for defining a cog.
 
@@ -90,8 +104,12 @@ class CogMeta(type):
                 async def bar(self, ctx):
                     pass # hidden -> False
     """
+    __cog_name__: str
+    __cog_settings__: Dict[str, Any]
+    __cog_commands__: List[Command]
+    __cog_listeners__: List[Tuple[str, str]]
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(cls: Type[CogMeta], *args: Any, **kwargs: Any) -> CogMeta:
         name, bases, attrs = args
         attrs['__cog_name__'] = kwargs.pop('name', name)
         attrs['__cog_settings__'] = kwargs.pop('command_attrs', {})
@@ -144,14 +162,14 @@ class CogMeta(type):
         new_cls.__cog_listeners__ = listeners_as_list
         return new_cls
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args)
 
     @classmethod
-    def qualified_name(cls):
+    def qualified_name(cls) -> str:
         return cls.__cog_name__
 
-def _cog_special_method(func):
+def _cog_special_method(func: FuncT) -> FuncT:
     func.__cog_special_method__ = None
     return func
 
@@ -165,8 +183,12 @@ class Cog(metaclass=CogMeta):
     When inheriting from this class, the options shown in :class:`CogMeta`
     are equally valid here.
     """
+    __cog_name__: ClassVar[str]
+    __cog_settings__: ClassVar[Dict[str, Any]]
+    __cog_commands__: ClassVar[List[Command]]
+    __cog_listeners__: ClassVar[List[Tuple[str, str]]]
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(cls: Type[CogT], *args: Any, **kwargs: Any) -> CogT:
         # For issue 426, we need to store a copy of the command objects
         # since we modify them to inject `self` to them.
         # To do this, we need to interfere with the Cog creation process.
@@ -174,7 +196,8 @@ class Cog(metaclass=CogMeta):
         cmd_attrs = cls.__cog_settings__
 
         # Either update the command with the cog provided defaults or copy it.
-        self.__cog_commands__ = tuple(c._update_copy(cmd_attrs) for c in cls.__cog_commands__)
+        # r.e type ignore, type-checker complains about overriding a ClassVar
+        self.__cog_commands__ = tuple(c._update_copy(cmd_attrs) for c in cls.__cog_commands__)  # type: ignore
 
         lookup = {
             cmd.qualified_name: cmd
@@ -187,15 +210,15 @@ class Cog(metaclass=CogMeta):
             parent = command.parent
             if parent is not None:
                 # Get the latest parent reference
-                parent = lookup[parent.qualified_name]
+                parent = lookup[parent.qualified_name]  # type: ignore
 
                 # Update our parent's reference to our self
-                parent.remove_command(command.name)
-                parent.add_command(command)
+                parent.remove_command(command.name)  # type: ignore
+                parent.add_command(command)  # type: ignore
 
         return self
 
-    def get_commands(self):
+    def get_commands(self) -> List[Command]:
         r"""
         Returns
         --------
@@ -210,20 +233,20 @@ class Cog(metaclass=CogMeta):
         return [c for c in self.__cog_commands__ if c.parent is None]
 
     @property
-    def qualified_name(self):
+    def qualified_name(self) -> str:
         """:class:`str`: Returns the cog's specified name, not the class name."""
         return self.__cog_name__
 
     @property
-    def description(self):
+    def description(self) -> str:
         """:class:`str`: Returns the cog's description, typically the cleaned docstring."""
         return self.__cog_description__
 
     @description.setter
-    def description(self, description):
+    def description(self, description: str) -> None:
         self.__cog_description__ = description
 
-    def walk_commands(self):
+    def walk_commands(self) -> Generator[Command, None, None]:
         """An iterator that recursively walks through this cog's commands and subcommands.
 
         Yields
@@ -238,7 +261,7 @@ class Cog(metaclass=CogMeta):
                 if isinstance(command, GroupMixin):
                     yield from command.walk_commands()
 
-    def get_listeners(self):
+    def get_listeners(self) -> List[Tuple[str, Callable[..., Any]]]:
         """Returns a :class:`list` of (name, function) listener pairs that are defined in this cog.
 
         Returns
@@ -249,12 +272,12 @@ class Cog(metaclass=CogMeta):
         return [(name, getattr(self, method_name)) for name, method_name in self.__cog_listeners__]
 
     @classmethod
-    def _get_overridden_method(cls, method):
+    def _get_overridden_method(cls, method: FuncT) -> Optional[FuncT]:
         """Return None if the method is not overridden. Otherwise returns the overridden method."""
         return getattr(method.__func__, '__cog_special_method__', method)
 
     @classmethod
-    def listener(cls, name=None):
+    def listener(cls, name: str = MISSING) -> Callable[[FuncT], FuncT]:
         """A decorator that marks a function as a listener.
 
         This is the cog equivalent of :meth:`.Bot.listen`.
@@ -272,10 +295,10 @@ class Cog(metaclass=CogMeta):
             the name.
         """
 
-        if name is not None and not isinstance(name, str):
+        if name is not MISSING and not isinstance(name, str):
             raise TypeError(f'Cog.listener expected str but received {name.__class__.__name__!r} instead.')
 
-        def decorator(func):
+        def decorator(func: FuncT) -> FuncT:
             actual = func
             if isinstance(actual, staticmethod):
                 actual = actual.__func__
@@ -294,7 +317,7 @@ class Cog(metaclass=CogMeta):
             return func
         return decorator
 
-    def has_error_handler(self):
+    def has_error_handler(self) -> bool:
         """:class:`bool`: Checks whether the cog has an error handler.
 
         .. versionadded:: 1.7
@@ -302,7 +325,7 @@ class Cog(metaclass=CogMeta):
         return not hasattr(self.cog_command_error.__func__, '__cog_special_method__')
 
     @_cog_special_method
-    def cog_unload(self):
+    def cog_unload(self) -> None:
         """A special method that is called when the cog gets removed.
 
         This function **cannot** be a coroutine. It must be a regular
@@ -313,7 +336,7 @@ class Cog(metaclass=CogMeta):
         pass
 
     @_cog_special_method
-    def bot_check_once(self, ctx):
+    def bot_check_once(self, ctx: Context) -> bool:
         """A special method that registers as a :meth:`.Bot.check_once`
         check.
 
@@ -323,7 +346,7 @@ class Cog(metaclass=CogMeta):
         return True
 
     @_cog_special_method
-    def bot_check(self, ctx):
+    def bot_check(self, ctx: Context) -> bool:
         """A special method that registers as a :meth:`.Bot.check`
         check.
 
@@ -333,8 +356,8 @@ class Cog(metaclass=CogMeta):
         return True
 
     @_cog_special_method
-    def cog_check(self, ctx):
-        """A special method that registers as a :func:`commands.check`
+    def cog_check(self, ctx: Context) -> bool:
+        """A special method that registers as a :func:`~discord.ext.commands.check`
         for every command and subcommand in this cog.
 
         This function **can** be a coroutine and must take a sole parameter,
@@ -343,7 +366,7 @@ class Cog(metaclass=CogMeta):
         return True
 
     @_cog_special_method
-    async def cog_command_error(self, ctx, error):
+    async def cog_command_error(self, ctx: Context, error: Exception) -> None:
         """A special method that is called whenever an error
         is dispatched inside this cog.
 
@@ -362,7 +385,7 @@ class Cog(metaclass=CogMeta):
         pass
 
     @_cog_special_method
-    async def cog_before_invoke(self, ctx):
+    async def cog_before_invoke(self, ctx: Context) -> None:
         """A special method that acts as a cog local pre-invoke hook.
 
         This is similar to :meth:`.Command.before_invoke`.
@@ -377,7 +400,7 @@ class Cog(metaclass=CogMeta):
         pass
 
     @_cog_special_method
-    async def cog_after_invoke(self, ctx):
+    async def cog_after_invoke(self, ctx: Context) -> None:
         """A special method that acts as a cog local post-invoke hook.
 
         This is similar to :meth:`.Command.after_invoke`.
@@ -391,7 +414,7 @@ class Cog(metaclass=CogMeta):
         """
         pass
 
-    def _inject(self, bot):
+    def _inject(self: CogT, bot: BotBase) -> CogT:
         cls = self.__class__
 
         # realistically, the only thing that can cause loading errors
@@ -426,7 +449,7 @@ class Cog(metaclass=CogMeta):
 
         return self
 
-    def _eject(self, bot):
+    def _eject(self, bot: BotBase) -> None:
         cls = self.__class__
 
         try:

discord/ext/commands/context.py

@@ -21,15 +21,52 @@ 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 inspect
+import re
+
+from typing import Any, Dict, Generic, List, Optional, TYPE_CHECKING, TypeVar, Union
 
 import discord.abc
 import discord.utils
 
+from discord.message import Message
+
+if TYPE_CHECKING:
+    from typing_extensions import ParamSpec
+
+    from discord.abc import MessageableChannel
+    from discord.guild import Guild
+    from discord.member import Member
+    from discord.state import ConnectionState
+    from discord.user import ClientUser, User
+    from discord.voice_client import VoiceProtocol
+
+    from .bot import Bot, AutoShardedBot
+    from .cog import Cog
+    from .core import Command
+    from .help import HelpCommand
+    from .view import StringView
+
 __all__ = (
     'Context',
 )
 
-class Context(discord.abc.Messageable):
+MISSING: Any = discord.utils.MISSING
+
+
+T = TypeVar('T')
+BotT = TypeVar('BotT', bound="Union[Bot, AutoShardedBot]")
+CogT = TypeVar('CogT', bound="Cog")
+
+if TYPE_CHECKING:
+    P = ParamSpec('P')
+else:
+    P = TypeVar('P')
+
+
+class Context(discord.abc.Messageable, Generic[BotT]):
     r"""Represents the context in which a command is being invoked under.
 
     This class contains a lot of meta data to help you understand more about
@@ -46,17 +83,22 @@ class Context(discord.abc.Messageable):
         The bot that contains the command being executed.
     args: :class:`list`
         The list of transformed arguments that were passed into the command.
-        If this is accessed during the :func:`on_command_error` event
+        If this is accessed during the :func:`.on_command_error` event
         then this list could be incomplete.
     kwargs: :class:`dict`
         A dictionary of transformed arguments that were passed into the command.
         Similar to :attr:`args`\, if this is accessed in the
-        :func:`on_command_error` event then this dict could be incomplete.
-    prefix: :class:`str`
+        :func:`.on_command_error` event then this dict could be incomplete.
+    current_parameter: Optional[:class:`inspect.Parameter`]
+        The parameter that is currently being inspected and converted.
+        This is only of use for within converters.
+
+        .. versionadded:: 2.0
+    prefix: Optional[:class:`str`]
         The prefix that was used to invoke the command.
-    command: :class:`Command`
+    command: Optional[:class:`Command`]
         The command that is being invoked currently.
-    invoked_with: :class:`str`
+    invoked_with: Optional[:class:`str`]
         The command name that triggered this invocation. Useful for finding out
         which alias called the command.
     invoked_parents: List[:class:`str`]
@@ -67,7 +109,7 @@ class Context(discord.abc.Messageable):
 
         .. versionadded:: 1.7
 
-    invoked_subcommand: :class:`Command`
+    invoked_subcommand: Optional[:class:`Command`]
         The subcommand that was invoked.
         If no valid subcommand was invoked then this is equal to ``None``.
     subcommand_passed: Optional[:class:`str`]
@@ -80,22 +122,38 @@ class Context(discord.abc.Messageable):
         or invoked.
     """
 
-    def __init__(self, **attrs):
-        self.message = attrs.pop('message', None)
-        self.bot = attrs.pop('bot', None)
-        self.args = attrs.pop('args', [])
-        self.kwargs = attrs.pop('kwargs', {})
-        self.prefix = attrs.pop('prefix')
-        self.command = attrs.pop('command', None)
-        self.view = attrs.pop('view', None)
-        self.invoked_with = attrs.pop('invoked_with', None)
-        self.invoked_parents = attrs.pop('invoked_parents', [])
-        self.invoked_subcommand = attrs.pop('invoked_subcommand', None)
-        self.subcommand_passed = attrs.pop('subcommand_passed', None)
-        self.command_failed = attrs.pop('command_failed', False)
-        self._state = self.message._state
+    def __init__(self,
+        *,
+        message: Message,
+        bot: BotT,
+        view: StringView,
+        args: List[Any] = MISSING,
+        kwargs: Dict[str, Any] = MISSING,
+        prefix: Optional[str] = None,
+        command: Optional[Command] = None,
+        invoked_with: Optional[str] = None,
+        invoked_parents: List[str] = MISSING,
+        invoked_subcommand: Optional[Command] = None,
+        subcommand_passed: Optional[str] = None,
+        command_failed: bool = False,
+        current_parameter: Optional[inspect.Parameter] = None,
+    ):
+        self.message: Message = message
+        self.bot: BotT = bot
+        self.args: List[Any] = args or []
+        self.kwargs: Dict[str, Any] = kwargs or {}
+        self.prefix: Optional[str] = prefix
+        self.command: Optional[Command] = command
+        self.view: StringView = view
+        self.invoked_with: Optional[str] = invoked_with
+        self.invoked_parents: List[str] = invoked_parents or []
+        self.invoked_subcommand: Optional[Command] = invoked_subcommand
+        self.subcommand_passed: Optional[str] = subcommand_passed
+        self.command_failed: bool = command_failed
+        self.current_parameter: Optional[inspect.Parameter] = current_parameter
+        self._state: ConnectionState = self.message._state
 
-    async def invoke(self, command, /, *args, **kwargs):
+    async def invoke(self, command: Command[CogT, P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
         r"""|coro|
 
         Calls a command with the arguments given.
@@ -117,7 +175,7 @@ class Context(discord.abc.Messageable):
         command: :class:`.Command`
             The command that is going to be called.
         \*args
-            The arguments to to use.
+            The arguments to use.
         \*\*kwargs
             The keyword arguments to use.
 
@@ -126,17 +184,9 @@ class Context(discord.abc.Messageable):
         TypeError
             The command argument to invoke is missing.
         """
-        arguments = []
-        if command.cog is not None:
-            arguments.append(command.cog)
+        return await command(self, *args, **kwargs)
 
-        arguments.append(self)
-        arguments.extend(args)
-
-        ret = await command.callback(*arguments, **kwargs)
-        return ret
-
-    async def reinvoke(self, *, call_hooks=False, restart=True):
+    async def reinvoke(self, *, call_hooks: bool = False, restart: bool = True) -> None:
         """|coro|
 
         Calls the command again.
@@ -180,7 +230,7 @@ class Context(discord.abc.Messageable):
 
         if restart:
             to_call = cmd.root_parent or cmd
-            view.index = len(self.prefix)
+            view.index = len(self.prefix or '')
             view.previous = 0
             self.invoked_parents = []
             self.invoked_with = view.get_word() # advance to get the root command
@@ -199,15 +249,32 @@ class Context(discord.abc.Messageable):
             self.subcommand_passed = subcommand_passed
 
     @property
-    def valid(self):
+    def valid(self) -> bool:
         """:class:`bool`: Checks if the invocation context is valid to be invoked with."""
         return self.prefix is not None and self.command is not None
 
-    async def _get_channel(self):
+    async def _get_channel(self) -> discord.abc.Messageable:
         return self.channel
 
     @property
-    def cog(self):
+    def clean_prefix(self) -> str:
+        """:class:`str`: The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``.
+
+        .. versionadded:: 2.0
+        """
+        if self.prefix is None:
+            return ''
+
+        user = self.me
+        # this breaks if the prefix mention is not the bot itself but I
+        # consider this to be an *incredibly* strange use case. I'd rather go
+        # for this common use case rather than waste performance for the
+        # odd one.
+        pattern = re.compile(r"<@!?%s>" % user.id)
+        return pattern.sub("@%s" % user.display_name.replace('\\', r'\\'), self.prefix)
+
+    @property
+    def cog(self) -> Optional[Cog]:
         """Optional[:class:`.Cog`]: Returns the cog associated with this context's command. None if it does not exist."""
 
         if self.command is None:
@@ -215,38 +282,39 @@ class Context(discord.abc.Messageable):
         return self.command.cog
 
     @discord.utils.cached_property
-    def guild(self):
+    def guild(self) -> Optional[Guild]:
         """Optional[:class:`.Guild`]: Returns the guild associated with this context's command. None if not available."""
         return self.message.guild
 
     @discord.utils.cached_property
-    def channel(self):
+    def channel(self) -> MessageableChannel:
         """Union[:class:`.abc.Messageable`]: Returns the channel associated with this context's command.
         Shorthand for :attr:`.Message.channel`.
         """
         return self.message.channel
 
     @discord.utils.cached_property
-    def author(self):
+    def author(self) -> Union[User, Member]:
         """Union[:class:`~discord.User`, :class:`.Member`]:
         Returns the author associated with this context's command. Shorthand for :attr:`.Message.author`
         """
         return self.message.author
 
     @discord.utils.cached_property
-    def me(self):
+    def me(self) -> Union[Member, ClientUser]:
         """Union[:class:`.Member`, :class:`.ClientUser`]:
         Similar to :attr:`.Guild.me` except it may return the :class:`.ClientUser` in private message contexts.
         """
-        return self.guild.me if self.guild is not None else self.bot.user
+        # bot.user will never be None at this point.
+        return self.guild.me if self.guild is not None else self.bot.user  # type: ignore
 
     @property
-    def voice_client(self):
+    def voice_client(self) -> Optional[VoiceProtocol]:
         r"""Optional[:class:`.VoiceProtocol`]: A shortcut to :attr:`.Guild.voice_client`\, if applicable."""
         g = self.guild
         return g.voice_client if g else None
 
-    async def send_help(self, *args):
+    async def send_help(self, *args: Any) -> Any:
         """send_help(entity=<bot>)
 
         |coro|
@@ -298,12 +366,12 @@ class Context(discord.abc.Messageable):
                 return None
 
         entity = args[0]
-        if entity is None:
-            return None
-
         if isinstance(entity, str):
             entity = bot.get_cog(entity) or bot.get_command(entity)
 
+        if entity is None:
+            return None
+
         try:
             entity.qualified_name
         except AttributeError:
@@ -327,6 +395,6 @@ class Context(discord.abc.Messageable):
         except CommandError as e:
             await cmd.on_help_command_error(self, e)
 
-    @discord.utils.copy_doc(discord.Message.reply)
-    async def reply(self, content=None, **kwargs):
+    @discord.utils.copy_doc(Message.reply)
+    async def reply(self, content: Optional[str] = None, **kwargs: Any) -> Message:
         return await self.message.reply(content, **kwargs)

discord/ext/commands/converter.py

@@ -26,17 +26,34 @@ from __future__ import annotations
 
 import re
 import inspect
-from typing import TYPE_CHECKING, Generic, Protocol, TypeVar, Union, runtime_checkable
+from typing import (
+    Any,
+    Dict,
+    Generic,
+    Iterable,
+    Literal,
+    Optional,
+    TYPE_CHECKING,
+    List,
+    Protocol,
+    Type,
+    TypeVar,
+    Tuple,
+    Union,
+    runtime_checkable,
+)
 
 import discord
 from .errors import *
 
 if TYPE_CHECKING:
     from .context import Context
+    from discord.message import PartialMessageableChannel
 
 
 __all__ = (
     'Converter',
+    'ObjectConverter',
     'MemberConverter',
     'UserConverter',
     'MessageConverter',
@@ -55,8 +72,12 @@ __all__ = (
     'CategoryChannelConverter',
     'IDConverter',
     'StoreChannelConverter',
+    'ThreadConverter',
+    'GuildChannelConverter',
+    'GuildStickerConverter',
     'clean_content',
     'Greedy',
+    'run_converters',
 )
 
 
@@ -70,11 +91,14 @@ def _get_from_guilds(bot, getter, argument):
 
 
 _utils_get = discord.utils.get
-T = TypeVar('T', covariant=True)
+T = TypeVar('T')
+T_co = TypeVar('T_co', covariant=True)
+CT = TypeVar('CT', bound=discord.abc.GuildChannel)
+TT = TypeVar('TT', bound=discord.Thread)
 
 
 @runtime_checkable
-class Converter(Protocol[T]):
+class Converter(Protocol[T_co]):
     """The base class of custom converters that require the :class:`.Context`
     to be passed to be useful.
 
@@ -85,7 +109,7 @@ class Converter(Protocol[T]):
     method to do its conversion logic. This method must be a :ref:`coroutine <coroutine>`.
     """
 
-    async def convert(self, ctx: Context, argument: str) -> T:
+    async def convert(self, ctx: Context, argument: str) -> T_co:
         """|coro|
 
         The method to override to do conversion logic.
@@ -110,13 +134,39 @@ class Converter(Protocol[T]):
         """
         raise NotImplementedError('Derived classes need to implement this.')
 
-class IDConverter(Converter[T]):
-    def __init__(self):
-        self._id_regex = re.compile(r'([0-9]{15,20})$')
-        super().__init__()
 
-    def _get_id_match(self, argument):
-        return self._id_regex.match(argument)
+_ID_REGEX = re.compile(r'([0-9]{15,20})$')
+
+
+class IDConverter(Converter[T_co]):
+    @staticmethod
+    def _get_id_match(argument):
+        return _ID_REGEX.match(argument)
+
+
+class ObjectConverter(IDConverter[discord.Object]):
+    """Converts to a :class:`~discord.Object`.
+
+    The argument must follow the valid ID or mention formats (e.g. `<@80088516616269824>`).
+
+    .. versionadded:: 2.0
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by member, role, or channel mention.
+    """
+
+    async def convert(self, ctx: Context, argument: str) -> discord.Object:
+        match = self._get_id_match(argument) or re.match(r'<(?:@(?:!|&)?|#)([0-9]{15,20})>$', argument)
+
+        if match is None:
+            raise ObjectNotFound(argument)
+
+        result = int(match.group(1))
+
+        return discord.Object(id=result)
+
 
 class MemberConverter(IDConverter[discord.Member]):
     """Converts to a :class:`~discord.Member`.
@@ -173,7 +223,7 @@ class MemberConverter(IDConverter[discord.Member]):
 
     async def convert(self, ctx: Context, argument: str) -> discord.Member:
         bot = ctx.bot
-        match = self._get_id_match(argument) or re.match(r'<@!?([0-9]+)>$', argument)
+        match = self._get_id_match(argument) or re.match(r'<@!?([0-9]{15,20})>$', argument)
         guild = ctx.guild
         result = None
         user_id = None
@@ -204,6 +254,7 @@ class MemberConverter(IDConverter[discord.Member]):
 
         return result
 
+
 class UserConverter(IDConverter[discord.User]):
     """Converts to a :class:`~discord.User`.
 
@@ -223,8 +274,9 @@ class UserConverter(IDConverter[discord.User]):
         This converter now lazily fetches users from the HTTP APIs if an ID is passed
         and it's not available in cache.
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.User:
-        match = self._get_id_match(argument) or re.match(r'<@!?([0-9]+)>$', argument)
+        match = self._get_id_match(argument) or re.match(r'<@!?([0-9]{15,20})>$', argument)
         result = None
         state = ctx._state
 
@@ -263,6 +315,7 @@ class UserConverter(IDConverter[discord.User]):
 
         return result
 
+
 class PartialMessageConverter(Converter[discord.PartialMessage]):
     """Converts to a :class:`discord.PartialMessage`.
 
@@ -274,27 +327,49 @@ class PartialMessageConverter(Converter[discord.PartialMessage]):
     2. By message ID (The message is assumed to be in the context channel.)
     3. By message URL
     """
+
     @staticmethod
-    def _get_id_matches(argument):
+    def _get_id_matches(ctx, argument):
         id_regex = re.compile(r'(?:(?P<channel_id>[0-9]{15,20})-)?(?P<message_id>[0-9]{15,20})$')
         link_regex = re.compile(
             r'https?://(?:(ptb|canary|www)\.)?discord(?:app)?\.com/channels/'
-            r'(?:[0-9]{15,20}|@me)'
+            r'(?P<guild_id>[0-9]{15,20}|@me)'
             r'/(?P<channel_id>[0-9]{15,20})/(?P<message_id>[0-9]{15,20})/?$'
         )
         match = id_regex.match(argument) or link_regex.match(argument)
         if not match:
             raise MessageNotFound(argument)
-        channel_id = match.group("channel_id")
-        return int(match.group("message_id")), int(channel_id) if channel_id else None
+        data = match.groupdict()
+        channel_id = discord.utils._get_as_snowflake(data, 'channel_id')
+        message_id = int(data['message_id'])
+        guild_id = data.get('guild_id')
+        if guild_id is None:
+            guild_id = ctx.guild and ctx.guild.id
+        elif guild_id == '@me':
+            guild_id = None
+        else:
+            guild_id = int(guild_id)
+        return guild_id, message_id, channel_id
+
+    @staticmethod
+    def _resolve_channel(ctx, guild_id, channel_id) -> Optional[PartialMessageableChannel]:
+        if guild_id is not None:
+            guild = ctx.bot.get_guild(guild_id)
+            if guild is not None and channel_id is not None:
+                return guild._resolve_channel(channel_id)  # type: ignore
+            else:
+                return None
+        else:
+            return ctx.bot.get_channel(channel_id) if channel_id else ctx.channel
 
     async def convert(self, ctx: Context, argument: str) -> discord.PartialMessage:
-        message_id, channel_id = self._get_id_matches(argument)
-        channel = ctx.bot.get_channel(channel_id) if channel_id else ctx.channel
+        guild_id, message_id, channel_id = self._get_id_matches(ctx, argument)
+        channel = self._resolve_channel(ctx, guild_id, channel_id)
         if not channel:
             raise ChannelNotFound(channel_id)
         return discord.PartialMessage(channel=channel, id=message_id)
 
+
 class MessageConverter(IDConverter[discord.Message]):
     """Converts to a :class:`discord.Message`.
 
@@ -309,12 +384,13 @@ class MessageConverter(IDConverter[discord.Message]):
     .. versionchanged:: 1.5
          Raise :exc:`.ChannelNotFound`, :exc:`.MessageNotFound` or :exc:`.ChannelNotReadable` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.Message:
-        message_id, channel_id = PartialMessageConverter._get_id_matches(argument)
+        guild_id, message_id, channel_id = PartialMessageConverter._get_id_matches(ctx, argument)
         message = ctx.bot._connection._get_message(message_id)
         if message:
             return message
-        channel = ctx.bot.get_channel(channel_id) if channel_id else ctx.channel
+        channel = PartialMessageConverter._resolve_channel(ctx, guild_id, channel_id)
         if not channel:
             raise ChannelNotFound(channel_id)
         try:
@@ -324,6 +400,80 @@ class MessageConverter(IDConverter[discord.Message]):
         except discord.Forbidden:
             raise ChannelNotReadable(channel)
 
+
+class GuildChannelConverter(IDConverter[discord.abc.GuildChannel]):
+    """Converts to a :class:`~discord.abc.GuildChannel`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name.
+
+    .. versionadded:: 2.0
+    """
+
+    async def convert(self, ctx: Context, argument: str) -> discord.abc.GuildChannel:
+        return self._resolve_channel(ctx, argument, 'channels', discord.abc.GuildChannel)
+
+    @staticmethod
+    def _resolve_channel(ctx: Context, argument: str, attribute: str, type: Type[CT]) -> CT:
+        bot = ctx.bot
+
+        match = IDConverter._get_id_match(argument) or re.match(r'<#([0-9]{15,20})>$', argument)
+        result = None
+        guild = ctx.guild
+
+        if match is None:
+            # not a mention
+            if guild:
+                iterable: Iterable[CT] = getattr(guild, attribute)
+                result: Optional[CT] = discord.utils.get(iterable, name=argument)
+            else:
+
+                def check(c):
+                    return isinstance(c, type) and c.name == argument
+
+                result = discord.utils.find(check, bot.get_all_channels())
+        else:
+            channel_id = int(match.group(1))
+            if guild:
+                result = guild.get_channel(channel_id)
+            else:
+                result = _get_from_guilds(bot, 'get_channel', channel_id)
+
+        if not isinstance(result, type):
+            raise ChannelNotFound(argument)
+
+        return result
+
+    @staticmethod
+    def _resolve_thread(ctx: Context, argument: str, attribute: str, type: Type[TT]) -> TT:
+        bot = ctx.bot
+
+        match = IDConverter._get_id_match(argument) or re.match(r'<#([0-9]{15,20})>$', argument)
+        result = None
+        guild = ctx.guild
+
+        if match is None:
+            # not a mention
+            if guild:
+                iterable: Iterable[TT] = getattr(guild, attribute)
+                result: Optional[TT] = discord.utils.get(iterable, name=argument)
+        else:
+            thread_id = int(match.group(1))
+            if guild:
+                result = guild.get_thread(thread_id)
+
+        if not result or not isinstance(result, type):
+            raise ThreadNotFound(argument)
+
+        return result
+
+
 class TextChannelConverter(IDConverter[discord.TextChannel]):
     """Converts to a :class:`~discord.TextChannel`.
 
@@ -339,32 +489,10 @@ class TextChannelConverter(IDConverter[discord.TextChannel]):
     .. versionchanged:: 1.5
          Raise :exc:`.ChannelNotFound` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.TextChannel:
-        bot = ctx.bot
+        return GuildChannelConverter._resolve_channel(ctx, argument, 'text_channels', discord.TextChannel)
 
-        match = self._get_id_match(argument) or re.match(r'<#([0-9]+)>$', argument)
-        result = None
-        guild = ctx.guild
-
-        if match is None:
-            # not a mention
-            if guild:
-                result = discord.utils.get(guild.text_channels, name=argument)
-            else:
-                def check(c):
-                    return isinstance(c, discord.TextChannel) and c.name == argument
-                result = discord.utils.find(check, bot.get_all_channels())
-        else:
-            channel_id = int(match.group(1))
-            if guild:
-                result = guild.get_channel(channel_id)
-            else:
-                result = _get_from_guilds(bot, 'get_channel', channel_id)
-
-        if not isinstance(result, discord.TextChannel):
-            raise ChannelNotFound(argument)
-
-        return result
 
 class VoiceChannelConverter(IDConverter[discord.VoiceChannel]):
     """Converts to a :class:`~discord.VoiceChannel`.
@@ -381,31 +509,10 @@ class VoiceChannelConverter(IDConverter[discord.VoiceChannel]):
     .. versionchanged:: 1.5
          Raise :exc:`.ChannelNotFound` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.VoiceChannel:
-        bot = ctx.bot
-        match = self._get_id_match(argument) or re.match(r'<#([0-9]+)>$', argument)
-        result = None
-        guild = ctx.guild
+        return GuildChannelConverter._resolve_channel(ctx, argument, 'voice_channels', discord.VoiceChannel)
 
-        if match is None:
-            # not a mention
-            if guild:
-                result = discord.utils.get(guild.voice_channels, name=argument)
-            else:
-                def check(c):
-                    return isinstance(c, discord.VoiceChannel) and c.name == argument
-                result = discord.utils.find(check, bot.get_all_channels())
-        else:
-            channel_id = int(match.group(1))
-            if guild:
-                result = guild.get_channel(channel_id)
-            else:
-                result = _get_from_guilds(bot, 'get_channel', channel_id)
-
-        if not isinstance(result, discord.VoiceChannel):
-            raise ChannelNotFound(argument)
-
-        return result
 
 class StageChannelConverter(IDConverter[discord.StageChannel]):
     """Converts to a :class:`~discord.StageChannel`.
@@ -421,31 +528,10 @@ class StageChannelConverter(IDConverter[discord.StageChannel]):
     2. Lookup by mention.
     3. Lookup by name
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.StageChannel:
-        bot = ctx.bot
-        match = self._get_id_match(argument) or re.match(r'<#([0-9]+)>$', argument)
-        result = None
-        guild = ctx.guild
+        return GuildChannelConverter._resolve_channel(ctx, argument, 'stage_channels', discord.StageChannel)
 
-        if match is None:
-            # not a mention
-            if guild:
-                result = discord.utils.get(guild.stage_channels, name=argument)
-            else:
-                def check(c):
-                    return isinstance(c, discord.StageChannel) and c.name == argument
-                result = discord.utils.find(check, bot.get_all_channels())
-        else:
-            channel_id = int(match.group(1))
-            if guild:
-                result = guild.get_channel(channel_id)
-            else:
-                result = _get_from_guilds(bot, 'get_channel', channel_id)
-
-        if not isinstance(result, discord.StageChannel):
-            raise ChannelNotFound(argument)
-
-        return result
 
 class CategoryChannelConverter(IDConverter[discord.CategoryChannel]):
     """Converts to a :class:`~discord.CategoryChannel`.
@@ -462,32 +548,10 @@ class CategoryChannelConverter(IDConverter[discord.CategoryChannel]):
     .. versionchanged:: 1.5
          Raise :exc:`.ChannelNotFound` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.CategoryChannel:
-        bot = ctx.bot
+        return GuildChannelConverter._resolve_channel(ctx, argument, 'categories', discord.CategoryChannel)
 
-        match = self._get_id_match(argument) or re.match(r'<#([0-9]+)>$', argument)
-        result = None
-        guild = ctx.guild
-
-        if match is None:
-            # not a mention
-            if guild:
-                result = discord.utils.get(guild.categories, name=argument)
-            else:
-                def check(c):
-                    return isinstance(c, discord.CategoryChannel) and c.name == argument
-                result = discord.utils.find(check, bot.get_all_channels())
-        else:
-            channel_id = int(match.group(1))
-            if guild:
-                result = guild.get_channel(channel_id)
-            else:
-                result = _get_from_guilds(bot, 'get_channel', channel_id)
-
-        if not isinstance(result, discord.CategoryChannel):
-            raise ChannelNotFound(argument)
-
-        return result
 
 class StoreChannelConverter(IDConverter[discord.StoreChannel]):
     """Converts to a :class:`~discord.StoreChannel`.
@@ -505,30 +569,26 @@ class StoreChannelConverter(IDConverter[discord.StoreChannel]):
     """
 
     async def convert(self, ctx: Context, argument: str) -> discord.StoreChannel:
-        bot = ctx.bot
-        match = self._get_id_match(argument) or re.match(r'<#([0-9]+)>$', argument)
-        result = None
-        guild = ctx.guild
+        return GuildChannelConverter._resolve_channel(ctx, argument, 'channels', discord.StoreChannel)
 
-        if match is None:
-            # not a mention
-            if guild:
-                result = discord.utils.get(guild.channels, name=argument)
-            else:
-                def check(c):
-                    return isinstance(c, discord.StoreChannel) and c.name == argument
-                result = discord.utils.find(check, bot.get_all_channels())
-        else:
-            channel_id = int(match.group(1))
-            if guild:
-                result = guild.get_channel(channel_id)
-            else:
-                result = _get_from_guilds(bot, 'get_channel', channel_id)
 
-        if not isinstance(result, discord.StoreChannel):
-            raise ChannelNotFound(argument)
+class ThreadConverter(IDConverter[discord.Thread]):
+    """Coverts to a :class:`~discord.Thread`.
+
+    All lookups are via the local guild.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name.
+
+    .. versionadded: 2.0
+    """
+
+    async def convert(self, ctx: Context, argument: str) -> discord.Thread:
+        return GuildChannelConverter._resolve_thread(ctx, argument, 'threads', discord.Thread)
 
-        return result
 
 class ColourConverter(Converter[discord.Colour]):
     """Converts to a :class:`~discord.Colour`.
@@ -542,7 +602,7 @@ class ColourConverter(Converter[discord.Colour]):
     - ``#<hex>``
     - ``0x#<hex>``
     - ``rgb(<number>, <number>, <number>)``
-    - Any of the ``classmethod`` in :class:`Colour`
+    - Any of the ``classmethod`` in :class:`~discord.Colour`
 
         - The ``_`` in the name can be optionally replaced with spaces.
 
@@ -612,13 +672,15 @@ class ColourConverter(Converter[discord.Colour]):
             raise BadColourArgument(arg)
         return method()
 
+
 ColorConverter = ColourConverter
 
+
 class RoleConverter(IDConverter[discord.Role]):
     """Converts to a :class:`~discord.Role`.
 
-    All lookups are via the local guild. If in a DM context, then the lookup
-    is done by the global cache.
+    All lookups are via the local guild. If in a DM context, the converter raises
+    :exc:`.NoPrivateMessage` exception.
 
     The lookup strategy is as follows (in order):
 
@@ -629,12 +691,13 @@ class RoleConverter(IDConverter[discord.Role]):
     .. versionchanged:: 1.5
          Raise :exc:`.RoleNotFound` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.Role:
         guild = ctx.guild
         if not guild:
             raise NoPrivateMessage()
 
-        match = self._get_id_match(argument) or re.match(r'<@&([0-9]+)>$', argument)
+        match = self._get_id_match(argument) or re.match(r'<@&([0-9]{15,20})>$', argument)
         if match:
             result = guild.get_role(int(match.group(1)))
         else:
@@ -644,11 +707,14 @@ class RoleConverter(IDConverter[discord.Role]):
             raise RoleNotFound(argument)
         return result
 
+
 class GameConverter(Converter[discord.Game]):
     """Converts to :class:`~discord.Game`."""
+
     async def convert(self, ctx: Context, argument: str) -> discord.Game:
         return discord.Game(name=argument)
 
+
 class InviteConverter(Converter[discord.Invite]):
     """Converts to a :class:`~discord.Invite`.
 
@@ -657,12 +723,14 @@ class InviteConverter(Converter[discord.Invite]):
     .. versionchanged:: 1.5
          Raise :exc:`.BadInviteArgument` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.Invite:
         try:
             invite = await ctx.bot.fetch_invite(argument)
             return invite
         except Exception as exc:
-            raise BadInviteArgument() from exc
+            raise BadInviteArgument(argument) from exc
+
 
 class GuildConverter(IDConverter[discord.Guild]):
     """Converts to a :class:`~discord.Guild`.
@@ -690,6 +758,7 @@ class GuildConverter(IDConverter[discord.Guild]):
                 raise GuildNotFound(argument)
         return result
 
+
 class EmojiConverter(IDConverter[discord.Emoji]):
     """Converts to a :class:`~discord.Emoji`.
 
@@ -705,8 +774,9 @@ class EmojiConverter(IDConverter[discord.Emoji]):
     .. versionchanged:: 1.5
          Raise :exc:`.EmojiNotFound` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.Emoji:
-        match = self._get_id_match(argument) or re.match(r'<a?:[a-zA-Z0-9\_]+:([0-9]+)>$', argument)
+        match = self._get_id_match(argument) or re.match(r'<a?:[a-zA-Z0-9\_]{1,32}:([0-9]{15,20})>$', argument)
         result = None
         bot = ctx.bot
         guild = ctx.guild
@@ -722,17 +792,14 @@ class EmojiConverter(IDConverter[discord.Emoji]):
             emoji_id = int(match.group(1))
 
             # Try to look up emoji by id.
-            if guild:
-                result = discord.utils.get(guild.emojis, id=emoji_id)
-
-            if result is None:
-                result = discord.utils.get(bot.emojis, id=emoji_id)
+            result = bot.get_emoji(emoji_id)
 
         if result is None:
             raise EmojiNotFound(argument)
 
         return result
 
+
 class PartialEmojiConverter(Converter[discord.PartialEmoji]):
     """Converts to a :class:`~discord.PartialEmoji`.
 
@@ -741,19 +808,61 @@ class PartialEmojiConverter(Converter[discord.PartialEmoji]):
     .. versionchanged:: 1.5
          Raise :exc:`.PartialEmojiConversionFailure` instead of generic :exc:`.BadArgument`
     """
+
     async def convert(self, ctx: Context, argument: str) -> discord.PartialEmoji:
-        match = re.match(r'<(a?):([a-zA-Z0-9\_]+):([0-9]+)>$', argument)
+        match = re.match(r'<(a?):([a-zA-Z0-9\_]{1,32}):([0-9]{15,20})>$', argument)
 
         if match:
             emoji_animated = bool(match.group(1))
             emoji_name = match.group(2)
             emoji_id = int(match.group(3))
 
-            return discord.PartialEmoji.with_state(ctx.bot._connection, animated=emoji_animated, name=emoji_name,
-                                                   id=emoji_id)
+            return discord.PartialEmoji.with_state(
+                ctx.bot._connection, animated=emoji_animated, name=emoji_name, id=emoji_id
+            )
 
         raise PartialEmojiConversionFailure(argument)
 
+
+class GuildStickerConverter(IDConverter[discord.GuildSticker]):
+    """Converts to a :class:`~discord.GuildSticker`.
+
+    All lookups are done for the local guild first, if available. If that lookup
+    fails, then it checks the client's global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    3. Lookup by name
+
+    .. versionadded:: 2.0
+    """
+
+    async def convert(self, ctx: Context, argument: str) -> discord.GuildSticker:
+        match = self._get_id_match(argument)
+        result = None
+        bot = ctx.bot
+        guild = ctx.guild
+
+        if match is None:
+            # Try to get the sticker by name. Try local guild first.
+            if guild:
+                result = discord.utils.get(guild.stickers, name=argument)
+
+            if result is None:
+                result = discord.utils.get(bot.stickers, name=argument)
+        else:
+            sticker_id = int(match.group(1))
+
+            # Try to look up sticker by id.
+            result = bot.get_sticker(sticker_id)
+
+        if result is None:
+            raise GuildStickerNotFound(argument)
+
+        return result
+
+
 class clean_content(Converter[str]):
     """Converts the argument to mention scrubbed version of
     said content.
@@ -773,59 +882,67 @@ class clean_content(Converter[str]):
 
         .. versionadded:: 1.7
     """
-    def __init__(self, *, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False, remove_markdown=False):
+
+    def __init__(
+        self,
+        *,
+        fix_channel_mentions: bool = False,
+        use_nicknames: bool = True,
+        escape_markdown: bool = False,
+        remove_markdown: bool = False,
+    ) -> None:
         self.fix_channel_mentions = fix_channel_mentions
         self.use_nicknames = use_nicknames
         self.escape_markdown = escape_markdown
         self.remove_markdown = remove_markdown
 
     async def convert(self, ctx: Context, argument: str) -> str:
-        message = ctx.message
-        transformations = {}
-
-        if self.fix_channel_mentions and ctx.guild:
-            def resolve_channel(id, *, _get=ctx.guild.get_channel):
-                ch = _get(id)
-                return f'<#{id}>', ('#' + ch.name if ch else '#deleted-channel')
-
-            transformations.update(resolve_channel(channel) for channel in message.raw_channel_mentions)
-
-        if self.use_nicknames and ctx.guild:
-            def resolve_member(id, *, _get=ctx.guild.get_member):
-                m = _get(id)
-                return '@' + m.display_name if m else '@deleted-user'
-        else:
-            def resolve_member(id, *, _get=ctx.bot.get_user):
-                m = _get(id)
-                return '@' + m.name if m else '@deleted-user'
-
-
-        transformations.update(
-            (f'<@{member_id}>', resolve_member(member_id))
-            for member_id in message.raw_mentions
-        )
-
-        transformations.update(
-            (f'<@!{member_id}>', resolve_member(member_id))
-            for member_id in message.raw_mentions
-        )
+        msg = ctx.message
 
         if ctx.guild:
-            def resolve_role(_id, *, _find=ctx.guild.get_role):
-                r = _find(_id)
-                return '@' + r.name if r else '@deleted-role'
 
-            transformations.update(
-                (f'<@&{role_id}>', resolve_role(role_id))
-                for role_id in message.raw_role_mentions
-            )
+            def resolve_member(id: int) -> str:
+                m = _utils_get(msg.mentions, id=id) or ctx.guild.get_member(id)
+                return f'@{m.display_name if self.use_nicknames else m.name}' if m else '@deleted-user'
 
-        def repl(obj):
-            return transformations.get(obj.group(0), '')
+            def resolve_role(id: int) -> str:
+                r = _utils_get(msg.role_mentions, id=id) or ctx.guild.get_role(id)
+                return f'@{r.name}' if r else '@deleted-role'
 
-        pattern = re.compile('|'.join(transformations.keys()))
-        result = pattern.sub(repl, argument)
+        else:
 
+            def resolve_member(id: int) -> str:
+                m = _utils_get(msg.mentions, id=id) or ctx.bot.get_user(id)
+                return f'@{m.name}' if m else '@deleted-user'
+
+            def resolve_role(id: int) -> str:
+                return '@deleted-role'
+
+        if self.fix_channel_mentions and ctx.guild:
+
+            def resolve_channel(id: int) -> str:
+                c = ctx.guild.get_channel(id)
+                return f'#{c.name}' if c else '#deleted-channel'
+
+        else:
+
+            def resolve_channel(id: int) -> str:
+                return f'<#{id}>'
+
+        transforms = {
+            '@': resolve_member,
+            '@!': resolve_member,
+            '#': resolve_channel,
+            '@&': resolve_role,
+        }
+
+        def repl(match: re.Match) -> str:
+            type = match[1]
+            id = int(match[2])
+            transformed = transforms[type](id)
+            return transformed
+
+        result = re.sub(r'<(@[!&]?|#)([0-9]{15,20})>', repl, argument)
         if self.escape_markdown:
             result = discord.utils.escape_markdown(result)
         elif self.remove_markdown:
@@ -834,28 +951,232 @@ class clean_content(Converter[str]):
         # Completely ensure no mentions escape:
         return discord.utils.escape_mentions(result)
 
-class _Greedy:
+
+class Greedy(List[T]):
+    r"""A special converter that greedily consumes arguments until it can't.
+    As a consequence of this behaviour, most input errors are silently discarded,
+    since it is used as an indicator of when to stop parsing.
+
+    When a parser error is met the greedy converter stops converting, undoes the
+    internal string parsing routine, and continues parsing regularly.
+
+    For example, in the following code:
+
+    .. code-block:: python3
+
+        @commands.command()
+        async def test(ctx, numbers: Greedy[int], reason: str):
+            await ctx.send("numbers: {}, reason: {}".format(numbers, reason))
+
+    An invocation of ``[p]test 1 2 3 4 5 6 hello`` would pass ``numbers`` with
+    ``[1, 2, 3, 4, 5, 6]`` and ``reason`` with ``hello``\.
+
+    For more information, check :ref:`ext_commands_special_converters`.
+    """
+
     __slots__ = ('converter',)
 
-    def __init__(self, *, converter=None):
+    def __init__(self, *, converter: T):
         self.converter = converter
 
-    def __getitem__(self, params):
+    def __repr__(self):
+        converter = getattr(self.converter, '__name__', repr(self.converter))
+        return f'Greedy[{converter}]'
+
+    def __class_getitem__(cls, params: Union[Tuple[T], T]) -> Greedy[T]:
         if not isinstance(params, tuple):
             params = (params,)
         if len(params) != 1:
             raise TypeError('Greedy[...] only takes a single argument')
         converter = params[0]
 
-        if not (callable(converter) or isinstance(converter, Converter) or hasattr(converter, '__origin__')):
+        origin = getattr(converter, '__origin__', None)
+        args = getattr(converter, '__args__', ())
+
+        if not (callable(converter) or isinstance(converter, Converter) or origin is not None):
             raise TypeError('Greedy[...] expects a type or a Converter instance.')
 
-        if converter is str or converter is type(None) or converter is _Greedy:
+        if converter in (str, type(None)) or origin is Greedy:
             raise TypeError(f'Greedy[{converter.__name__}] is invalid.')
 
-        if getattr(converter, '__origin__', None) is Union and type(None) in converter.__args__:
+        if origin is Union and type(None) in args:
             raise TypeError(f'Greedy[{converter!r}] is invalid.')
 
-        return self.__class__(converter=converter)
+        return cls(converter=converter)
 
-Greedy = _Greedy()
+
+def _convert_to_bool(argument: str) -> bool:
+    lowered = argument.lower()
+    if lowered in ('yes', 'y', 'true', 't', '1', 'enable', 'on'):
+        return True
+    elif lowered in ('no', 'n', 'false', 'f', '0', 'disable', 'off'):
+        return False
+    else:
+        raise BadBoolArgument(lowered)
+
+
+def get_converter(param: inspect.Parameter) -> Any:
+    converter = param.annotation
+    if converter is param.empty:
+        if param.default is not param.empty:
+            converter = str if param.default is None else type(param.default)
+        else:
+            converter = str
+    return converter
+
+
+_GenericAlias = type(List[T])
+
+
+def is_generic_type(tp: Any, *, _GenericAlias: Type = _GenericAlias) -> bool:
+    return isinstance(tp, type) and issubclass(tp, Generic) or isinstance(tp, _GenericAlias)  # type: ignore
+
+
+CONVERTER_MAPPING: Dict[Type[Any], Any] = {
+    discord.Object: ObjectConverter,
+    discord.Member: MemberConverter,
+    discord.User: UserConverter,
+    discord.Message: MessageConverter,
+    discord.PartialMessage: PartialMessageConverter,
+    discord.TextChannel: TextChannelConverter,
+    discord.Invite: InviteConverter,
+    discord.Guild: GuildConverter,
+    discord.Role: RoleConverter,
+    discord.Game: GameConverter,
+    discord.Colour: ColourConverter,
+    discord.VoiceChannel: VoiceChannelConverter,
+    discord.StageChannel: StageChannelConverter,
+    discord.Emoji: EmojiConverter,
+    discord.PartialEmoji: PartialEmojiConverter,
+    discord.CategoryChannel: CategoryChannelConverter,
+    discord.StoreChannel: StoreChannelConverter,
+    discord.Thread: ThreadConverter,
+    discord.abc.GuildChannel: GuildChannelConverter,
+    discord.GuildSticker: GuildStickerConverter,
+}
+
+
+async def _actual_conversion(ctx: Context, converter, argument: str, param: inspect.Parameter):
+    if converter is bool:
+        return _convert_to_bool(argument)
+
+    try:
+        module = converter.__module__
+    except AttributeError:
+        pass
+    else:
+        if module is not None and (module.startswith('discord.') and not module.endswith('converter')):
+            converter = CONVERTER_MAPPING.get(converter, converter)
+
+    try:
+        if inspect.isclass(converter) and issubclass(converter, Converter):
+            if inspect.ismethod(converter.convert):
+                return await converter.convert(ctx, argument)
+            else:
+                return await converter().convert(ctx, argument)
+        elif isinstance(converter, Converter):
+            return await converter.convert(ctx, argument)
+    except CommandError:
+        raise
+    except Exception as exc:
+        raise ConversionError(converter, exc) from exc
+
+    try:
+        return converter(argument)
+    except CommandError:
+        raise
+    except Exception as exc:
+        try:
+            name = converter.__name__
+        except AttributeError:
+            name = converter.__class__.__name__
+
+        raise BadArgument(f'Converting to "{name}" failed for parameter "{param.name}".') from exc
+
+
+async def run_converters(ctx: Context, converter, argument: str, param: inspect.Parameter):
+    """|coro|
+
+    Runs converters for a given converter, argument, and parameter.
+
+    This function does the same work that the library does under the hood.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    ------------
+    ctx: :class:`Context`
+        The invocation context to run the converters under.
+    converter: Any
+        The converter to run, this corresponds to the annotation in the function.
+    argument: :class:`str`
+        The argument to convert to.
+    param: :class:`inspect.Parameter`
+        The parameter being converted. This is mainly for error reporting.
+
+    Raises
+    -------
+    CommandError
+        The converter failed to convert.
+
+    Returns
+    --------
+    Any
+        The resulting conversion.
+    """
+    origin = getattr(converter, '__origin__', None)
+
+    if origin is Union:
+        errors = []
+        _NoneType = type(None)
+        union_args = converter.__args__
+        for conv in union_args:
+            # if we got to this part in the code, then the previous conversions have failed
+            # so we should just undo the view, return the default, and allow parsing to continue
+            # with the other parameters
+            if conv is _NoneType and param.kind != param.VAR_POSITIONAL:
+                ctx.view.undo()
+                return None if param.default is param.empty else param.default
+
+            try:
+                value = await run_converters(ctx, conv, argument, param)
+            except CommandError as exc:
+                errors.append(exc)
+            else:
+                return value
+
+        # if we're here, then we failed all the converters
+        raise BadUnionArgument(param, union_args, errors)
+
+    if origin is Literal:
+        errors = []
+        conversions = {}
+        literal_args = converter.__args__
+        for literal in literal_args:
+            literal_type = type(literal)
+            try:
+                value = conversions[literal_type]
+            except KeyError:
+                try:
+                    value = await _actual_conversion(ctx, literal_type, argument, param)
+                except CommandError as exc:
+                    errors.append(exc)
+                    conversions[literal_type] = object()
+                    continue
+                else:
+                    conversions[literal_type] = value
+
+            if value == literal:
+                return value
+
+        # if we're here, then we failed to match all the literals
+        raise BadLiteralArgument(param, literal_args, errors)
+
+    # This must be the last if-clause in the chain of origin checking
+    # Nearly every type is a generic type within the typing library
+    # So care must be taken to make sure a more specialised origin handle
+    # isn't overwritten by the widest if clause
+    if origin is not None and is_generic_type(converter):
+        converter = origin
+
+    return await _actual_conversion(ctx, converter, argument, param)

discord/ext/commands/cooldowns.py

@@ -22,6 +22,10 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+
+from typing import Any, Callable, Deque, Dict, Optional, Type, TypeVar, TYPE_CHECKING
 from discord.enums import Enum
 import time
 import asyncio
@@ -30,13 +34,20 @@ from collections import deque
 from ...abc import PrivateChannel
 from .errors import MaxConcurrencyReached
 
+if TYPE_CHECKING:
+    from ...message import Message
+
 __all__ = (
     'BucketType',
     'Cooldown',
     'CooldownMapping',
+    'DynamicCooldownMapping',
     'MaxConcurrency',
 )
 
+C = TypeVar('C', bound='CooldownMapping')
+MC = TypeVar('MC', bound='MaxConcurrency')
+
 class BucketType(Enum):
     default  = 0
     user     = 1
@@ -46,7 +57,7 @@ class BucketType(Enum):
     category = 5
     role     = 6
 
-    def get_key(self, msg):
+    def get_key(self, msg: Message) -> Any:
         if self is BucketType.user:
             return msg.author.id
         elif self is BucketType.guild:
@@ -56,33 +67,52 @@ class BucketType(Enum):
         elif self is BucketType.member:
             return ((msg.guild and msg.guild.id), msg.author.id)
         elif self is BucketType.category:
-            return (msg.channel.category or msg.channel).id
+            return (msg.channel.category or msg.channel).id  # type: ignore
         elif self is BucketType.role:
             # we return the channel id of a private-channel as there are only roles in guilds
             # and that yields the same result as for a guild with only the @everyone role
             # NOTE: PrivateChannel doesn't actually have an id attribute but we assume we are
             # recieving a DMChannel or GroupChannel which inherit from PrivateChannel and do
-            return (msg.channel if isinstance(msg.channel, PrivateChannel) else msg.author.top_role).id
+            return (msg.channel if isinstance(msg.channel, PrivateChannel) else msg.author.top_role).id  # type: ignore
 
-    def __call__(self, msg):
+    def __call__(self, msg: Message) -> Any:
         return self.get_key(msg)
 
 
 class Cooldown:
-    __slots__ = ('rate', 'per', 'type', '_window', '_tokens', '_last')
+    """Represents a cooldown for a command.
 
-    def __init__(self, rate, per, type):
-        self.rate = int(rate)
-        self.per = float(per)
-        self.type = type
-        self._window = 0.0
-        self._tokens = self.rate
-        self._last = 0.0
+    Attributes
+    -----------
+    rate: :class:`int`
+        The total number of tokens available per :attr:`per` seconds.
+    per: :class:`float`
+        The length of the cooldown period in seconds.
+    """
 
-        if not callable(self.type):
-            raise TypeError('Cooldown type must be a BucketType or callable')
+    __slots__ = ('rate', 'per', '_window', '_tokens', '_last')
 
-    def get_tokens(self, current=None):
+    def __init__(self, rate: float, per: float) -> None:
+        self.rate: int = int(rate)
+        self.per: float = float(per)
+        self._window: float = 0.0
+        self._tokens: int = self.rate
+        self._last: float = 0.0
+
+    def get_tokens(self, current: Optional[float] = None) -> int:
+        """Returns the number of available tokens before rate limiting is applied.
+
+        Parameters
+        ------------
+        current: Optional[:class:`float`]
+            The time in seconds since Unix epoch to calculate tokens at.
+            If not supplied then :func:`time.time()` is used.
+
+        Returns
+        --------
+        :class:`int`
+            The number of tokens available before the cooldown is to be applied.
+        """
         if not current:
             current = time.time()
 
@@ -92,7 +122,20 @@ class Cooldown:
             tokens = self.rate
         return tokens
 
-    def get_retry_after(self, current=None):
+    def get_retry_after(self, current: Optional[float] = None) -> float:
+        """Returns the time in seconds until the cooldown will be reset.
+
+        Parameters
+        -------------
+        current: Optional[:class:`float`]
+            The current time in seconds since Unix epoch.
+            If not supplied, then :func:`time.time()` is used.
+
+        Returns
+        -------
+        :class:`float`
+            The number of seconds to wait before this cooldown will be reset.
+        """
         current = current or time.time()
         tokens = self.get_tokens(current)
 
@@ -101,7 +144,20 @@ class Cooldown:
 
         return 0.0
 
-    def update_rate_limit(self, current=None):
+    def update_rate_limit(self, current: Optional[float] = None) -> Optional[float]:
+        """Updates the cooldown rate limit.
+
+        Parameters
+        -------------
+        current: Optional[:class:`float`]
+            The time in seconds since Unix epoch to update the rate limit at.
+            If not supplied, then :func:`time.time()` is used.
+
+        Returns
+        -------
+        Optional[:class:`float`]
+            The retry-after time in seconds if rate limited.
+        """
         current = current or time.time()
         self._last = current
 
@@ -118,43 +174,58 @@ class Cooldown:
         # we're not so decrement our tokens
         self._tokens -= 1
 
-        # see if we got rate limited due to this token change, and if
-        # so update the window to point to our current time frame
-        if self._tokens == 0:
-            self._window = current
-
-    def reset(self):
+    def reset(self) -> None:
+        """Reset the cooldown to its initial state."""
         self._tokens = self.rate
         self._last = 0.0
 
-    def copy(self):
-        return Cooldown(self.rate, self.per, self.type)
+    def copy(self) -> Cooldown:
+        """Creates a copy of this cooldown.
 
-    def __repr__(self):
-        return '<Cooldown rate: {0.rate} per: {0.per} window: {0._window} tokens: {0._tokens}>'.format(self)
+        Returns
+        --------
+        :class:`Cooldown`
+            A new instance of this cooldown.
+        """
+        return Cooldown(self.rate, self.per)
+
+    def __repr__(self) -> str:
+        return f'<Cooldown rate: {self.rate} per: {self.per} window: {self._window} tokens: {self._tokens}>'
 
 class CooldownMapping:
-    def __init__(self, original):
-        self._cache = {}
-        self._cooldown = original
+    def __init__(
+        self,
+        original: Optional[Cooldown],
+        type: Callable[[Message], Any],
+    ) -> None:
+        if not callable(type):
+            raise TypeError('Cooldown type must be a BucketType or callable')
 
-    def copy(self):
-        ret = CooldownMapping(self._cooldown)
+        self._cache: Dict[Any, Cooldown] = {}
+        self._cooldown: Optional[Cooldown] = original
+        self._type: Callable[[Message], Any] = type
+
+    def copy(self) -> CooldownMapping:
+        ret = CooldownMapping(self._cooldown, self._type)
         ret._cache = self._cache.copy()
         return ret
 
     @property
-    def valid(self):
+    def valid(self) -> bool:
         return self._cooldown is not None
 
+    @property
+    def type(self) -> Callable[[Message], Any]:
+        return self._type
+
     @classmethod
-    def from_cooldown(cls, rate, per, type):
-        return cls(Cooldown(rate, per, type))
+    def from_cooldown(cls: Type[C], rate, per, type) -> C:
+        return cls(Cooldown(rate, per), type)
 
-    def _bucket_key(self, msg):
-        return self._cooldown.type(msg)
+    def _bucket_key(self, msg: Message) -> Any:
+        return self._type(msg)
 
-    def _verify_cache_integrity(self, current=None):
+    def _verify_cache_integrity(self, current: Optional[float] = None) -> None:
         # we want to delete all cache objects that haven't been used
         # in a cooldown window. e.g. if we have a  command that has a
         # cooldown of 60s and it has not been used in 60s then that key should be deleted
@@ -163,24 +234,50 @@ class CooldownMapping:
         for k in dead_keys:
             del self._cache[k]
 
-    def get_bucket(self, message, current=None):
-        if self._cooldown.type is BucketType.default:
-            return self._cooldown
+    def create_bucket(self, message: Message) -> Cooldown:
+        return self._cooldown.copy()  # type: ignore
+
+    def get_bucket(self, message: Message, current: Optional[float] = None) -> Cooldown:
+        if self._type is BucketType.default:
+            return self._cooldown  # type: ignore
 
         self._verify_cache_integrity(current)
         key = self._bucket_key(message)
         if key not in self._cache:
-            bucket = self._cooldown.copy()
-            self._cache[key] = bucket
+            bucket = self.create_bucket(message)
+            if bucket is not None:
+                self._cache[key] = bucket
         else:
             bucket = self._cache[key]
 
         return bucket
 
-    def update_rate_limit(self, message, current=None):
+    def update_rate_limit(self, message: Message, current: Optional[float] = None) -> Optional[float]:
         bucket = self.get_bucket(message, current)
         return bucket.update_rate_limit(current)
 
+class DynamicCooldownMapping(CooldownMapping):
+
+    def __init__(
+        self,
+        factory: Callable[[Message], Cooldown],
+        type: Callable[[Message], Any]
+    ) -> None:
+        super().__init__(None, type)
+        self._factory: Callable[[Message], Cooldown] = factory
+
+    def copy(self) -> DynamicCooldownMapping:
+        ret = DynamicCooldownMapping(self._factory, self._type)
+        ret._cache = self._cache.copy()
+        return ret
+
+    @property
+    def valid(self) -> bool:
+        return True
+
+    def create_bucket(self, message: Message) -> Cooldown:
+        return self._factory(message)
+
 class _Semaphore:
     """This class is a version of a semaphore.
 
@@ -196,28 +293,28 @@ class _Semaphore:
 
     __slots__ = ('value', 'loop', '_waiters')
 
-    def __init__(self, number):
-        self.value = number
-        self.loop = asyncio.get_event_loop()
-        self._waiters = deque()
+    def __init__(self, number: int) -> None:
+        self.value: int = number
+        self.loop: asyncio.AbstractEventLoop = asyncio.get_event_loop()
+        self._waiters: Deque[asyncio.Future] = deque()
 
-    def __repr__(self):
-        return '<_Semaphore value={0.value} waiters={1}>'.format(self, len(self._waiters))
+    def __repr__(self) -> str:
+        return f'<_Semaphore value={self.value} waiters={len(self._waiters)}>'
 
-    def locked(self):
+    def locked(self) -> bool:
         return self.value == 0
 
-    def is_active(self):
+    def is_active(self) -> bool:
         return len(self._waiters) > 0
 
-    def wake_up(self):
+    def wake_up(self) -> None:
         while self._waiters:
             future = self._waiters.popleft()
             if not future.done():
                 future.set_result(None)
                 return
 
-    async def acquire(self, *, wait=False):
+    async def acquire(self, *, wait: bool = False) -> bool:
         if not wait and self.value <= 0:
             # signal that we're not acquiring
             return False
@@ -236,18 +333,18 @@ class _Semaphore:
         self.value -= 1
         return True
 
-    def release(self):
+    def release(self) -> None:
         self.value += 1
         self.wake_up()
 
 class MaxConcurrency:
     __slots__ = ('number', 'per', 'wait', '_mapping')
 
-    def __init__(self, number, *, per, wait):
-        self._mapping = {}
-        self.per = per
-        self.number = number
-        self.wait = wait
+    def __init__(self, number: int, *, per: BucketType, wait: bool) -> None:
+        self._mapping: Dict[Any, _Semaphore] = {}
+        self.per: BucketType = per
+        self.number: int = number
+        self.wait: bool = wait
 
         if number <= 0:
             raise ValueError('max_concurrency \'number\' cannot be less than 1')
@@ -255,16 +352,16 @@ class MaxConcurrency:
         if not isinstance(per, BucketType):
             raise TypeError(f'max_concurrency \'per\' must be of type BucketType not {type(per)!r}')
 
-    def copy(self):
+    def copy(self: MC) -> MC:
         return self.__class__(self.number, per=self.per, wait=self.wait)
 
-    def __repr__(self):
-        return '<MaxConcurrency per={0.per!r} number={0.number} wait={0.wait}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<MaxConcurrency per={self.per!r} number={self.number} wait={self.wait}>'
 
-    def get_key(self, message):
+    def get_key(self, message: Message) -> Any:
         return self.per.get_key(message)
 
-    async def acquire(self, message):
+    async def acquire(self, message: Message) -> None:
         key = self.get_key(message)
 
         try:
@@ -276,7 +373,7 @@ class MaxConcurrency:
         if not acquired:
             raise MaxConcurrencyReached(self.number, self.per)
 
-    async def release(self, message):
+    async def release(self, message: Message) -> None:
         # Technically there's no reason for this function to be async
         # But it might be more useful in the future
         key = self.get_key(message)

discord/ext/commands/errors.py

@@ -22,8 +22,23 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import Optional, Any, TYPE_CHECKING, List, Callable, Type, Tuple, Union
+
 from discord.errors import ClientException, DiscordException
 
+if TYPE_CHECKING:
+    from inspect import Parameter
+
+    from .converter import Converter
+    from .context import Context
+    from .cooldowns import Cooldown, BucketType
+    from .flags import Flag
+    from discord.abc import GuildChannel
+    from discord.threads import Thread
+    from discord.types.snowflake import Snowflake, SnowflakeList
+
 
 __all__ = (
     'CommandError',
@@ -42,15 +57,19 @@ __all__ = (
     'MaxConcurrencyReached',
     'NotOwner',
     'MessageNotFound',
+    'ObjectNotFound',
     'MemberNotFound',
     'GuildNotFound',
     'UserNotFound',
     'ChannelNotFound',
+    'ThreadNotFound',
     'ChannelNotReadable',
     'BadColourArgument',
+    'BadColorArgument',
     'RoleNotFound',
     'BadInviteArgument',
     'EmojiNotFound',
+    'GuildStickerNotFound',
     'PartialEmojiConversionFailure',
     'BadBoolArgument',
     'MissingRole',
@@ -62,6 +81,7 @@ __all__ = (
     'NSFWChannelRequired',
     'ConversionError',
     'BadUnionArgument',
+    'BadLiteralArgument',
     'ArgumentParsingError',
     'UnexpectedQuoteError',
     'InvalidEndOfQuotedStringError',
@@ -73,6 +93,11 @@ __all__ = (
     'ExtensionFailed',
     'ExtensionNotFound',
     'CommandRegistrationError',
+    'FlagError',
+    'BadFlagArgument',
+    'MissingFlagArgument',
+    'TooManyFlags',
+    'MissingRequiredFlag',
 )
 
 class CommandError(DiscordException):
@@ -82,9 +107,9 @@ class CommandError(DiscordException):
 
     This exception and exceptions inherited from it are handled
     in a special way as they are caught and passed into a special event
-    from :class:`.Bot`\, :func:`on_command_error`.
+    from :class:`.Bot`\, :func:`.on_command_error`.
     """
-    def __init__(self, message=None, *args):
+    def __init__(self, message: Optional[str] = None, *args: Any) -> None:
         if message is not None:
             # clean-up @everyone and @here mentions
             m = message.replace('@everyone', '@\u200beveryone').replace('@here', '@\u200bhere')
@@ -105,9 +130,9 @@ class ConversionError(CommandError):
         The original exception that was raised. You can also get this via
         the ``__cause__`` attribute.
     """
-    def __init__(self, converter, original):
-        self.converter = converter
-        self.original = original
+    def __init__(self, converter: Converter, original: Exception) -> None:
+        self.converter: Converter = converter
+        self.original: Exception = original
 
 class UserInputError(CommandError):
     """The base exception type for errors that involve errors
@@ -139,8 +164,8 @@ class MissingRequiredArgument(UserInputError):
     param: :class:`inspect.Parameter`
         The argument that is missing.
     """
-    def __init__(self, param):
-        self.param = param
+    def __init__(self, param: Parameter) -> None:
+        self.param: Parameter = param
         super().__init__(f'{param.name} is a required argument that is missing.')
 
 class TooManyArguments(UserInputError):
@@ -181,9 +206,9 @@ class CheckAnyFailure(CheckFailure):
         A list of check predicates that failed.
     """
 
-    def __init__(self, checks, errors):
-        self.checks = checks
-        self.errors = errors
+    def __init__(self, checks: List[CheckFailure], errors: List[Callable[[Context], bool]]) -> None:
+        self.checks: List[CheckFailure] = checks
+        self.errors: List[Callable[[Context], bool]] = errors
         super().__init__('You do not have permission to run this command.')
 
 class PrivateMessageOnly(CheckFailure):
@@ -192,7 +217,7 @@ class PrivateMessageOnly(CheckFailure):
 
     This inherits from :exc:`CheckFailure`
     """
-    def __init__(self, message=None):
+    def __init__(self, message: Optional[str] = None) -> None:
         super().__init__(message or 'This command can only be used in private messages.')
 
 class NoPrivateMessage(CheckFailure):
@@ -202,7 +227,7 @@ class NoPrivateMessage(CheckFailure):
     This inherits from :exc:`CheckFailure`
     """
 
-    def __init__(self, message=None):
+    def __init__(self, message: Optional[str] = None) -> None:
         super().__init__(message or 'This command cannot be used in private messages.')
 
 class NotOwner(CheckFailure):
@@ -212,6 +237,23 @@ class NotOwner(CheckFailure):
     """
     pass
 
+class ObjectNotFound(BadArgument):
+    """Exception raised when the argument provided did not match the format
+    of an ID or a mention.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    argument: :class:`str`
+        The argument supplied by the caller that was not matched
+    """
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'{argument!r} does not follow a valid ID or mention format.')
+
 class MemberNotFound(BadArgument):
     """Exception raised when the member provided was not found in the bot's
     cache.
@@ -225,8 +267,8 @@ class MemberNotFound(BadArgument):
     argument: :class:`str`
         The member supplied by the caller that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Member "{argument}" not found.')
 
 class GuildNotFound(BadArgument):
@@ -241,8 +283,8 @@ class GuildNotFound(BadArgument):
     argument: :class:`str`
         The guild supplied by the called that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Guild "{argument}" not found.')
 
 class UserNotFound(BadArgument):
@@ -258,8 +300,8 @@ class UserNotFound(BadArgument):
     argument: :class:`str`
         The user supplied by the caller that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'User "{argument}" not found.')
 
 class MessageNotFound(BadArgument):
@@ -274,8 +316,8 @@ class MessageNotFound(BadArgument):
     argument: :class:`str`
         The message supplied by the caller that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Message "{argument}" not found.')
 
 class ChannelNotReadable(BadArgument):
@@ -288,11 +330,11 @@ class ChannelNotReadable(BadArgument):
 
     Attributes
     -----------
-    argument: :class:`.abc.GuildChannel`
+    argument: Union[:class:`.abc.GuildChannel`, :class:`.Thread`]
         The channel supplied by the caller that was not readable
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: Union[GuildChannel, Thread]) -> None:
+        self.argument: Union[GuildChannel, Thread] = argument
         super().__init__(f"Can't read messages in {argument.mention}.")
 
 class ChannelNotFound(BadArgument):
@@ -307,10 +349,26 @@ class ChannelNotFound(BadArgument):
     argument: :class:`str`
         The channel supplied by the caller that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Channel "{argument}" not found.')
 
+class ThreadNotFound(BadArgument):
+    """Exception raised when the bot can not find the thread.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    argument: :class:`str`
+        The thread supplied by the caller that was not found
+    """
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'Thread "{argument}" not found.')
+
 class BadColourArgument(BadArgument):
     """Exception raised when the colour is not valid.
 
@@ -323,8 +381,8 @@ class BadColourArgument(BadArgument):
     argument: :class:`str`
         The colour supplied by the caller that was not valid
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Colour "{argument}" is invalid.')
 
 BadColorArgument = BadColourArgument
@@ -341,8 +399,8 @@ class RoleNotFound(BadArgument):
     argument: :class:`str`
         The role supplied by the caller that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Role "{argument}" not found.')
 
 class BadInviteArgument(BadArgument):
@@ -352,8 +410,9 @@ class BadInviteArgument(BadArgument):
 
     .. versionadded:: 1.5
     """
-    def __init__(self):
-        super().__init__('Invite is invalid or expired.')
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'Invite "{argument}" is invalid or expired.')
 
 class EmojiNotFound(BadArgument):
     """Exception raised when the bot can not find the emoji.
@@ -367,8 +426,8 @@ class EmojiNotFound(BadArgument):
     argument: :class:`str`
         The emoji supplied by the caller that was not found
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Emoji "{argument}" not found.')
 
 class PartialEmojiConversionFailure(BadArgument):
@@ -384,10 +443,26 @@ class PartialEmojiConversionFailure(BadArgument):
     argument: :class:`str`
         The emoji supplied by the caller that did not match the regex
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'Couldn\'t convert "{argument}" to PartialEmoji.')
 
+class GuildStickerNotFound(BadArgument):
+    """Exception raised when the bot can not find the sticker.
+
+    This inherits from :exc:`BadArgument`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    argument: :class:`str`
+        The sticker supplied by the caller that was not found
+    """
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'Sticker "{argument}" not found.')
+
 class BadBoolArgument(BadArgument):
     """Exception raised when a boolean argument was not convertable.
 
@@ -400,8 +475,8 @@ class BadBoolArgument(BadArgument):
     argument: :class:`str`
         The boolean argument supplied by the caller that is not in the predefined list
     """
-    def __init__(self, argument):
-        self.argument = argument
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
         super().__init__(f'{argument} is not a recognised boolean option')
 
 class DisabledCommand(CommandError):
@@ -422,9 +497,9 @@ class CommandInvokeError(CommandError):
         The original exception that was raised. You can also get this via
         the ``__cause__`` attribute.
     """
-    def __init__(self, e):
-        self.original = e
-        super().__init__('Command raised an exception: {0.__class__.__name__}: {0}'.format(e))
+    def __init__(self, e: Exception) -> None:
+        self.original: Exception = e
+        super().__init__(f'Command raised an exception: {e.__class__.__name__}: {e}')
 
 class CommandOnCooldown(CommandError):
     """Exception raised when the command being invoked is on cooldown.
@@ -433,15 +508,18 @@ class CommandOnCooldown(CommandError):
 
     Attributes
     -----------
-    cooldown: Cooldown
-        A class with attributes ``rate``, ``per``, and ``type`` similar to
-        the :func:`.cooldown` decorator.
+    cooldown: :class:`.Cooldown`
+        A class with attributes ``rate`` and ``per`` similar to the
+        :func:`.cooldown` decorator.
+    type: :class:`BucketType`
+        The type associated with the cooldown.
     retry_after: :class:`float`
         The amount of seconds to wait before you can retry again.
     """
-    def __init__(self, cooldown, retry_after):
-        self.cooldown = cooldown
-        self.retry_after = retry_after
+    def __init__(self, cooldown: Cooldown, retry_after: float, type: BucketType) -> None:
+        self.cooldown: Cooldown = cooldown
+        self.retry_after: float = retry_after
+        self.type: BucketType = type
         super().__init__(f'You are on cooldown. Try again in {retry_after:.2f}s')
 
 class MaxConcurrencyReached(CommandError):
@@ -457,14 +535,14 @@ class MaxConcurrencyReached(CommandError):
         The bucket type passed to the :func:`.max_concurrency` decorator.
     """
 
-    def __init__(self, number, per):
-        self.number = number
-        self.per = per
+    def __init__(self, number: int, per: BucketType) -> None:
+        self.number: int = number
+        self.per: BucketType = per
         name = per.name
         suffix = 'per %s' % name if per.name != 'default' else 'globally'
         plural = '%s times %s' if number > 1 else '%s time %s'
         fmt = plural % (number, suffix)
-        super().__init__(f'Too many people using this command. It can only be used {fmt} concurrently.')
+        super().__init__(f'Too many people are using this command. It can only be used {fmt} concurrently.')
 
 class MissingRole(CheckFailure):
     """Exception raised when the command invoker lacks a role to run a command.
@@ -479,8 +557,8 @@ class MissingRole(CheckFailure):
         The required role that is missing.
         This is the parameter passed to :func:`~.commands.has_role`.
     """
-    def __init__(self, missing_role):
-        self.missing_role = missing_role
+    def __init__(self, missing_role: Snowflake) -> None:
+        self.missing_role: Snowflake = missing_role
         message = f'Role {missing_role!r} is required to run this command.'
         super().__init__(message)
 
@@ -497,8 +575,8 @@ class BotMissingRole(CheckFailure):
         The required role that is missing.
         This is the parameter passed to :func:`~.commands.has_role`.
     """
-    def __init__(self, missing_role):
-        self.missing_role = missing_role
+    def __init__(self, missing_role: Snowflake) -> None:
+        self.missing_role: Snowflake = missing_role
         message = f'Bot requires the role {missing_role!r} to run this command'
         super().__init__(message)
 
@@ -516,8 +594,8 @@ class MissingAnyRole(CheckFailure):
         The roles that the invoker is missing.
         These are the parameters passed to :func:`~.commands.has_any_role`.
     """
-    def __init__(self, missing_roles):
-        self.missing_roles = missing_roles
+    def __init__(self, missing_roles: SnowflakeList) -> None:
+        self.missing_roles: SnowflakeList = missing_roles
 
         missing = [f"'{role}'" for role in missing_roles]
 
@@ -545,8 +623,8 @@ class BotMissingAnyRole(CheckFailure):
         These are the parameters passed to :func:`~.commands.has_any_role`.
 
     """
-    def __init__(self, missing_roles):
-        self.missing_roles = missing_roles
+    def __init__(self, missing_roles: SnowflakeList) -> None:
+        self.missing_roles: SnowflakeList = missing_roles
 
         missing = [f"'{role}'" for role in missing_roles]
 
@@ -567,11 +645,11 @@ class NSFWChannelRequired(CheckFailure):
 
     Parameters
     -----------
-    channel: :class:`discord.abc.GuildChannel`
+    channel: Union[:class:`.abc.GuildChannel`, :class:`.Thread`]
         The channel that does not have NSFW enabled.
     """
-    def __init__(self, channel):
-        self.channel = channel
+    def __init__(self, channel: Union[GuildChannel, Thread]) -> None:
+        self.channel: Union[GuildChannel, Thread] = channel
         super().__init__(f"Channel '{channel}' needs to be NSFW for this command to work.")
 
 class MissingPermissions(CheckFailure):
@@ -582,13 +660,13 @@ class MissingPermissions(CheckFailure):
 
     Attributes
     -----------
-    missing_perms: :class:`list`
+    missing_permissions: List[:class:`str`]
         The required permissions that are missing.
     """
-    def __init__(self, missing_perms, *args):
-        self.missing_perms = missing_perms
+    def __init__(self, missing_permissions: List[str], *args: Any) -> None:
+        self.missing_permissions: List[str] = missing_permissions
 
-        missing = [perm.replace('_', ' ').replace('guild', 'server').title() for perm in missing_perms]
+        missing = [perm.replace('_', ' ').replace('guild', 'server').title() for perm in missing_permissions]
 
         if len(missing) > 2:
             fmt = '{}, and {}'.format(", ".join(missing[:-1]), missing[-1])
@@ -605,13 +683,13 @@ class BotMissingPermissions(CheckFailure):
 
     Attributes
     -----------
-    missing_perms: :class:`list`
+    missing_permissions: List[:class:`str`]
         The required permissions that are missing.
     """
-    def __init__(self, missing_perms, *args):
-        self.missing_perms = missing_perms
+    def __init__(self, missing_permissions: List[str], *args: Any) -> None:
+        self.missing_permissions: List[str] = missing_permissions
 
-        missing = [perm.replace('_', ' ').replace('guild', 'server').title() for perm in missing_perms]
+        missing = [perm.replace('_', ' ').replace('guild', 'server').title() for perm in missing_permissions]
 
         if len(missing) > 2:
             fmt = '{}, and {}'.format(", ".join(missing[:-1]), missing[-1])
@@ -630,20 +708,22 @@ class BadUnionArgument(UserInputError):
     -----------
     param: :class:`inspect.Parameter`
         The parameter that failed being converted.
-    converters: Tuple[Type, ...]
+    converters: Tuple[Type, ``...``]
         A tuple of converters attempted in conversion, in order of failure.
     errors: List[:class:`CommandError`]
         A list of errors that were caught from failing the conversion.
     """
-    def __init__(self, param, converters, errors):
-        self.param = param
-        self.converters = converters
-        self.errors = errors
+    def __init__(self, param: Parameter, converters: Tuple[Type, ...], errors: List[CommandError]) -> None:
+        self.param: Parameter = param
+        self.converters: Tuple[Type, ...] = converters
+        self.errors: List[CommandError] = errors
 
         def _get_name(x):
             try:
                 return x.__name__
             except AttributeError:
+                if hasattr(x, '__origin__'):
+                    return repr(x)
                 return x.__class__.__name__
 
         to_string = [_get_name(x) for x in converters]
@@ -654,6 +734,36 @@ class BadUnionArgument(UserInputError):
 
         super().__init__(f'Could not convert "{param.name}" into {fmt}.')
 
+class BadLiteralArgument(UserInputError):
+    """Exception raised when a :data:`typing.Literal` converter fails for all
+    its associated values.
+
+    This inherits from :exc:`UserInputError`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    param: :class:`inspect.Parameter`
+        The parameter that failed being converted.
+    literals: Tuple[Any, ``...``]
+        A tuple of values compared against in conversion, in order of failure.
+    errors: List[:class:`CommandError`]
+        A list of errors that were caught from failing the conversion.
+    """
+    def __init__(self, param: Parameter, literals: Tuple[Any, ...], errors: List[CommandError]) -> None:
+        self.param: Parameter = param
+        self.literals: Tuple[Any, ...] = literals
+        self.errors: List[CommandError] = errors
+
+        to_string = [repr(l) for l in literals]
+        if len(to_string) > 2:
+            fmt = '{}, or {}'.format(', '.join(to_string[:-1]), to_string[-1])
+        else:
+            fmt = ' or '.join(to_string)
+
+        super().__init__(f'Could not convert "{param.name}" into the literal {fmt}.')
+
 class ArgumentParsingError(UserInputError):
     """An exception raised when the parser fails to parse a user's input.
 
@@ -674,8 +784,8 @@ class UnexpectedQuoteError(ArgumentParsingError):
     quote: :class:`str`
         The quote mark that was found inside the non-quoted string.
     """
-    def __init__(self, quote):
-        self.quote = quote
+    def __init__(self, quote: str) -> None:
+        self.quote: str = quote
         super().__init__(f'Unexpected quote mark, {quote!r}, in non-quoted string')
 
 class InvalidEndOfQuotedStringError(ArgumentParsingError):
@@ -689,8 +799,8 @@ class InvalidEndOfQuotedStringError(ArgumentParsingError):
     char: :class:`str`
         The character found instead of the expected string.
     """
-    def __init__(self, char):
-        self.char = char
+    def __init__(self, char: str) -> None:
+        self.char: str = char
         super().__init__(f'Expected space after closing quotation but received {char!r}')
 
 class ExpectedClosingQuoteError(ArgumentParsingError):
@@ -704,8 +814,8 @@ class ExpectedClosingQuoteError(ArgumentParsingError):
         The quote character expected.
     """
 
-    def __init__(self, close_quote):
-        self.close_quote = close_quote
+    def __init__(self, close_quote: str) -> None:
+        self.close_quote: str = close_quote
         super().__init__(f'Expected closing {close_quote}.')
 
 class ExtensionError(DiscordException):
@@ -718,8 +828,8 @@ class ExtensionError(DiscordException):
     name: :class:`str`
         The extension that had an error.
     """
-    def __init__(self, message=None, *args, name):
-        self.name = name
+    def __init__(self, message: Optional[str] = None, *args: Any, name: str) -> None:
+        self.name: str = name
         message = message or f'Extension {name!r} had an error.'
         # clean-up @everyone and @here mentions
         m = message.replace('@everyone', '@\u200beveryone').replace('@here', '@\u200bhere')
@@ -730,7 +840,7 @@ class ExtensionAlreadyLoaded(ExtensionError):
 
     This inherits from :exc:`ExtensionError`
     """
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         super().__init__(f'Extension {name!r} is already loaded.', name=name)
 
 class ExtensionNotLoaded(ExtensionError):
@@ -738,7 +848,7 @@ class ExtensionNotLoaded(ExtensionError):
 
     This inherits from :exc:`ExtensionError`
     """
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         super().__init__(f'Extension {name!r} has not been loaded.', name=name)
 
 class NoEntryPointError(ExtensionError):
@@ -746,7 +856,7 @@ class NoEntryPointError(ExtensionError):
 
     This inherits from :exc:`ExtensionError`
     """
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         super().__init__(f"Extension {name!r} has no 'setup' function.", name=name)
 
 class ExtensionFailed(ExtensionError):
@@ -762,10 +872,10 @@ class ExtensionFailed(ExtensionError):
         The original exception that was raised. You can also get this via
         the ``__cause__`` attribute.
     """
-    def __init__(self, name, original):
-        self.original = original
-        fmt = 'Extension {0!r} raised an error: {1.__class__.__name__}: {1}'
-        super().__init__(fmt.format(name, original), name=name)
+    def __init__(self, name: str, original: Exception) -> None:
+        self.original: Exception = original
+        msg = f'Extension {name!r} raised an error: {original.__class__.__name__}: {original}'
+        super().__init__(msg, name=name)
 
 class ExtensionNotFound(ExtensionError):
     """An exception raised when an extension is not found.
@@ -779,13 +889,10 @@ class ExtensionNotFound(ExtensionError):
     -----------
     name: :class:`str`
         The extension that had the error.
-    original: :class:`NoneType`
-        Always ``None`` for backwards compatibility.
     """
-    def __init__(self, name, original=None):
-        self.original = None
-        fmt = 'Extension {0!r} could not be loaded.'
-        super().__init__(fmt.format(name), name=name)
+    def __init__(self, name: str) -> None:
+        msg = f'Extension {name!r} could not be loaded.'
+        super().__init__(msg, name=name)
 
 class CommandRegistrationError(ClientException):
     """An exception raised when the command can't be added
@@ -802,8 +909,89 @@ class CommandRegistrationError(ClientException):
     alias_conflict: :class:`bool`
         Whether the name that conflicts is an alias of the command we try to add.
     """
-    def __init__(self, name, *, alias_conflict=False):
-        self.name = name
-        self.alias_conflict = alias_conflict
+    def __init__(self, name: str, *, alias_conflict: bool = False) -> None:
+        self.name: str = name
+        self.alias_conflict: bool = alias_conflict
         type_ = 'alias' if alias_conflict else 'command'
         super().__init__(f'The {type_} {name} is already an existing command or alias.')
+
+class FlagError(BadArgument):
+    """The base exception type for all flag parsing related errors.
+
+    This inherits from :exc:`BadArgument`.
+
+    .. versionadded:: 2.0
+    """
+    pass
+
+class TooManyFlags(FlagError):
+    """An exception raised when a flag has received too many values.
+
+    This inherits from :exc:`FlagError`.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ------------
+    flag: :class:`~discord.ext.commands.Flag`
+        The flag that received too many values.
+    values: List[:class:`str`]
+        The values that were passed.
+    """
+    def __init__(self, flag: Flag, values: List[str]) -> None:
+        self.flag: Flag = flag
+        self.values: List[str] = values
+        super().__init__(f'Too many flag values, expected {flag.max_args} but received {len(values)}.')
+
+class BadFlagArgument(FlagError):
+    """An exception raised when a flag failed to convert a value.
+
+    This inherits from :exc:`FlagError`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    flag: :class:`~discord.ext.commands.Flag`
+        The flag that failed to convert.
+    """
+    def __init__(self, flag: Flag) -> None:
+        self.flag: Flag = flag
+        try:
+            name = flag.annotation.__name__
+        except AttributeError:
+            name = flag.annotation.__class__.__name__
+
+        super().__init__(f'Could not convert to {name!r} for flag {flag.name!r}')
+
+class MissingRequiredFlag(FlagError):
+    """An exception raised when a required flag was not given.
+
+    This inherits from :exc:`FlagError`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    flag: :class:`~discord.ext.commands.Flag`
+        The required flag that was not found.
+    """
+    def __init__(self, flag: Flag) -> None:
+        self.flag: Flag = flag
+        super().__init__(f'Flag {flag.name!r} is required and missing')
+
+class MissingFlagArgument(FlagError):
+    """An exception raised when a flag did not get a value.
+
+    This inherits from :exc:`FlagError`
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    flag: :class:`~discord.ext.commands.Flag`
+        The flag that did not get a value.
+    """
+    def __init__(self, flag: Flag) -> None:
+        self.flag: Flag = flag
+        super().__init__(f'Flag {flag.name!r} does not have an argument')

discord/ext/commands/flags.py

@@ -0,0 +1,618 @@
+"""
+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
+
+from .errors import (
+    BadFlagArgument,
+    CommandError,
+    MissingFlagArgument,
+    TooManyFlags,
+    MissingRequiredFlag,
+)
+
+from discord.utils import resolve_annotation
+from .view import StringView
+from .converter import run_converters
+
+from discord.utils import maybe_coroutine, MISSING
+from dataclasses import dataclass, field
+from typing import (
+    Dict,
+    Iterator,
+    Literal,
+    Optional,
+    Pattern,
+    Set,
+    TYPE_CHECKING,
+    Tuple,
+    List,
+    Any,
+    Type,
+    TypeVar,
+    Union,
+)
+
+import inspect
+import sys
+import re
+
+__all__ = (
+    'Flag',
+    'flag',
+    'FlagConverter',
+)
+
+
+if TYPE_CHECKING:
+    from .context import Context
+
+
+@dataclass
+class Flag:
+    """Represents a flag parameter for :class:`FlagConverter`.
+
+    The :func:`~discord.ext.commands.flag` function helps
+    create these flag objects, but it is not necessary to
+    do so. These cannot be constructed manually.
+
+    Attributes
+    ------------
+    name: :class:`str`
+        The name of the flag.
+    aliases: List[:class:`str`]
+        The aliases of the flag name.
+    attribute: :class:`str`
+        The attribute in the class that corresponds to this flag.
+    default: Any
+        The default value of the flag, if available.
+    annotation: Any
+        The underlying evaluated annotation of the flag.
+    max_args: :class:`int`
+        The maximum number of arguments the flag can accept.
+        A negative value indicates an unlimited amount of arguments.
+    override: :class:`bool`
+        Whether multiple given values overrides the previous value.
+    """
+
+    name: str = MISSING
+    aliases: List[str] = field(default_factory=list)
+    attribute: str = MISSING
+    annotation: Any = MISSING
+    default: Any = MISSING
+    max_args: int = MISSING
+    override: bool = MISSING
+    cast_to_dict: bool = False
+
+    @property
+    def required(self) -> bool:
+        """:class:`bool`: Whether the flag is required.
+
+        A required flag has no default value.
+        """
+        return self.default is MISSING
+
+
+def flag(
+    *,
+    name: str = MISSING,
+    aliases: List[str] = MISSING,
+    default: Any = MISSING,
+    max_args: int = MISSING,
+    override: bool = MISSING,
+) -> Any:
+    """Override default functionality and parameters of the underlying :class:`FlagConverter`
+    class attributes.
+
+    Parameters
+    ------------
+    name: :class:`str`
+        The flag name. If not given, defaults to the attribute name.
+    aliases: List[:class:`str`]
+        Aliases to the flag name. If not given no aliases are set.
+    default: Any
+        The default parameter. This could be either a value or a callable that takes
+        :class:`Context` as its sole parameter. If not given then it defaults to
+        the default value given to the attribute.
+    max_args: :class:`int`
+        The maximum number of arguments the flag can accept.
+        A negative value indicates an unlimited amount of arguments.
+        The default value depends on the annotation given.
+    override: :class:`bool`
+        Whether multiple given values overrides the previous value. The default
+        value depends on the annotation given.
+    """
+    return Flag(name=name, aliases=aliases, default=default, max_args=max_args, override=override)
+
+
+def validate_flag_name(name: str, forbidden: Set[str]):
+    if not name:
+        raise ValueError('flag names should not be empty')
+
+    for ch in name:
+        if ch.isspace():
+            raise ValueError(f'flag name {name!r} cannot have spaces')
+        if ch == '\\':
+            raise ValueError(f'flag name {name!r} cannot have backslashes')
+        if ch in forbidden:
+            raise ValueError(f'flag name {name!r} cannot have any of {forbidden!r} within them')
+
+
+def get_flags(namespace: Dict[str, Any], globals: Dict[str, Any], locals: Dict[str, Any]) -> Dict[str, Flag]:
+    annotations = namespace.get('__annotations__', {})
+    case_insensitive = namespace['__commands_flag_case_insensitive__']
+    flags: Dict[str, Flag] = {}
+    cache: Dict[str, Any] = {}
+    names: Set[str] = set()
+    for name, annotation in annotations.items():
+        flag = namespace.pop(name, MISSING)
+        if isinstance(flag, Flag):
+            flag.annotation = annotation
+        else:
+            flag = Flag(name=name, annotation=annotation, default=flag)
+
+        flag.attribute = name
+        if flag.name is MISSING:
+            flag.name = name
+
+        annotation = flag.annotation = resolve_annotation(flag.annotation, globals, locals, cache)
+
+        if flag.default is MISSING and hasattr(annotation, '__commands_is_flag__') and annotation._can_be_constructible():
+            flag.default = annotation._construct_default
+
+        if flag.aliases is MISSING:
+            flag.aliases = []
+
+        # Add sensible defaults based off of the type annotation
+        # <type> -> (max_args=1)
+        # List[str] -> (max_args=-1)
+        # Tuple[int, ...] -> (max_args=1)
+        # Dict[K, V] -> (max_args=-1, override=True)
+        # Union[str, int] -> (max_args=1)
+        # Optional[str] -> (default=None, max_args=1)
+
+        try:
+            origin = annotation.__origin__
+        except AttributeError:
+            # A regular type hint
+            if flag.max_args is MISSING:
+                flag.max_args = 1
+        else:
+            if origin is Union:
+                # typing.Union
+                if flag.max_args is MISSING:
+                    flag.max_args = 1
+                if annotation.__args__[-1] is type(None) and flag.default is MISSING:
+                    # typing.Optional
+                    flag.default = None
+            elif origin is tuple:
+                # typing.Tuple
+                # tuple parsing is e.g. `flag: peter 20`
+                # for Tuple[str, int] would give you flag: ('peter', 20)
+                if flag.max_args is MISSING:
+                    flag.max_args = 1
+            elif origin is list:
+                # typing.List
+                if flag.max_args is MISSING:
+                    flag.max_args = -1
+            elif origin is dict:
+                # typing.Dict[K, V]
+                # Equivalent to:
+                # typing.List[typing.Tuple[K, V]]
+                flag.cast_to_dict = True
+                if flag.max_args is MISSING:
+                    flag.max_args = -1
+                if flag.override is MISSING:
+                    flag.override = True
+            elif origin is Literal:
+                if flag.max_args is MISSING:
+                    flag.max_args = 1
+            else:
+                raise TypeError(f'Unsupported typing annotation {annotation!r} for {flag.name!r} flag')
+
+        if flag.override is MISSING:
+            flag.override = False
+
+        # Validate flag names are unique
+        name = flag.name.casefold() if case_insensitive else flag.name
+        if name in names:
+            raise TypeError(f'{flag.name!r} flag conflicts with previous flag or alias.')
+        else:
+            names.add(name)
+
+        for alias in flag.aliases:
+            # Validate alias is unique
+            alias = alias.casefold() if case_insensitive else alias
+            if alias in names:
+                raise TypeError(f'{flag.name!r} flag alias {alias!r} conflicts with previous flag or alias.')
+            else:
+                names.add(alias)
+
+        flags[flag.name] = flag
+
+    return flags
+
+
+class FlagsMeta(type):
+    if TYPE_CHECKING:
+        __commands_is_flag__: bool
+        __commands_flags__: Dict[str, Flag]
+        __commands_flag_aliases__: Dict[str, str]
+        __commands_flag_regex__: Pattern[str]
+        __commands_flag_case_insensitive__: bool
+        __commands_flag_delimiter__: str
+        __commands_flag_prefix__: str
+
+    def __new__(
+        cls: Type[type],
+        name: str,
+        bases: Tuple[type, ...],
+        attrs: Dict[str, Any],
+        *,
+        case_insensitive: bool = MISSING,
+        delimiter: str = MISSING,
+        prefix: str = MISSING,
+    ):
+        attrs['__commands_is_flag__'] = True
+
+        try:
+            global_ns = sys.modules[attrs['__module__']].__dict__
+        except KeyError:
+            global_ns = {}
+
+        frame = inspect.currentframe()
+        try:
+            if frame is None:
+                local_ns = {}
+            else:
+                if frame.f_back is None:
+                    local_ns = frame.f_locals
+                else:
+                    local_ns = frame.f_back.f_locals
+        finally:
+            del frame
+
+        flags: Dict[str, Flag] = {}
+        aliases: Dict[str, str] = {}
+        for base in reversed(bases):
+            if base.__dict__.get('__commands_is_flag__', False):
+                flags.update(base.__dict__['__commands_flags__'])
+                aliases.update(base.__dict__['__commands_flag_aliases__'])
+                if case_insensitive is MISSING:
+                    attrs['__commands_flag_case_insensitive__'] = base.__dict__['__commands_flag_case_insensitive__']
+                if delimiter is MISSING:
+                    attrs['__commands_flag_delimiter__'] = base.__dict__['__commands_flag_delimiter__']
+                if prefix is MISSING:
+                    attrs['__commands_flag_prefix__'] = base.__dict__['__commands_flag_prefix__']
+
+        if case_insensitive is not MISSING:
+            attrs['__commands_flag_case_insensitive__'] = case_insensitive
+        if delimiter is not MISSING:
+            attrs['__commands_flag_delimiter__'] = delimiter
+        if prefix is not MISSING:
+            attrs['__commands_flag_prefix__'] = prefix
+
+        case_insensitive = attrs.setdefault('__commands_flag_case_insensitive__', False)
+        delimiter = attrs.setdefault('__commands_flag_delimiter__', ':')
+        prefix = attrs.setdefault('__commands_flag_prefix__', '')
+
+        for flag_name, flag in get_flags(attrs, global_ns, local_ns).items():
+            flags[flag_name] = flag
+            aliases.update({alias_name: flag_name for alias_name in flag.aliases})
+
+        forbidden = set(delimiter).union(prefix)
+        for flag_name in flags:
+            validate_flag_name(flag_name, forbidden)
+        for alias_name in aliases:
+            validate_flag_name(alias_name, forbidden)
+
+        regex_flags = 0
+        if case_insensitive:
+            flags = {key.casefold(): value for key, value in flags.items()}
+            aliases = {key.casefold(): value.casefold() for key, value in aliases.items()}
+            regex_flags = re.IGNORECASE
+
+        keys = list(re.escape(k) for k in flags)
+        keys.extend(re.escape(a) for a in aliases)
+        keys = sorted(keys, key=lambda t: len(t), reverse=True)
+
+        joined = '|'.join(keys)
+        pattern = re.compile(f'(({re.escape(prefix)})(?P<flag>{joined}){re.escape(delimiter)})', regex_flags)
+        attrs['__commands_flag_regex__'] = pattern
+        attrs['__commands_flags__'] = flags
+        attrs['__commands_flag_aliases__'] = aliases
+
+        return type.__new__(cls, name, bases, attrs)
+
+
+async def tuple_convert_all(ctx: Context, argument: str, flag: Flag, converter: Any) -> Tuple[Any, ...]:
+    view = StringView(argument)
+    results = []
+    param: inspect.Parameter = ctx.current_parameter  # type: ignore
+    while not view.eof:
+        view.skip_ws()
+        if view.eof:
+            break
+
+        word = view.get_quoted_word()
+        if word is None:
+            break
+
+        try:
+            converted = await run_converters(ctx, converter, word, param)
+        except CommandError:
+            raise
+        except Exception as e:
+            raise BadFlagArgument(flag) from e
+        else:
+            results.append(converted)
+
+    return tuple(results)
+
+
+async def tuple_convert_flag(ctx: Context, argument: str, flag: Flag, converters: Any) -> Tuple[Any, ...]:
+    view = StringView(argument)
+    results = []
+    param: inspect.Parameter = ctx.current_parameter  # type: ignore
+    for converter in converters:
+        view.skip_ws()
+        if view.eof:
+            break
+
+        word = view.get_quoted_word()
+        if word is None:
+            break
+
+        try:
+            converted = await run_converters(ctx, converter, word, param)
+        except CommandError:
+            raise
+        except Exception as e:
+            raise BadFlagArgument(flag) from e
+        else:
+            results.append(converted)
+
+    if len(results) != len(converters):
+        raise BadFlagArgument(flag)
+
+    return tuple(results)
+
+
+async def convert_flag(ctx, argument: str, flag: Flag, annotation: Any = None) -> Any:
+    param: inspect.Parameter = ctx.current_parameter  # type: ignore
+    annotation = annotation or flag.annotation
+    try:
+        origin = annotation.__origin__
+    except AttributeError:
+        pass
+    else:
+        if origin is tuple:
+            if annotation.__args__[-1] is Ellipsis:
+                return await tuple_convert_all(ctx, argument, flag, annotation.__args__[0])
+            else:
+                return await tuple_convert_flag(ctx, argument, flag, annotation.__args__)
+        elif origin is list:
+            # typing.List[x]
+            annotation = annotation.__args__[0]
+            return await convert_flag(ctx, argument, flag, annotation)
+        elif origin is Union and annotation.__args__[-1] is type(None):
+            # typing.Optional[x]
+            annotation = Union[annotation.__args__[:-1]]
+            return await run_converters(ctx, annotation, argument, param)
+        elif origin is dict:
+            # typing.Dict[K, V] -> typing.Tuple[K, V]
+            return await tuple_convert_flag(ctx, argument, flag, annotation.__args__)
+
+    try:
+        return await run_converters(ctx, annotation, argument, param)
+    except CommandError:
+        raise
+    except Exception as e:
+        raise BadFlagArgument(flag) from e
+
+
+F = TypeVar('F', bound='FlagConverter')
+
+
+class FlagConverter(metaclass=FlagsMeta):
+    """A converter that allows for a user-friendly flag syntax.
+
+    The flags are defined using :pep:`526` type annotations similar
+    to the :mod:`dataclasses` Python module. For more information on
+    how this converter works, check the appropriate
+    :ref:`documentation <ext_commands_flag_converter>`.
+
+    .. container:: operations
+
+        .. describe:: iter(x)
+
+            Returns an iterator of ``(flag_name, flag_value)`` pairs. This allows it
+            to be, for example, constructed as a dict or a list of pairs.
+            Note that aliases are not shown.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    -----------
+    case_insensitive: :class:`bool`
+        A class parameter to toggle case insensitivity of the flag parsing.
+        If ``True`` then flags are parsed in a case insensitive manner.
+        Defaults to ``False``.
+    prefix: :class:`str`
+        The prefix that all flags must be prefixed with. By default
+        there is no prefix.
+    delimiter: :class:`str`
+        The delimiter that separates a flag's argument from the flag's name.
+        By default this is ``:``.
+    """
+
+    @classmethod
+    def get_flags(cls) -> Dict[str, Flag]:
+        """Dict[:class:`str`, :class:`Flag`]: A mapping of flag name to flag object this converter has."""
+        return cls.__commands_flags__.copy()
+
+    @classmethod
+    def _can_be_constructible(cls) -> bool:
+        return all(not flag.required for flag in cls.__commands_flags__.values())
+
+    def __iter__(self) -> Iterator[Tuple[str, Any]]:
+        for flag in self.__class__.__commands_flags__.values():
+            yield (flag.name, getattr(self, flag.attribute))
+
+    @classmethod
+    async def _construct_default(cls: Type[F], ctx: Context) -> F:
+        self: F = cls.__new__(cls)
+        flags = cls.__commands_flags__
+        for flag in flags.values():
+            if callable(flag.default):
+                default = await maybe_coroutine(flag.default, ctx)
+                setattr(self, flag.attribute, default)
+            else:
+                setattr(self, flag.attribute, flag.default)
+        return self
+
+    def __repr__(self) -> str:
+        pairs = ' '.join([f'{flag.attribute}={getattr(self, flag.attribute)!r}' for flag in self.get_flags().values()])
+        return f'<{self.__class__.__name__} {pairs}>'
+
+    @classmethod
+    def parse_flags(cls, argument: str) -> Dict[str, List[str]]:
+        result: Dict[str, List[str]] = {}
+        flags = cls.__commands_flags__
+        aliases = cls.__commands_flag_aliases__
+        last_position = 0
+        last_flag: Optional[Flag] = None
+
+        case_insensitive = cls.__commands_flag_case_insensitive__
+        for match in cls.__commands_flag_regex__.finditer(argument):
+            begin, end = match.span(0)
+            key = match.group('flag')
+            if case_insensitive:
+                key = key.casefold()
+
+            if key in aliases:
+                key = aliases[key]
+
+            flag = flags.get(key)
+            if last_position and last_flag is not None:
+                value = argument[last_position : begin - 1].lstrip()
+                if not value:
+                    raise MissingFlagArgument(last_flag)
+
+                try:
+                    values = result[last_flag.name]
+                except KeyError:
+                    result[last_flag.name] = [value]
+                else:
+                    values.append(value)
+
+            last_position = end
+            last_flag = flag
+
+        # Add the remaining string to the last available flag
+        if last_position and last_flag is not None:
+            value = argument[last_position:].strip()
+            if not value:
+                raise MissingFlagArgument(last_flag)
+
+            try:
+                values = result[last_flag.name]
+            except KeyError:
+                result[last_flag.name] = [value]
+            else:
+                values.append(value)
+
+        # Verification of values will come at a later stage
+        return result
+
+    @classmethod
+    async def convert(cls: Type[F], ctx: Context, argument: str) -> F:
+        """|coro|
+
+        The method that actually converters an argument to the flag mapping.
+
+        Parameters
+        ----------
+        cls: Type[:class:`FlagConverter`]
+            The flag converter class.
+        ctx: :class:`Context`
+            The invocation context.
+        argument: :class:`str`
+            The argument to convert from.
+
+        Raises
+        --------
+        FlagError
+            A flag related parsing error.
+        CommandError
+            A command related error.
+
+        Returns
+        --------
+        :class:`FlagConverter`
+            The flag converter instance with all flags parsed.
+        """
+        arguments = cls.parse_flags(argument)
+        flags = cls.__commands_flags__
+
+        self: F = cls.__new__(cls)
+        for name, flag in flags.items():
+            try:
+                values = arguments[name]
+            except KeyError:
+                if flag.required:
+                    raise MissingRequiredFlag(flag)
+                else:
+                    if callable(flag.default):
+                        default = await maybe_coroutine(flag.default, ctx)
+                        setattr(self, flag.attribute, default)
+                    else:
+                        setattr(self, flag.attribute, flag.default)
+                    continue
+
+            if flag.max_args > 0 and len(values) > flag.max_args:
+                if flag.override:
+                    values = values[-flag.max_args :]
+                else:
+                    raise TooManyFlags(flag, values)
+
+            # Special case:
+            if flag.max_args == 1:
+                value = await convert_flag(ctx, values[0], flag)
+                setattr(self, flag.attribute, value)
+                continue
+
+            # Another special case, tuple parsing.
+            # Tuple parsing is basically converting arguments within the flag
+            # So, given flag: hello 20 as the input and Tuple[str, int] as the type hint
+            # We would receive ('hello', 20) as the resulting value
+            # This uses the same whitespace and quoting rules as regular parameters.
+            values = [await convert_flag(ctx, value, flag) for value in values]
+
+            if flag.cast_to_dict:
+                values = dict(values)  # type: ignore
+
+            setattr(self, flag.attribute, values)
+
+        return self

discord/ext/commands/help.py

@@ -27,11 +27,17 @@ import copy
 import functools
 import inspect
 import re
+
+from typing import Optional, TYPE_CHECKING
+
 import discord.utils
 
 from .core import Group, Command
 from .errors import CommandError
 
+if TYPE_CHECKING:
+    from .context import Context
+
 __all__ = (
     'Paginator',
     'HelpCommand',
@@ -60,6 +66,7 @@ __all__ = (
 # Type <prefix>help command for more info on a command.
 # You can also type <prefix>help category for more info on a category.
 
+
 class Paginator:
     """A class that aids in paginating code blocks for Discord messages.
 
@@ -81,6 +88,7 @@ class Paginator:
         The character string inserted between lines. e.g. a newline character.
             .. versionadded:: 1.7
     """
+
     def __init__(self, prefix='```', suffix='```', max_size=2000, linesep='\n'):
         self.prefix = prefix
         self.suffix = suffix
@@ -92,7 +100,7 @@ class Paginator:
         """Clears the paginator to have no pages."""
         if self.prefix is not None:
             self._current_page = [self.prefix]
-            self._count = len(self.prefix) + self._linesep_len # prefix + newline
+            self._count = len(self.prefix) + self._linesep_len  # prefix + newline
         else:
             self._current_page = []
             self._count = 0
@@ -150,7 +158,7 @@ class Paginator:
 
         if self.prefix is not None:
             self._current_page = [self.prefix]
-            self._count = len(self.prefix) + self._linesep_len # prefix + linesep
+            self._count = len(self.prefix) + self._linesep_len  # prefix + linesep
         else:
             self._current_page = []
             self._count = 0
@@ -171,10 +179,12 @@ class Paginator:
         fmt = '<Paginator prefix: {0.prefix!r} suffix: {0.suffix!r} linesep: {0.linesep!r} max_size: {0.max_size} count: {0._count}>'
         return fmt.format(self)
 
+
 def _not_overriden(f):
     f.__help_command_not_overriden__ = True
     return f
 
+
 class _HelpCommandImpl(Command):
     def __init__(self, inject, *args, **kwargs):
         super().__init__(inject.command_callback, *args, **kwargs)
@@ -212,8 +222,8 @@ class _HelpCommandImpl(Command):
     def clean_params(self):
         result = self.params.copy()
         try:
-            result.popitem(last=False)
-        except Exception:
+            del result[next(iter(result))]
+        except StopIteration:
             raise ValueError('Missing context parameter') from None
         else:
             return result
@@ -250,6 +260,7 @@ class _HelpCommandImpl(Command):
         cog.walk_commands = cog.walk_commands.__wrapped__
         self.cog = None
 
+
 class HelpCommand:
     r"""The base implementation for help command formatting.
 
@@ -272,11 +283,11 @@ class HelpCommand:
         Defaults to ``False``.
     verify_checks: Optional[:class:`bool`]
         Specifies if commands should have their :attr:`.Command.checks` called
-        and verified. If ``True``, always calls :attr:`.Commands.checks`.
-        If ``None``, only calls :attr:`.Commands.checks` in a guild setting.
-        If ``False``, never calls :attr:`.Commands.checks`. Defaults to ``True``.
+        and verified. If ``True``, always calls :attr:`.Command.checks`.
+        If ``None``, only calls :attr:`.Command.checks` in a guild setting.
+        If ``False``, never calls :attr:`.Command.checks`. Defaults to ``True``.
 
-        ..versionchanged:: 1.7
+        .. versionchanged:: 1.7
     command_attrs: :class:`dict`
         A dictionary of options to pass in for the construction of the help command.
         This allows you to change the command behaviour without actually changing
@@ -288,7 +299,7 @@ class HelpCommand:
         '@everyone': '@\u200beveryone',
         '@here': '@\u200bhere',
         r'<@!?[0-9]{17,22}>': '@deleted-user',
-        r'<@&[0-9]{17,22}>': '@deleted-role'
+        r'<@&[0-9]{17,22}>': '@deleted-role',
     }
 
     MENTION_PATTERN = re.compile('|'.join(MENTION_TRANSFORMS.keys()))
@@ -305,10 +316,7 @@ class HelpCommand:
         # The keys can be safely copied as-is since they're 99.99% certain of being
         # string keys
         deepcopy = copy.deepcopy
-        self.__original_kwargs__ = {
-            k: deepcopy(v)
-            for k, v in kwargs.items()
-        }
+        self.__original_kwargs__ = {k: deepcopy(v) for k, v in kwargs.items()}
         self.__original_args__ = deepcopy(args)
         return self
 
@@ -318,7 +326,7 @@ class HelpCommand:
         self.command_attrs = attrs = options.pop('command_attrs', {})
         attrs.setdefault('name', 'help')
         attrs.setdefault('help', 'Shows this message')
-        self.context = None
+        self.context: Context = discord.utils.MISSING
         self._command_impl = _HelpCommandImpl(self, **self.command_attrs)
 
     def copy(self):
@@ -369,25 +377,10 @@ class HelpCommand:
     def get_bot_mapping(self):
         """Retrieves the bot mapping passed to :meth:`send_bot_help`."""
         bot = self.context.bot
-        mapping = {
-            cog: cog.get_commands()
-            for cog in bot.cogs.values()
-        }
+        mapping = {cog: cog.get_commands() for cog in bot.cogs.values()}
         mapping[None] = [c for c in bot.commands if c.cog is None]
         return mapping
 
-    @property
-    def clean_prefix(self):
-        """:class:`str`: The cleaned up invoke prefix. i.e. mentions are ``@name`` instead of ``<@id>``."""
-        user = self.context.guild.me if self.context.guild else self.context.bot.user
-        # this breaks if the prefix mention is not the bot itself but I
-        # consider this to be an *incredibly* strange use case. I'd rather go
-        # for this common use case rather than waste performance for the
-        # odd one.
-        pattern = re.compile(fr"<@!?{user.id}>")
-        display_name = user.display_name.replace('\\', r'\\')
-        return pattern.sub('@' + display_name, self.context.prefix)
-
     @property
     def invoked_with(self):
         """Similar to :attr:`Context.invoked_with` except properly handles
@@ -442,7 +435,7 @@ class HelpCommand:
         else:
             alias = command.name if not parent_sig else parent_sig + ' ' + command.name
 
-        return f'{self.clean_prefix}{alias} {command.signature}'
+        return f'{self.context.clean_prefix}{alias} {command.signature}'
 
     def remove_mentions(self, string):
         """Removes mentions from the string to prevent abuse.
@@ -607,10 +600,7 @@ class HelpCommand:
             The maximum width of the commands.
         """
 
-        as_lengths = (
-            discord.utils._string_width(c.name)
-            for c in commands
-        )
+        as_lengths = (discord.utils._string_width(c.name) for c in commands)
         return max(as_lengths, default=0)
 
     def get_destination(self):
@@ -631,8 +621,7 @@ class HelpCommand:
         """|coro|
 
         Handles the implementation when an error happens in the help command.
-        For example, the result of :meth:`command_not_found` or
-        :meth:`command_has_no_subcommand_found` will be passed here.
+        For example, the result of :meth:`command_not_found` will be passed here.
 
         You can override this method to customise the behaviour.
 
@@ -880,6 +869,7 @@ class HelpCommand:
         else:
             return await self.send_command_help(cmd)
 
+
 class DefaultHelpCommand(HelpCommand):
     """The implementation of the default help command.
 
@@ -934,14 +924,16 @@ class DefaultHelpCommand(HelpCommand):
     def shorten_text(self, text):
         """:class:`str`: Shortens text to fit into the :attr:`width`."""
         if len(text) > self.width:
-            return text[:self.width - 3] + '...'
+            return text[:self.width - 3].rstrip() + '...'
         return text
 
     def get_ending_note(self):
         """:class:`str`: Returns help command's ending note. This is mainly useful to override for i18n purposes."""
         command_name = self.invoked_with
-        return f"Type {self.clean_prefix}{command_name} command for more info on a command.\n" \
-               f"You can also type {self.clean_prefix}{command_name} category for more info on a category."
+        return (
+            f"Type {self.context.clean_prefix}{command_name} command for more info on a command.\n"
+            f"You can also type {self.context.clean_prefix}{command_name} category for more info on a category."
+        )
 
     def add_indented_commands(self, commands, *, heading, max_size=None):
         """Indents a list of commands after the specified heading.
@@ -962,7 +954,7 @@ class DefaultHelpCommand(HelpCommand):
             if the list of commands is greater than 0.
         max_size: Optional[:class:`int`]
             The max size to use for the gap between indents.
-            If unspecified, calls :meth:`get_max_size` on the
+            If unspecified, calls :meth:`~HelpCommand.get_max_size` on the
             commands parameter.
         """
 
@@ -1030,6 +1022,7 @@ class DefaultHelpCommand(HelpCommand):
             self.paginator.add_line(bot.description, empty=True)
 
         no_category = f'\u200b{self.no_category}:'
+
         def get_category(command, *, no_category=no_category):
             cog = command.cog
             return cog.qualified_name + ':' if cog is not None else no_category
@@ -1083,6 +1076,7 @@ class DefaultHelpCommand(HelpCommand):
 
         await self.send_pages()
 
+
 class MinimalHelpCommand(HelpCommand):
     """An implementation of a help command with minimal output.
 
@@ -1149,11 +1143,13 @@ class MinimalHelpCommand(HelpCommand):
             The help command opening note.
         """
         command_name = self.invoked_with
-        return "Use `{0}{1} [command]` for more info on a command.\n" \
-               "You can also use `{0}{1} [category]` for more info on a category.".format(self.clean_prefix, command_name)
+        return (
+            f"Use `{self.context.clean_prefix}{command_name} [command]` for more info on a command.\n"
+            f"You can also use `{self.context.clean_prefix}{command_name} [category]` for more info on a category."
+        )
 
     def get_command_signature(self, command):
-        return f'{self.clean_prefix}{command.qualified_name} {command.signature}'
+        return f'{self.context.clean_prefix}{command.qualified_name} {command.signature}'
 
     def get_ending_note(self):
         """Return the help command's ending note. This is mainly useful to override for i18n purposes.
@@ -1202,7 +1198,7 @@ class MinimalHelpCommand(HelpCommand):
             The command to show information of.
         """
         fmt = '{0}{1} \N{EN DASH} {2}' if command.short_doc else '{0}{1}'
-        self.paginator.add_line(fmt.format(self.clean_prefix, command.qualified_name, command.short_doc))
+        self.paginator.add_line(fmt.format(self.context.clean_prefix, command.qualified_name, command.short_doc))
 
     def add_aliases_formatting(self, aliases):
         """Adds the formatting information on a command's aliases.
@@ -1273,6 +1269,7 @@ class MinimalHelpCommand(HelpCommand):
             self.paginator.add_line(note, empty=True)
 
         no_category = f'\u200b{self.no_category}'
+
         def get_category(command, *, no_category=no_category):
             cog = command.cog
             return cog.qualified_name if cog is not None else no_category

discord/ext/commands/view.py

@@ -189,4 +189,4 @@ class StringView:
 
 
     def __repr__(self):
-        return '<StringView pos: {0.index} prev: {0.previous} end: {0.end} eof: {0.eof}>'.format(self)
+        return f'<StringView pos: {self.index} prev: {self.previous} end: {self.end} eof: {self.eof}>'

discord/ext/tasks/__init__.py

@@ -22,35 +22,92 @@ 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 datetime
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    List,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+)
+
 import aiohttp
 import discord
 import inspect
-import logging
 import sys
 import traceback
 
+from collections.abc import Sequence
 from discord.backoff import ExponentialBackoff
-
-log = logging.getLogger(__name__)
+from discord.utils import MISSING
 
 __all__ = (
     'loop',
 )
 
-class Loop:
+T = TypeVar('T')
+_func = Callable[..., Awaitable[Any]]
+LF = TypeVar('LF', bound=_func)
+FT = TypeVar('FT', bound=_func)
+ET = TypeVar('ET', bound=Callable[[Any, BaseException], Awaitable[Any]])
+
+
+class SleepHandle:
+    __slots__ = ('future', 'loop', 'handle')
+
+    def __init__(self, dt: datetime.datetime, *, loop: asyncio.AbstractEventLoop) -> None:
+        self.loop = loop
+        self.future = future = loop.create_future()
+        relative_delta = discord.utils.compute_timedelta(dt)
+        self.handle = loop.call_later(relative_delta, future.set_result, True)
+
+    def recalculate(self, dt: datetime.datetime) -> None:
+        self.handle.cancel()
+        relative_delta = discord.utils.compute_timedelta(dt)
+        self.handle = self.loop.call_later(relative_delta, self.future.set_result, True)
+
+    def wait(self) -> asyncio.Future[Any]:
+        return self.future
+
+    def done(self) -> bool:
+        return self.future.done()
+
+    def cancel(self) -> None:
+        self.handle.cancel()
+        self.future.cancel()
+
+
+class Loop(Generic[LF]):
     """A background task helper that abstracts the loop and reconnection logic for you.
 
     The main interface to create this is through :func:`loop`.
     """
-    def __init__(self, coro, seconds, hours, minutes, count, reconnect, loop):
-        self.coro = coro
-        self.reconnect = reconnect
-        self.loop = loop
-        self.count = count
+
+    def __init__(
+        self,
+        coro: LF,
+        seconds: float,
+        hours: float,
+        minutes: float,
+        time: Union[datetime.time, Sequence[datetime.time]],
+        count: Optional[int],
+        reconnect: bool,
+        loop: asyncio.AbstractEventLoop,
+    ) -> None:
+        self.coro: LF = coro
+        self.reconnect: bool = reconnect
+        self.loop: asyncio.AbstractEventLoop = loop
+        self.count: Optional[int] = count
         self._current_loop = 0
-        self._task = None
+        self._handle: SleepHandle = MISSING
+        self._task: asyncio.Task[None] = MISSING
         self._injected = None
         self._valid_exception = (
             OSError,
@@ -69,15 +126,15 @@ class Loop:
         if self.count is not None and self.count <= 0:
             raise ValueError('count must be greater than 0 or None.')
 
-        self.change_interval(seconds=seconds, minutes=minutes, hours=hours)
+        self.change_interval(seconds=seconds, minutes=minutes, hours=hours, time=time)
         self._last_iteration_failed = False
-        self._last_iteration = None
+        self._last_iteration: datetime.datetime = MISSING
         self._next_iteration = None
 
         if not inspect.iscoroutinefunction(self.coro):
-            raise TypeError('Expected coroutine function, not {0.__name__!r}.'.format(type(self.coro)))
+            raise TypeError(f'Expected coroutine function, not {type(self.coro).__name__!r}.')
 
-    async def _call_loop_function(self, name, *args, **kwargs):
+    async def _call_loop_function(self, name: str, *args: Any, **kwargs: Any) -> None:
         coro = getattr(self, '_' + name)
         if coro is None:
             return
@@ -87,14 +144,22 @@ class Loop:
         else:
             await coro(*args, **kwargs)
 
-    async def _loop(self, *args, **kwargs):
+    def _try_sleep_until(self, dt: datetime.datetime):
+        self._handle = SleepHandle(dt=dt, loop=self.loop)
+        return self._handle.wait()
+
+    async def _loop(self, *args: Any, **kwargs: Any) -> None:
         backoff = ExponentialBackoff()
         await self._call_loop_function('before_loop')
-        sleep_until = discord.utils.sleep_until
         self._last_iteration_failed = False
-        self._next_iteration = datetime.datetime.now(datetime.timezone.utc)
+        if self._time is not MISSING:
+            # the time index should be prepared every time the internal loop is started
+            self._prepare_time_index()
+            self._next_iteration = self._get_next_sleep_time()
+        else:
+            self._next_iteration = datetime.datetime.now(datetime.timezone.utc)
         try:
-            await asyncio.sleep(0) # allows canceling in before_loop
+            await self._try_sleep_until(self._next_iteration)
             while True:
                 if not self._last_iteration_failed:
                     self._last_iteration = self._next_iteration
@@ -102,22 +167,27 @@ class Loop:
                 try:
                     await self.coro(*args, **kwargs)
                     self._last_iteration_failed = False
-                    now = datetime.datetime.now(datetime.timezone.utc)
-                    if now > self._next_iteration:
-                        self._next_iteration = now
                 except self._valid_exception:
                     self._last_iteration_failed = True
                     if not self.reconnect:
                         raise
                     await asyncio.sleep(backoff.delay())
                 else:
+                    await self._try_sleep_until(self._next_iteration)
+
                     if self._stop_next_iteration:
                         return
+
+                    now = datetime.datetime.now(datetime.timezone.utc)
+                    if now > self._next_iteration:
+                        self._next_iteration = now
+                        if self._time is not MISSING:
+                            self._prepare_time_index(now)
+
                     self._current_loop += 1
                     if self._current_loop == self.count:
                         break
 
-                    await sleep_until(self._next_iteration)
         except asyncio.CancelledError:
             self._is_being_cancelled = True
             raise
@@ -127,17 +197,26 @@ class Loop:
             raise exc
         finally:
             await self._call_loop_function('after_loop')
+            self._handle.cancel()
             self._is_being_cancelled = False
             self._current_loop = 0
             self._stop_next_iteration = False
             self._has_failed = False
 
-    def __get__(self, obj, objtype):
+    def __get__(self, obj: T, objtype: Type[T]) -> Loop[LF]:
         if obj is None:
             return self
 
-        copy = Loop(self.coro, seconds=self.seconds, hours=self.hours, minutes=self.minutes,
-                               count=self.count, reconnect=self.reconnect, loop=self.loop)
+        copy: Loop[LF] = Loop(
+            self.coro,
+            seconds=self._seconds,
+            hours=self._hours,
+            minutes=self._minutes,
+            time=self._time,
+            count=self.count,
+            reconnect=self.reconnect,
+            loop=self.loop,
+        )
         copy._injected = obj
         copy._before_loop = self._before_loop
         copy._after_loop = self._after_loop
@@ -146,23 +225,63 @@ class Loop:
         return copy
 
     @property
-    def current_loop(self):
+    def seconds(self) -> Optional[float]:
+        """Optional[:class:`float`]: Read-only value for the number of seconds
+        between each iteration. ``None`` if an explicit ``time`` value was passed instead.
+
+        .. versionadded:: 2.0
+        """
+        if self._seconds is not MISSING:
+            return self._seconds
+
+    @property
+    def minutes(self) -> Optional[float]:
+        """Optional[:class:`float`]: Read-only value for the number of minutes
+        between each iteration. ``None`` if an explicit ``time`` value was passed instead.
+
+        .. versionadded:: 2.0
+        """
+        if self._minutes is not MISSING:
+            return self._minutes
+
+    @property
+    def hours(self) -> Optional[float]:
+        """Optional[:class:`float`]: Read-only value for the number of hours
+        between each iteration. ``None`` if an explicit ``time`` value was passed instead.
+
+        .. versionadded:: 2.0
+        """
+        if self._hours is not MISSING:
+            return self._hours
+
+    @property
+    def time(self) -> Optional[List[datetime.time]]:
+        """Optional[List[:class:`datetime.time`]]: Read-only list for the exact times this loop runs at.
+        ``None`` if relative times were passed instead.
+
+        .. versionadded:: 2.0
+        """
+        if self._time is not MISSING:
+            return self._time.copy()
+
+    @property
+    def current_loop(self) -> int:
         """:class:`int`: The current iteration of the loop."""
         return self._current_loop
 
     @property
-    def next_iteration(self):
+    def next_iteration(self) -> Optional[datetime.datetime]:
         """Optional[:class:`datetime.datetime`]: When the next iteration of the loop will occur.
 
         .. versionadded:: 1.3
         """
-        if self._task is None:
+        if self._task is MISSING:
             return None
         elif self._task and self._task.done() or self._stop_next_iteration:
             return None
         return self._next_iteration
 
-    async def __call__(self, *args, **kwargs):
+    async def __call__(self, *args: Any, **kwargs: Any) -> Any:
         r"""|coro|
 
         Calls the internal callback that the task holds.
@@ -182,7 +301,7 @@ class Loop:
 
         return await self.coro(*args, **kwargs)
 
-    def start(self, *args, **kwargs):
+    def start(self, *args: Any, **kwargs: Any) -> asyncio.Task[None]:
         r"""Starts the internal task in the event loop.
 
         Parameters
@@ -203,19 +322,19 @@ class Loop:
             The task that has been created.
         """
 
-        if self._task is not None and not self._task.done():
+        if self._task is not MISSING and not self._task.done():
             raise RuntimeError('Task is already launched and is not completed.')
 
         if self._injected is not None:
             args = (self._injected, *args)
 
-        if self.loop is None:
+        if self.loop is MISSING:
             self.loop = asyncio.get_event_loop()
 
         self._task = self.loop.create_task(self._loop(*args, **kwargs))
         return self._task
 
-    def stop(self):
+    def stop(self) -> None:
         r"""Gracefully stops the task from running.
 
         Unlike :meth:`cancel`\, this allows the task to finish its
@@ -233,18 +352,18 @@ class Loop:
 
         .. versionadded:: 1.2
         """
-        if self._task and not self._task.done():
+        if self._task is not MISSING and not self._task.done():
             self._stop_next_iteration = True
 
-    def _can_be_cancelled(self):
-        return not self._is_being_cancelled and self._task and not self._task.done()
+    def _can_be_cancelled(self) -> bool:
+        return bool(not self._is_being_cancelled and self._task and not self._task.done())
 
-    def cancel(self):
+    def cancel(self) -> None:
         """Cancels the internal task, if it is running."""
         if self._can_be_cancelled():
             self._task.cancel()
 
-    def restart(self, *args, **kwargs):
+    def restart(self, *args: Any, **kwargs: Any) -> None:
         r"""A convenience method to restart the internal task.
 
         .. note::
@@ -255,12 +374,12 @@ class Loop:
         Parameters
         ------------
         \*args
-            The arguments to to use.
+            The arguments to use.
         \*\*kwargs
             The keyword arguments to use.
         """
 
-        def restart_when_over(fut, *, args=args, kwargs=kwargs):
+        def restart_when_over(fut: Any, *, args: Any = args, kwargs: Any = kwargs) -> None:
             self._task.remove_done_callback(restart_when_over)
             self.start(*args, **kwargs)
 
@@ -268,7 +387,7 @@ class Loop:
             self._task.add_done_callback(restart_when_over)
             self._task.cancel()
 
-    def add_exception_type(self, *exceptions):
+    def add_exception_type(self, *exceptions: Type[BaseException]) -> None:
         r"""Adds exception types to be handled during the reconnect logic.
 
         By default the exception types handled are those handled by
@@ -297,7 +416,7 @@ class Loop:
 
         self._valid_exception = (*self._valid_exception, *exceptions)
 
-    def clear_exception_types(self):
+    def clear_exception_types(self) -> None:
         """Removes all exception types that are handled.
 
         .. note::
@@ -306,7 +425,7 @@ class Loop:
         """
         self._valid_exception = tuple()
 
-    def remove_exception_type(self, *exceptions):
+    def remove_exception_type(self, *exceptions: Type[BaseException]) -> bool:
         r"""Removes exception types from being handled during the reconnect logic.
 
         Parameters
@@ -323,34 +442,34 @@ class Loop:
         self._valid_exception = tuple(x for x in self._valid_exception if x not in exceptions)
         return len(self._valid_exception) == old_length - len(exceptions)
 
-    def get_task(self):
+    def get_task(self) -> Optional[asyncio.Task[None]]:
         """Optional[:class:`asyncio.Task`]: Fetches the internal task or ``None`` if there isn't one running."""
-        return self._task
+        return self._task if self._task is not MISSING else None
 
-    def is_being_cancelled(self):
+    def is_being_cancelled(self) -> bool:
         """Whether the task is being cancelled."""
         return self._is_being_cancelled
 
-    def failed(self):
+    def failed(self) -> bool:
         """:class:`bool`: Whether the internal task has failed.
 
         .. versionadded:: 1.2
         """
         return self._has_failed
 
-    def is_running(self):
+    def is_running(self) -> bool:
         """:class:`bool`: Check if the task is currently running.
 
         .. versionadded:: 1.4
         """
-        return not bool(self._task.done()) if self._task else False
+        return not bool(self._task.done()) if self._task is not MISSING else False
 
-    async def _error(self, *args):
-        exception = args[-1]
+    async def _error(self, *args: Any) -> None:
+        exception: Exception = args[-1]
         print(f'Unhandled exception in internal background task {self.coro.__name__!r}.', file=sys.stderr)
         traceback.print_exception(type(exception), exception, exception.__traceback__, file=sys.stderr)
 
-    def before_loop(self, coro):
+    def before_loop(self, coro: FT) -> FT:
         """A decorator that registers a coroutine to be called before the loop starts running.
 
         This is useful if you want to wait for some bot state before the loop starts,
@@ -370,12 +489,12 @@ class Loop:
         """
 
         if not inspect.iscoroutinefunction(coro):
-            raise TypeError('Expected coroutine function, received {0.__name__!r}.'.format(type(coro)))
+            raise TypeError(f'Expected coroutine function, received {coro.__class__.__name__!r}.')
 
         self._before_loop = coro
         return coro
 
-    def after_loop(self, coro):
+    def after_loop(self, coro: FT) -> FT:
         """A decorator that register a coroutine to be called after the loop finished running.
 
         The coroutine must take no arguments (except ``self`` in a class context).
@@ -398,12 +517,12 @@ class Loop:
         """
 
         if not inspect.iscoroutinefunction(coro):
-            raise TypeError('Expected coroutine function, received {0.__name__!r}.'.format(type(coro)))
+            raise TypeError(f'Expected coroutine function, received {coro.__class__.__name__!r}.')
 
         self._after_loop = coro
         return coro
 
-    def error(self, coro):
+    def error(self, coro: ET) -> ET:
         """A decorator that registers a coroutine to be called if the task encounters an unhandled exception.
 
         The coroutine must take only one argument the exception raised (except ``self`` in a class context).
@@ -424,22 +543,90 @@ class Loop:
             The function was not a coroutine.
         """
         if not inspect.iscoroutinefunction(coro):
-            raise TypeError('Expected coroutine function, received {0.__name__!r}.'.format(type(coro)))
+            raise TypeError(f'Expected coroutine function, received {coro.__class__.__name__!r}.')
 
-        self._error = coro
+        self._error = coro  # type: ignore
         return coro
 
-    def _get_next_sleep_time(self):
-        return self._last_iteration + datetime.timedelta(seconds=self._sleep)
+    def _get_next_sleep_time(self) -> datetime.datetime:
+        if self._sleep is not MISSING:
+            return self._last_iteration + datetime.timedelta(seconds=self._sleep)
 
-    def change_interval(self, *, seconds=0, minutes=0, hours=0):
+        if self._time_index >= len(self._time):
+            self._time_index = 0
+            if self._current_loop == 0:
+                # if we're at the last index on the first iteration, we need to sleep until tomorrow
+                return datetime.datetime.combine(
+                    datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=1), self._time[0]
+                )
+
+        next_time = self._time[self._time_index]
+
+        if self._current_loop == 0:
+            self._time_index += 1
+            return datetime.datetime.combine(datetime.datetime.now(datetime.timezone.utc), next_time)
+
+        next_date = self._last_iteration
+        if self._time_index == 0:
+            # we can assume that the earliest time should be scheduled for "tomorrow"
+            next_date += datetime.timedelta(days=1)
+
+        self._time_index += 1
+        return datetime.datetime.combine(next_date, next_time)
+
+    def _prepare_time_index(self, now: datetime.datetime = MISSING) -> None:
+        # now kwarg should be a datetime.datetime representing the time "now"
+        # to calculate the next time index from
+
+        # pre-condition: self._time is set
+        time_now = (
+            now if now is not MISSING else datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0)
+        ).timetz()
+        for idx, time in enumerate(self._time):
+            if time >= time_now:
+                self._time_index = idx
+                break
+        else:
+            self._time_index = 0
+
+    def _get_time_parameter(
+        self,
+        time: Union[datetime.time, Sequence[datetime.time]],
+        *,
+        dt: Type[datetime.time] = datetime.time,
+        utc: datetime.timezone = datetime.timezone.utc,
+    ) -> List[datetime.time]:
+        if isinstance(time, dt):
+            inner = time if time.tzinfo is not None else time.replace(tzinfo=utc)
+            return [inner]
+        if not isinstance(time, Sequence):
+            raise TypeError(
+                f'Expected datetime.time or a sequence of datetime.time for ``time``, received {type(time)!r} instead.'
+            )
+        if not time:
+            raise ValueError('time parameter must not be an empty sequence.')
+
+        ret: List[datetime.time] = []
+        for index, t in enumerate(time):
+            if not isinstance(t, dt):
+                raise TypeError(
+                    f'Expected a sequence of {dt!r} for ``time``, received {type(t).__name__!r} at index {index} instead.'
+                )
+            ret.append(t if t.tzinfo is not None else t.replace(tzinfo=utc))
+
+        ret = sorted(set(ret))  # de-dupe and sort times
+        return ret
+
+    def change_interval(
+        self,
+        *,
+        seconds: float = 0,
+        minutes: float = 0,
+        hours: float = 0,
+        time: Union[datetime.time, Sequence[datetime.time]] = MISSING,
+    ) -> None:
         """Changes the interval for the sleep time.
 
-        .. note::
-
-            This only applies on the next loop iteration. If it is desirable for the change of interval
-            to be applied right away, cancel the task with :meth:`cancel`.
-
         .. versionadded:: 1.2
 
         Parameters
@@ -450,23 +637,66 @@ class Loop:
             The number of minutes between every iteration.
         hours: :class:`float`
             The number of hours between every iteration.
+        time: Union[:class:`datetime.time`, Sequence[:class:`datetime.time`]]
+            The exact times to run this loop at. Either a non-empty list or a single
+            value of :class:`datetime.time` should be passed.
+            This cannot be used in conjunction with the relative time parameters.
+
+            .. versionadded:: 2.0
+
+            .. note::
+
+                Duplicate times will be ignored, and only run once.
 
         Raises
         -------
         ValueError
             An invalid value was given.
+        TypeError
+            An invalid value for the ``time`` parameter was passed, or the
+            ``time`` parameter was passed in conjunction with relative time parameters.
         """
 
-        sleep = seconds + (minutes * 60.0) + (hours * 3600.0)
-        if sleep < 0:
-            raise ValueError('Total number of seconds cannot be less than zero.')
+        if time is MISSING:
+            seconds = seconds or 0
+            minutes = minutes or 0
+            hours = hours or 0
+            sleep = seconds + (minutes * 60.0) + (hours * 3600.0)
+            if sleep < 0:
+                raise ValueError('Total number of seconds cannot be less than zero.')
 
-        self._sleep = sleep
-        self.seconds = seconds
-        self.hours = hours
-        self.minutes = minutes
+            self._sleep = sleep
+            self._seconds = float(seconds)
+            self._hours = float(hours)
+            self._minutes = float(minutes)
+            self._time: List[datetime.time] = MISSING
+        else:
+            if any((seconds, minutes, hours)):
+                raise TypeError('Cannot mix explicit time with relative time')
+            self._time = self._get_time_parameter(time)
+            self._sleep = self._seconds = self._minutes = self._hours = MISSING
 
-def loop(*, seconds=0, minutes=0, hours=0, count=None, reconnect=True, loop=None):
+        if self.is_running():
+            if self._time is not MISSING:
+                # prepare the next time index starting from after the last iteration
+                self._prepare_time_index(now=self._last_iteration)
+
+            self._next_iteration = self._get_next_sleep_time()
+            if not self._handle.done():
+                # the loop is sleeping, recalculate based on new interval
+                self._handle.recalculate(self._next_iteration)
+
+
+def loop(
+    *,
+    seconds: float = MISSING,
+    minutes: float = MISSING,
+    hours: float = MISSING,
+    time: Union[datetime.time, Sequence[datetime.time]] = MISSING,
+    count: Optional[int] = None,
+    reconnect: bool = True,
+    loop: asyncio.AbstractEventLoop = MISSING,
+) -> Callable[[LF], Loop[LF]]:
     """A decorator that schedules a task in the background for you with
     optional reconnect logic. The decorator returns a :class:`Loop`.
 
@@ -478,6 +708,19 @@ def loop(*, seconds=0, minutes=0, hours=0, count=None, reconnect=True, loop=None
         The number of minutes between every iteration.
     hours: :class:`float`
         The number of hours between every iteration.
+    time: Union[:class:`datetime.time`, Sequence[:class:`datetime.time`]]
+        The exact times to run this loop at. Either a non-empty list or a single
+        value of :class:`datetime.time` should be passed. Timezones are supported.
+        If no timezone is given for the times, it is assumed to represent UTC time.
+
+        This cannot be used in conjunction with the relative time parameters.
+
+        .. note::
+
+            Duplicate times will be ignored, and only run once.
+
+        .. versionadded:: 2.0
+
     count: Optional[:class:`int`]
         The number of loops to do, ``None`` if it should be an
         infinite loop.
@@ -494,16 +737,20 @@ def loop(*, seconds=0, minutes=0, hours=0, count=None, reconnect=True, loop=None
     ValueError
         An invalid value was given.
     TypeError
-        The function was not a coroutine.
+        The function was not a coroutine, an invalid value for the ``time`` parameter was passed,
+        or ``time`` parameter was passed in conjunction with relative time parameters.
     """
-    def decorator(func):
-        kwargs = {
-            'seconds': seconds,
-            'minutes': minutes,
-            'hours': hours,
-            'count': count,
-            'reconnect': reconnect,
-            'loop': loop
-        }
-        return Loop(func, **kwargs)
+
+    def decorator(func: LF) -> Loop[LF]:
+        return Loop[LF](
+            func,
+            seconds=seconds,
+            minutes=minutes,
+            hours=hours,
+            count=count,
+            time=time,
+            reconnect=reconnect,
+            loop=loop,
+        )
+
     return decorator

discord/file.py

@@ -22,13 +22,17 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
-import os.path
+from __future__ import annotations
+from typing import Optional, TYPE_CHECKING, Union
+
+import os
 import io
 
 __all__ = (
     'File',
 )
 
+
 class File:
     r"""A parameter object used for :meth:`abc.Messageable.send`
     for sending file objects.
@@ -40,7 +44,7 @@ class File:
 
     Attributes
     -----------
-    fp: Union[:class:`str`, :class:`io.BufferedIOBase`]
+    fp: Union[:class:`os.PathLike`, :class:`io.BufferedIOBase`]
         A file-like object opened in binary mode and read mode
         or a filename representing a file in the hard drive to
         open.
@@ -62,9 +66,18 @@ class File:
 
     __slots__ = ('fp', 'filename', 'spoiler', '_original_pos', '_owner', '_closer')
 
-    def __init__(self, fp, filename=None, *, spoiler=False):
-        self.fp = fp
+    if TYPE_CHECKING:
+        fp: io.BufferedIOBase
+        filename: Optional[str]
+        spoiler: bool
 
+    def __init__(
+        self,
+        fp: Union[str, bytes, os.PathLike, io.BufferedIOBase],
+        filename: Optional[str] = None,
+        *,
+        spoiler: bool = False,
+    ):
         if isinstance(fp, io.IOBase):
             if not (fp.seekable() and fp.readable()):
                 raise ValueError(f'File buffer {fp!r} must be seekable and readable')
@@ -96,7 +109,7 @@ class File:
 
         self.spoiler = spoiler or (self.filename is not None and self.filename.startswith('SPOILER_'))
 
-    def reset(self, *, seek=True):
+    def reset(self, *, seek: Union[int, bool] = True) -> None:
         # The `seek` parameter is needed because
         # the retry-loop is iterated over multiple times
         # starting from 0, as an implementation quirk
@@ -108,7 +121,7 @@ class File:
         if seek:
             self.fp.seek(self._original_pos)
 
-    def close(self):
+    def close(self) -> None:
         self.fp.close = self._closer
         if self._owner:
             self._closer()

discord/flags.py

@@ -34,12 +34,14 @@ __all__ = (
     'PublicUserFlags',
     'Intents',
     'MemberCacheFlags',
+    'ApplicationFlags',
 )
 
 FV = TypeVar('FV', bound='flag_value')
 BF = TypeVar('BF', bound='BaseFlags')
 
-class flag_value(Generic[BF]):
+
+class flag_value:
     def __init__(self, func: Callable[[Any], int]):
         self.flag = func(None)
         self.__doc__ = func.__doc__
@@ -63,16 +65,20 @@ class flag_value(Generic[BF]):
     def __repr__(self):
         return f'<flag_value flag={self.flag!r}>'
 
+
 class alias_flag_value(flag_value):
     pass
 
+
 def fill_with_flags(*, inverted: bool = False):
     def decorator(cls: Type[BF]):
+        # fmt: off
         cls.VALID_FLAGS = {
             name: value.flag
             for name, value in cls.__dict__.items()
             if isinstance(value, flag_value)
         }
+        # fmt: on
 
         if inverted:
             max_bits = max(cls.VALID_FLAGS.values()).bit_length()
@@ -81,8 +87,10 @@ def fill_with_flags(*, inverted: bool = False):
             cls.DEFAULT_VALUE = 0
 
         return cls
+
     return decorator
 
+
 # n.b. flags must inherit from this and use the decorator above
 class BaseFlags:
     VALID_FLAGS: ClassVar[Dict[str, int]]
@@ -136,6 +144,7 @@ class BaseFlags:
         else:
             raise TypeError(f'Value to set for {self.__class__.__name__} must be a bool.')
 
+
 @fill_with_flags(inverted=True)
 class SystemChannelFlags(BaseFlags):
     r"""Wraps up a Discord system channel flag value.
@@ -196,9 +205,17 @@ class SystemChannelFlags(BaseFlags):
 
     @flag_value
     def premium_subscriptions(self):
-        """:class:`bool`: Returns ``True`` if the system channel is used for Nitro boosting notifications."""
+        """:class:`bool`: Returns ``True`` if the system channel is used for "Nitro boosting" notifications."""
         return 2
 
+    @flag_value
+    def guild_reminder_notifications(self):
+        """:class:`bool`: Returns ``True`` if the system channel is used for server setup helpful tips notifications.
+
+        .. versionadded:: 2.0
+        """
+        return 4
+
 
 @fill_with_flags()
 class MessageFlags(BaseFlags):
@@ -262,6 +279,23 @@ class MessageFlags(BaseFlags):
         """
         return 16
 
+    @flag_value
+    def has_thread(self):
+        """:class:`bool`: Returns ``True`` if the source message is associated with a thread.
+
+        .. versionadded:: 2.0
+        """
+        return 32
+
+    @flag_value
+    def ephemeral(self):
+        """:class:`bool`: Returns ``True`` if the source message is ephemeral.
+
+        .. versionadded:: 2.0
+        """
+        return 64
+
+
 @fill_with_flags()
 class PublicUserFlags(BaseFlags):
     r"""Wraps up the Discord User Public flags.
@@ -368,6 +402,14 @@ class PublicUserFlags(BaseFlags):
         """
         return UserFlags.verified_bot_developer.value
 
+    @flag_value
+    def discord_certified_moderator(self):
+        """:class:`bool`: Returns ``True`` if the user is a Discord Certified Moderator.
+
+        .. versionadded:: 2.0
+        """
+        return UserFlags.discord_certified_moderator.value
+
     def all(self) -> List[UserFlags]:
         """List[:class:`UserFlags`]: Returns all public flags the user has."""
         return [public_flag for public_flag in UserFlags if self._has_flag(public_flag.value)]
@@ -438,16 +480,6 @@ class Intents(BaseFlags):
         self.value = self.DEFAULT_VALUE
         return self
 
-    @classmethod
-    def default(cls: Type[Intents]) -> Intents:
-        """A factory method that creates a :class:`Intents` with everything enabled
-        except :attr:`presences` and :attr:`members`.
-        """
-        self = cls.all()
-        self.presences = False
-        self.members = False
-        return self
-
     @flag_value
     def guilds(self):
         """:class:`bool`: Whether guild related events are enabled.
@@ -482,12 +514,13 @@ class Intents(BaseFlags):
 
         - :func:`on_member_join`
         - :func:`on_member_remove`
-        - :func:`on_member_update` (nickname, roles)
+        - :func:`on_member_update`
         - :func:`on_user_update`
 
         This also corresponds to the following attributes and classes in terms of cache:
 
         - :meth:`Client.get_all_members`
+        - :meth:`Client.get_user`
         - :meth:`Guild.chunk`
         - :meth:`Guild.fetch_members`
         - :meth:`Guild.get_member`
@@ -496,7 +529,7 @@ class Intents(BaseFlags):
         - :attr:`Member.nick`
         - :attr:`Member.premium_since`
         - :attr:`User.name`
-        - :attr:`User.avatar` (:attr:`User.avatar_url` and :meth:`User.avatar_url_as`)
+        - :attr:`User.avatar`
         - :attr:`User.discriminator`
 
         For more information go to the :ref:`member intent documentation <need_members_intent>`.
@@ -523,18 +556,34 @@ class Intents(BaseFlags):
 
     @flag_value
     def emojis(self):
-        """:class:`bool`: Whether guild emoji related events are enabled.
+        """:class:`bool`: Alias of :attr:`.emojis_and_stickers`.
+
+        .. versionchanged:: 2.0
+            Changed to an alias.
+        """
+        return 1 << 3
+
+    @alias_flag_value
+    def emojis_and_stickers(self):
+        """:class:`bool`: Whether guild emoji and sticker related events are enabled.
+
+        .. versionadded:: 2.0
 
         This corresponds to the following events:
 
         - :func:`on_guild_emojis_update`
+        - :func:`on_guild_stickers_update`
 
         This also corresponds to the following attributes and classes in terms of cache:
 
         - :class:`Emoji`
+        - :class:`GuildSticker`
         - :meth:`Client.get_emoji`
+        - :meth:`Client.get_sticker`
         - :meth:`Client.emojis`
+        - :meth:`Client.stickers`
         - :attr:`Guild.emojis`
+        - :attr:`Guild.stickers`
         """
         return 1 << 3
 
@@ -545,6 +594,9 @@ class Intents(BaseFlags):
         This corresponds to the following events:
 
         - :func:`on_guild_integrations_update`
+        - :func:`on_integration_create`
+        - :func:`on_integration_update`
+        - :func:`on_raw_integration_delete`
 
         This does not correspond to any attributes or classes in the library in terms of cache.
         """
@@ -588,6 +640,10 @@ class Intents(BaseFlags):
         - :attr:`VoiceChannel.members`
         - :attr:`VoiceChannel.voice_states`
         - :attr:`Member.voice`
+
+        .. note::
+
+            This intent is required to connect to voice.
         """
         return 1 << 7
 
@@ -597,7 +653,7 @@ class Intents(BaseFlags):
 
         This corresponds to the following events:
 
-        - :func:`on_member_update` (activities, status)
+        - :func:`on_presence_update`
 
         This also corresponds to the following attributes and classes in terms of cache:
 
@@ -627,7 +683,6 @@ class Intents(BaseFlags):
         - :func:`on_message_delete` (both guilds and DMs)
         - :func:`on_raw_message_delete` (both guilds and DMs)
         - :func:`on_raw_message_edit` (both guilds and DMs)
-        - :func:`on_private_channel_create`
 
         This also corresponds to the following attributes and classes in terms of cache:
 
@@ -682,7 +737,6 @@ class Intents(BaseFlags):
         - :func:`on_message_delete` (only for DMs)
         - :func:`on_raw_message_delete` (only for DMs)
         - :func:`on_raw_message_edit` (only for DMs)
-        - :func:`on_private_channel_create`
 
         This also corresponds to the following attributes and classes in terms of cache:
 
@@ -802,6 +856,7 @@ class Intents(BaseFlags):
         """
         return 1 << 14
 
+
 @fill_with_flags()
 class MemberCacheFlags(BaseFlags):
     """Controls the library's cache policy when it comes to members.
@@ -875,17 +930,6 @@ class MemberCacheFlags(BaseFlags):
     def _empty(self):
         return self.value == self.DEFAULT_VALUE
 
-    @flag_value
-    def online(self):
-        """:class:`bool`: Whether to cache members with a status.
-
-        For example, members that are part of the initial ``GUILD_CREATE``
-        or become online at a later point. This requires :attr:`Intents.presences`.
-
-        Members that go offline are no longer cached.
-        """
-        return 1
-
     @flag_value
     def voice(self):
         """:class:`bool`: Whether to cache members that are in voice.
@@ -894,7 +938,7 @@ class MemberCacheFlags(BaseFlags):
 
         Members that leave voice are no longer cached.
         """
-        return 2
+        return 1
 
     @flag_value
     def joined(self):
@@ -905,7 +949,7 @@ class MemberCacheFlags(BaseFlags):
 
         Members that leave the guild are no longer cached.
         """
-        return 4
+        return 2
 
     @classmethod
     def from_intents(cls: Type[MemberCacheFlags], intents: Intents) -> MemberCacheFlags:
@@ -926,35 +970,89 @@ class MemberCacheFlags(BaseFlags):
         self = cls.none()
         if intents.members:
             self.joined = True
-        if intents.presences:
-            self.online = True
         if intents.voice_states:
             self.voice = True
 
-        if not self.joined and self.online and self.voice:
-            self.voice = False
-
         return self
 
     def _verify_intents(self, intents: Intents):
-        if self.online and not intents.presences:
-            raise ValueError('MemberCacheFlags.online requires Intents.presences enabled')
-
         if self.voice and not intents.voice_states:
             raise ValueError('MemberCacheFlags.voice requires Intents.voice_states')
 
         if self.joined and not intents.members:
             raise ValueError('MemberCacheFlags.joined requires Intents.members')
 
-        if not self.joined and self.voice and self.online:
-            msg = 'Setting both MemberCacheFlags.voice and MemberCacheFlags.online requires MemberCacheFlags.joined ' \
-                  'to properly evict members from the cache.'
-            raise ValueError(msg)
-
     @property
     def _voice_only(self):
-        return self.value == 2
-
-    @property
-    def _online_only(self):
         return self.value == 1
+
+
+@fill_with_flags()
+class ApplicationFlags(BaseFlags):
+    r"""Wraps up the Discord Application flags.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two ApplicationFlags are equal.
+        .. describe:: x != y
+
+            Checks if two ApplicationFlags are not equal.
+        .. describe:: hash(x)
+
+            Return the flag's hash.
+        .. describe:: iter(x)
+
+            Returns an iterator of ``(name, value)`` pairs. This allows it
+            to be, for example, constructed as a dict or a list of pairs.
+            Note that aliases are not shown.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    value: :class:`int`
+        The raw value. You should query flags via the properties
+        rather than using this raw value.
+    """
+
+    @flag_value
+    def gateway_presence(self):
+        """:class:`bool`: Returns ``True`` if the application is verified and is allowed to
+        receive presence information over the gateway.
+        """
+        return 1 << 12
+
+    @flag_value
+    def gateway_presence_limited(self):
+        """:class:`bool`: Returns ``True`` if the application is allowed to receive limited
+        presence information over the gateway.
+        """
+        return 1 << 13
+
+    @flag_value
+    def gateway_guild_members(self):
+        """:class:`bool`: Returns ``True`` if the application is verified and is allowed to
+        receive guild members information over the gateway.
+        """
+        return 1 << 14
+
+    @flag_value
+    def gateway_guild_members_limited(self):
+        """:class:`bool`: Returns ``True`` if the application is allowed to receive limited
+        guild members information over the gateway.
+        """
+        return 1 << 15
+
+    @flag_value
+    def verification_pending_guild_limit(self):
+        """:class:`bool`: Returns ``True`` if the application is currently pending verification
+        and has hit the guild limit.
+        """
+        return 1 << 16
+
+    @flag_value
+    def embedded(self):
+        """:class:`bool`: Returns ``True`` if the application is embedded within the Discord client."""
+        return 1 << 17

discord/gateway.py

@@ -25,7 +25,6 @@ DEALINGS IN THE SOFTWARE.
 import asyncio
 from collections import namedtuple, deque
 import concurrent.futures
-import json
 import logging
 import struct
 import sys
@@ -41,7 +40,7 @@ from .activity import BaseActivity
 from .enums import SpeakingState
 from .errors import ConnectionClosed, InvalidArgument
 
-log = logging.getLogger(__name__)
+_log = logging.getLogger(__name__)
 
 __all__ = (
     'DiscordWebSocket',
@@ -102,7 +101,7 @@ class GatewayRatelimiter:
         async with self.lock:
             delta = self.get_delay()
             if delta:
-                log.warning('WebSocket in shard ID %s is ratelimited, waiting %.2f seconds', self.shard_id, delta)
+                _log.warning('WebSocket in shard ID %s is ratelimited, waiting %.2f seconds', self.shard_id, delta)
                 await asyncio.sleep(delta)
 
 
@@ -130,20 +129,20 @@ class KeepAliveHandler(threading.Thread):
     def run(self):
         while not self._stop_ev.wait(self.interval):
             if self._last_recv + self.heartbeat_timeout < time.perf_counter():
-                log.warning("Shard ID %s has stopped responding to the gateway. Closing and restarting.", self.shard_id)
+                _log.warning("Shard ID %s has stopped responding to the gateway. Closing and restarting.", self.shard_id)
                 coro = self.ws.close(4000)
                 f = asyncio.run_coroutine_threadsafe(coro, loop=self.ws.loop)
 
                 try:
                     f.result()
                 except Exception:
-                    log.exception('An error occurred while stopping the gateway. Ignoring.')
+                    _log.exception('An error occurred while stopping the gateway. Ignoring.')
                 finally:
                     self.stop()
                     return
 
             data = self.get_payload()
-            log.debug(self.msg, self.shard_id, data['d'])
+            _log.debug(self.msg, self.shard_id, data['d'])
             coro = self.ws.send_heartbeat(data)
             f = asyncio.run_coroutine_threadsafe(coro, loop=self.ws.loop)
             try:
@@ -162,7 +161,7 @@ class KeepAliveHandler(threading.Thread):
                         else:
                             stack = ''.join(traceback.format_stack(frame))
                             msg = f'{self.block_msg}\nLoop thread traceback (most recent call last):\n{stack}'
-                        log.warning(msg, self.shard_id, total)
+                        _log.warning(msg, self.shard_id, total)
 
             except Exception:
                 self.stop()
@@ -186,7 +185,7 @@ class KeepAliveHandler(threading.Thread):
         self._last_ack = ack_time
         self.latency = ack_time - self._last_send
         if self.latency > 10:
-            log.warning(self.behind_msg, self.shard_id, self.latency)
+            _log.warning(self.behind_msg, self.shard_id, self.latency)
 
 class VoiceKeepAliveHandler(KeepAliveHandler):
     def __init__(self, *args, **kwargs):
@@ -294,6 +293,12 @@ class DiscordWebSocket:
     def is_ratelimited(self):
         return self._rate_limiter.is_ratelimited()
 
+    def debug_log_receive(self, data, /):
+        self._dispatch('socket_raw_receive', data)
+
+    def log_receive(self, _, /):
+        pass
+
     @classmethod
     async def from_client(cls, client, *, initial=False, gateway=None, shard_id=None, session=None, sequence=None, resume=False):
         """Creates a main websocket for Discord from a :class:`Client`.
@@ -319,9 +324,13 @@ class DiscordWebSocket:
         ws.sequence = sequence
         ws._max_heartbeat_timeout = client._connection.heartbeat_timeout
 
+        if client._enable_debug_events:
+            ws.send = ws.debug_send
+            ws.log_receive = ws.debug_log_receive
+
         client._connection._update_references(ws)
 
-        log.debug('Created websocket connected to %s', gateway)
+        _log.debug('Created websocket connected to %s', gateway)
 
         # poll event for OP Hello
         await ws.poll_event()
@@ -373,7 +382,6 @@ class DiscordWebSocket:
                 },
                 'compress': True,
                 'large_threshold': 250,
-                'guild_subscriptions': self._connection.guild_subscriptions,
                 'v': 3
             }
         }
@@ -395,7 +403,7 @@ class DiscordWebSocket:
 
         await self.call_hooks('before_identify', self.shard_id, initial=self._initial_identify)
         await self.send_as_json(payload)
-        log.info('Shard ID %s has sent the IDENTIFY payload.', self.shard_id)
+        _log.info('Shard ID %s has sent the IDENTIFY payload.', self.shard_id)
 
     async def resume(self):
         """Sends the RESUME packet."""
@@ -409,11 +417,9 @@ class DiscordWebSocket:
         }
 
         await self.send_as_json(payload)
-        log.info('Shard ID %s has sent the RESUME payload.', self.shard_id)
-
-    async def received_message(self, msg):
-        self._dispatch('socket_raw_receive', msg)
+        _log.info('Shard ID %s has sent the RESUME payload.', self.shard_id)
 
+    async def received_message(self, msg, /):
         if type(msg) is bytes:
             self._buffer.extend(msg)
 
@@ -422,10 +428,14 @@ class DiscordWebSocket:
             msg = self._zlib.decompress(self._buffer)
             msg = msg.decode('utf-8')
             self._buffer = bytearray()
-        msg = json.loads(msg)
 
-        log.debug('For Shard ID %s: WebSocket Event: %s', self.shard_id, msg)
-        self._dispatch('socket_response', msg)
+        self.log_receive(msg)
+        msg = utils._from_json(msg)
+
+        _log.debug('For Shard ID %s: WebSocket Event: %s', self.shard_id, msg)
+        event = msg.get('t')
+        if event:
+            self._dispatch('socket_event_type', event)
 
         op = msg.get('op')
         data = msg.get('d')
@@ -441,7 +451,7 @@ class DiscordWebSocket:
                 # "reconnect" can only be handled by the Client
                 # so we terminate our connection and raise an
                 # internal exception signalling to reconnect.
-                log.debug('Received RECONNECT opcode.')
+                _log.debug('Received RECONNECT opcode.')
                 await self.close()
                 raise ReconnectWebSocket(self.shard_id)
 
@@ -471,35 +481,33 @@ class DiscordWebSocket:
 
                 self.sequence = None
                 self.session_id = None
-                log.info('Shard ID %s session has been invalidated.', self.shard_id)
+                _log.info('Shard ID %s session has been invalidated.', self.shard_id)
                 await self.close(code=1000)
                 raise ReconnectWebSocket(self.shard_id, resume=False)
 
-            log.warning('Unknown OP code %s.', op)
+            _log.warning('Unknown OP code %s.', op)
             return
 
-        event = msg.get('t')
-
         if event == 'READY':
             self._trace = trace = data.get('_trace', [])
             self.sequence = msg['s']
             self.session_id = data['session_id']
             # pass back shard ID to ready handler
             data['__shard_id__'] = self.shard_id
-            log.info('Shard ID %s has connected to Gateway: %s (Session ID: %s).',
+            _log.info('Shard ID %s has connected to Gateway: %s (Session ID: %s).',
                      self.shard_id, ', '.join(trace), self.session_id)
 
         elif event == 'RESUMED':
             self._trace = trace = data.get('_trace', [])
             # pass back the shard ID to the resumed handler
             data['__shard_id__'] = self.shard_id
-            log.info('Shard ID %s has successfully RESUMED session %s under trace %s.',
+            _log.info('Shard ID %s has successfully RESUMED session %s under trace %s.',
                      self.shard_id, self.session_id, ', '.join(trace))
 
         try:
             func = self._discord_parsers[event]
         except KeyError:
-            log.debug('Unknown event %s.', event)
+            _log.debug('Unknown event %s.', event)
         else:
             func(data)
 
@@ -553,10 +561,10 @@ class DiscordWebSocket:
             elif msg.type is aiohttp.WSMsgType.BINARY:
                 await self.received_message(msg.data)
             elif msg.type is aiohttp.WSMsgType.ERROR:
-                log.debug('Received %s', msg)
+                _log.debug('Received %s', msg)
                 raise msg.data
             elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.CLOSING, aiohttp.WSMsgType.CLOSE):
-                log.debug('Received %s', msg)
+                _log.debug('Received %s', msg)
                 raise WebSocketClosure
         except (asyncio.TimeoutError, WebSocketClosure) as e:
             # Ensure the keep alive handler is closed
@@ -565,25 +573,29 @@ class DiscordWebSocket:
                 self._keep_alive = None
 
             if isinstance(e, asyncio.TimeoutError):
-                log.info('Timed out receiving packet. Attempting a reconnect.')
+                _log.info('Timed out receiving packet. Attempting a reconnect.')
                 raise ReconnectWebSocket(self.shard_id) from None
 
             code = self._close_code or self.socket.close_code
             if self._can_handle_close():
-                log.info('Websocket closed with %s, attempting a reconnect.', code)
+                _log.info('Websocket closed with %s, attempting a reconnect.', code)
                 raise ReconnectWebSocket(self.shard_id) from None
             else:
-                log.info('Websocket closed with %s, cannot reconnect.', code)
+                _log.info('Websocket closed with %s, cannot reconnect.', code)
                 raise ConnectionClosed(self.socket, shard_id=self.shard_id, code=code) from None
 
-    async def send(self, data):
+    async def debug_send(self, data, /):
         await self._rate_limiter.block()
         self._dispatch('socket_raw_send', data)
         await self.socket.send_str(data)
 
+    async def send(self, data, /):
+        await self._rate_limiter.block()
+        await self.socket.send_str(data)
+
     async def send_as_json(self, data):
         try:
-            await self.send(utils.to_json(data))
+            await self.send(utils._to_json(data))
         except RuntimeError as exc:
             if not self._can_handle_close():
                 raise ConnectionClosed(self.socket, shard_id=self.shard_id) from exc
@@ -591,16 +603,18 @@ class DiscordWebSocket:
     async def send_heartbeat(self, data):
         # This bypasses the rate limit handling code since it has a higher priority
         try:
-            await self.socket.send_str(utils.to_json(data))
+            await self.socket.send_str(utils._to_json(data))
         except RuntimeError as exc:
             if not self._can_handle_close():
                 raise ConnectionClosed(self.socket, shard_id=self.shard_id) from exc
 
-    async def change_presence(self, *, activity=None, status=None, afk=False, since=0.0):
+    async def change_presence(self, *, activity=None, status=None, since=0.0):
         if activity is not None:
             if not isinstance(activity, BaseActivity):
                 raise InvalidArgument('activity must derive from BaseActivity.')
-            activity = activity.to_dict()
+            activity = [activity.to_dict()]
+        else:
+            activity = []
 
         if status == 'idle':
             since = int(time.time() * 1000)
@@ -608,15 +622,15 @@ class DiscordWebSocket:
         payload = {
             'op': self.PRESENCE,
             'd': {
-                'game': activity,
-                'afk': afk,
+                'activities': activity,
+                'afk': False,
                 'since': since,
                 'status': status
             }
         }
 
-        sent = utils.to_json(payload)
-        log.debug('Sending "%s" to change status', sent)
+        sent = utils._to_json(payload)
+        _log.debug('Sending "%s" to change status', sent)
         await self.send(sent)
 
     async def request_chunks(self, guild_id, query=None, *, limit, user_ids=None, presences=False, nonce=None):
@@ -652,7 +666,7 @@ class DiscordWebSocket:
             }
         }
 
-        log.debug('Updating our voice state to %s.', payload)
+        _log.debug('Updating our voice state to %s.', payload)
         await self.send_as_json(payload)
 
     async def close(self, code=4000):
@@ -707,16 +721,21 @@ class DiscordVoiceWebSocket:
     CLIENT_CONNECT      = 12
     CLIENT_DISCONNECT   = 13
 
-    def __init__(self, socket, loop):
+    def __init__(self, socket, loop, *, hook=None):
         self.ws = socket
         self.loop = loop
         self._keep_alive = None
         self._close_code = None
         self.secret_key = None
+        if hook:
+            self._hook = hook
+
+    async def _hook(self, *args):
+        pass
 
     async def send_as_json(self, data):
-        log.debug('Sending voice websocket frame: %s.', data)
-        await self.ws.send_str(utils.to_json(data))
+        _log.debug('Sending voice websocket frame: %s.', data)
+        await self.ws.send_str(utils._to_json(data))
 
     send_heartbeat = send_as_json
 
@@ -746,12 +765,12 @@ class DiscordVoiceWebSocket:
         await self.send_as_json(payload)
 
     @classmethod
-    async def from_client(cls, client, *, resume=False):
+    async def from_client(cls, client, *, resume=False, hook=None):
         """Creates a voice websocket for the :class:`VoiceClient`."""
         gateway = 'wss://' + client.endpoint + '/?v=4'
         http = client._state.http
         socket = await http.ws_connect(gateway, compress=15)
-        ws = cls(socket, loop=client.loop)
+        ws = cls(socket, loop=client.loop, hook=hook)
         ws.gateway = gateway
         ws._connection = client
         ws._max_heartbeat_timeout = 60.0
@@ -801,7 +820,7 @@ class DiscordVoiceWebSocket:
         await self.send_as_json(payload)
 
     async def received_message(self, msg):
-        log.debug('Voice websocket frame received: %s', msg)
+        _log.debug('Voice websocket frame received: %s', msg)
         op = msg['op']
         data = msg.get('d')
 
@@ -810,7 +829,7 @@ class DiscordVoiceWebSocket:
         elif op == self.HEARTBEAT_ACK:
             self._keep_alive.ack()
         elif op == self.RESUMED:
-            log.info('Voice RESUME succeeded.')
+            _log.info('Voice RESUME succeeded.')
         elif op == self.SESSION_DESCRIPTION:
             self._connection.mode = data['mode']
             await self.load_secret_key(data)
@@ -819,6 +838,8 @@ class DiscordVoiceWebSocket:
             self._keep_alive = VoiceKeepAliveHandler(ws=self, interval=min(interval, 5.0))
             self._keep_alive.start()
 
+        await self._hook(self, msg)
+
     async def initial_connection(self, data):
         state = self._connection
         state.ssrc = data['ssrc']
@@ -831,7 +852,7 @@ class DiscordVoiceWebSocket:
         struct.pack_into('>I', packet, 4, state.ssrc)
         state.socket.sendto(packet, (state.endpoint_ip, state.voice_port))
         recv = await self.loop.sock_recv(state.socket, 70)
-        log.debug('received packet in initial_connection: %s', recv)
+        _log.debug('received packet in initial_connection: %s', recv)
 
         # the ip is ascii starting at the 4th byte and ending at the first null
         ip_start = 4
@@ -839,15 +860,15 @@ class DiscordVoiceWebSocket:
         state.ip = recv[ip_start:ip_end].decode('ascii')
 
         state.port = struct.unpack_from('>H', recv, len(recv) - 2)[0]
-        log.debug('detected ip: %s port: %s', state.ip, state.port)
+        _log.debug('detected ip: %s port: %s', state.ip, state.port)
 
         # there *should* always be at least one supported mode (xsalsa20_poly1305)
         modes = [mode for mode in data['modes'] if mode in self._connection.supported_modes]
-        log.debug('received supported encryption modes: %s', ", ".join(modes))
+        _log.debug('received supported encryption modes: %s', ", ".join(modes))
 
         mode = modes[0]
         await self.select_protocol(state.ip, state.port, mode)
-        log.info('selected the voice protocol for use (%s)', mode)
+        _log.info('selected the voice protocol for use (%s)', mode)
 
     @property
     def latency(self):
@@ -865,7 +886,7 @@ class DiscordVoiceWebSocket:
         return sum(heartbeat.recent_ack_latencies) / len(heartbeat.recent_ack_latencies)
 
     async def load_secret_key(self, data):
-        log.info('received secret key for voice connection')
+        _log.info('received secret key for voice connection')
         self.secret_key = self._connection.secret_key = data.get('secret_key')
         await self.speak()
         await self.speak(False)
@@ -874,12 +895,12 @@ class DiscordVoiceWebSocket:
         # This exception is handled up the chain
         msg = await asyncio.wait_for(self.ws.receive(), timeout=30.0)
         if msg.type is aiohttp.WSMsgType.TEXT:
-            await self.received_message(json.loads(msg.data))
+            await self.received_message(utils._from_json(msg.data))
         elif msg.type is aiohttp.WSMsgType.ERROR:
-            log.debug('Received %s', msg)
+            _log.debug('Received %s', msg)
             raise ConnectionClosed(self.ws, shard_id=None) from msg.data
         elif msg.type in (aiohttp.WSMsgType.CLOSED, aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSING):
-            log.debug('Received %s', msg)
+            _log.debug('Received %s', msg)
             raise ConnectionClosed(self.ws, shard_id=None, code=self._close_code)
 
     async def close(self, code=1000):

discord/integrations.py

@@ -22,17 +22,36 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 import datetime
-from .utils import _get_as_snowflake, get, parse_time
+from typing import Any, Dict, Optional, TYPE_CHECKING, overload, Type, Tuple
+from .utils import _get_as_snowflake, parse_time, MISSING
 from .user import User
 from .errors import InvalidArgument
 from .enums import try_enum, ExpireBehaviour
 
 __all__ = (
     'IntegrationAccount',
+    'IntegrationApplication',
     'Integration',
+    'StreamIntegration',
+    'BotIntegration',
 )
 
+if TYPE_CHECKING:
+    from .types.integration import (
+        IntegrationAccount as IntegrationAccountPayload,
+        Integration as IntegrationPayload,
+        StreamIntegration as StreamIntegrationPayload,
+        BotIntegration as BotIntegrationPayload,
+        IntegrationType,
+        IntegrationApplication as IntegrationApplicationPayload,
+    )
+    from .guild import Guild
+    from .role import Role
+
+
 class IntegrationAccount:
     """Represents an integration account.
 
@@ -40,7 +59,7 @@ class IntegrationAccount:
 
     Attributes
     -----------
-    id: :class:`int`
+    id: :class:`str`
         The account ID.
     name: :class:`str`
         The account name.
@@ -48,12 +67,13 @@ class IntegrationAccount:
 
     __slots__ = ('id', 'name')
 
-    def __init__(self, **kwargs):
-        self.id = kwargs.pop('id')
-        self.name = kwargs.pop('name')
+    def __init__(self, data: IntegrationAccountPayload) -> None:
+        self.id: str = data['id']
+        self.name: str = data['name']
+
+    def __repr__(self) -> str:
+        return f'<IntegrationAccount id={self.id} name={self.name!r}>'
 
-    def __repr__(self):
-        return '<IntegrationAccount id={0.id} name={0.name!r}>'.format(self)
 
 class Integration:
     """Represents a guild integration.
@@ -62,6 +82,83 @@ class Integration:
 
     Attributes
     -----------
+    id: :class:`int`
+        The integration ID.
+    name: :class:`str`
+        The integration name.
+    guild: :class:`Guild`
+        The guild of the integration.
+    type: :class:`str`
+        The integration type (i.e. Twitch).
+    enabled: :class:`bool`
+        Whether the integration is currently enabled.
+    account: :class:`IntegrationAccount`
+        The account linked to this integration.
+    user: :class:`User`
+        The user that added this integration.
+    """
+
+    __slots__ = (
+        'guild',
+        'id',
+        '_state',
+        'type',
+        'name',
+        'account',
+        'user',
+        'enabled',
+    )
+
+    def __init__(self, *, data: IntegrationPayload, guild: Guild) -> None:
+        self.guild = guild
+        self._state = guild._state
+        self._from_data(data)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} id={self.id} name={self.name!r}>"
+
+    def _from_data(self, data: IntegrationPayload) -> None:
+        self.id: int = int(data['id'])
+        self.type: IntegrationType = data['type']
+        self.name: str = data['name']
+        self.account: IntegrationAccount = IntegrationAccount(data['account'])
+
+        user = data.get('user')
+        self.user = User(state=self._state, data=user) if user else None
+        self.enabled: bool = data['enabled']
+
+    async def delete(self, *, reason: Optional[str] = None) -> None:
+        """|coro|
+
+        Deletes the integration.
+
+        You must have the :attr:`~Permissions.manage_guild` permission to
+        do this.
+
+        Parameters
+        -----------
+        reason: :class:`str`
+            The reason the integration was deleted. Shows up on the audit log.
+
+            .. versionadded:: 2.0
+
+        Raises
+        -------
+        Forbidden
+            You do not have permission to delete the integration.
+        HTTPException
+            Deleting the integration failed.
+        """
+        await self._state.http.delete_integration(self.guild.id, self.id, reason=reason)
+
+
+class StreamIntegration(Integration):
+    """Represents a stream integration for Twitch or YouTube.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ----------
     id: :class:`int`
         The integration ID.
     name: :class:`str`
@@ -74,8 +171,6 @@ class Integration:
         Whether the integration is currently enabled.
     syncing: :class:`bool`
         Where the integration is currently syncing.
-    role: :class:`Role`
-        The role which the integration uses for subscribers.
     enable_emoticons: Optional[:class:`bool`]
         Whether emoticons should be synced for this integration (currently twitch only).
     expire_behaviour: :class:`ExpireBehaviour`
@@ -90,37 +185,45 @@ class Integration:
         An aware UTC datetime representing when the integration was last synced.
     """
 
-    __slots__ = ('id', '_state', 'guild', 'name', 'enabled', 'type',
-                 'syncing', 'role', 'expire_behaviour', 'expire_behavior',
-                 'expire_grace_period', 'synced_at', 'user', 'account',
-                 'enable_emoticons', '_role_id')
+    __slots__ = (
+        'revoked',
+        'expire_behaviour',
+        'expire_grace_period',
+        'synced_at',
+        '_role_id',
+        'syncing',
+        'enable_emoticons',
+        'subscriber_count',
+    )
 
-    def __init__(self, *, data, guild):
-        self.guild = guild
-        self._state = guild._state
-        self._from_data(data)
+    def _from_data(self, data: StreamIntegrationPayload) -> None:
+        super()._from_data(data)
+        self.revoked: bool = data['revoked']
+        self.expire_behaviour: ExpireBehaviour = try_enum(ExpireBehaviour, data['expire_behavior'])
+        self.expire_grace_period: int = data['expire_grace_period']
+        self.synced_at: datetime.datetime = parse_time(data['synced_at'])
+        self._role_id: Optional[int] = _get_as_snowflake(data, 'role_id')
+        self.syncing: bool = data['syncing']
+        self.enable_emoticons: bool = data['enable_emoticons']
+        self.subscriber_count: int = data['subscriber_count']
 
-    def __repr__(self):
-        return '<Integration id={0.id} name={0.name!r} type={0.type!r}>'.format(self)
+    @property
+    def expire_behavior(self) -> ExpireBehaviour:
+        """:class:`ExpireBehaviour`: An alias for :attr:`expire_behaviour`."""
+        return self.expire_behaviour
 
-    def _from_data(self, integ):
-        self.id = _get_as_snowflake(integ, 'id')
-        self.name = integ['name']
-        self.type = integ['type']
-        self.enabled = integ['enabled']
-        self.syncing = integ['syncing']
-        self._role_id = _get_as_snowflake(integ, 'role_id')
-        self.role = get(self.guild.roles, id=self._role_id)
-        self.enable_emoticons = integ.get('enable_emoticons')
-        self.expire_behaviour = try_enum(ExpireBehaviour, integ['expire_behavior'])
-        self.expire_behavior = self.expire_behaviour
-        self.expire_grace_period = integ['expire_grace_period']
-        self.synced_at = parse_time(integ['synced_at'])
+    @property
+    def role(self) -> Optional[Role]:
+        """Optional[:class:`Role`] The role which the integration uses for subscribers."""
+        return self.guild.get_role(self._role_id)  # type: ignore
 
-        self.user = User(state=self._state, data=integ['user'])
-        self.account = IntegrationAccount(**integ['account'])
-
-    async def edit(self, **fields):
+    async def edit(
+        self,
+        *,
+        expire_behaviour: ExpireBehaviour = MISSING,
+        expire_grace_period: int = MISSING,
+        enable_emoticons: bool = MISSING,
+    ) -> None:
         """|coro|
 
         Edits the integration.
@@ -146,34 +249,24 @@ class Integration:
         InvalidArgument
             ``expire_behaviour`` did not receive a :class:`ExpireBehaviour`.
         """
-        try:
-            expire_behaviour = fields['expire_behaviour']
-        except KeyError:
-            expire_behaviour = fields.get('expire_behavior', self.expire_behaviour)
+        payload: Dict[str, Any] = {}
+        if expire_behaviour is not MISSING:
+            if not isinstance(expire_behaviour, ExpireBehaviour):
+                raise InvalidArgument('expire_behaviour field must be of type ExpireBehaviour')
 
-        if not isinstance(expire_behaviour, ExpireBehaviour):
-            raise InvalidArgument('expire_behaviour field must be of type ExpireBehaviour')
+            payload['expire_behavior'] = expire_behaviour.value
 
-        expire_grace_period = fields.get('expire_grace_period', self.expire_grace_period)
+        if expire_grace_period is not MISSING:
+            payload['expire_grace_period'] = expire_grace_period
 
-        payload = {
-            'expire_behavior': expire_behaviour.value,
-            'expire_grace_period': expire_grace_period,
-        }
-
-        enable_emoticons = fields.get('enable_emoticons')
-
-        if enable_emoticons is not None:
+        if enable_emoticons is not MISSING:
             payload['enable_emoticons'] = enable_emoticons
 
+        # This endpoint is undocumented.
+        # Unsure if it returns the data or not as a result
         await self._state.http.edit_integration(self.guild.id, self.id, **payload)
 
-        self.expire_behaviour = expire_behaviour
-        self.expire_behavior = self.expire_behaviour
-        self.expire_grace_period = expire_grace_period
-        self.enable_emoticons = enable_emoticons
-
-    async def sync(self):
+    async def sync(self) -> None:
         """|coro|
 
         Syncs the integration.
@@ -191,19 +284,83 @@ class Integration:
         await self._state.http.sync_integration(self.guild.id, self.id)
         self.synced_at = datetime.datetime.now(datetime.timezone.utc)
 
-    async def delete(self):
-        """|coro|
 
-        Deletes the integration.
+class IntegrationApplication:
+    """Represents an application for a bot integration.
 
-        You must have the :attr:`~Permissions.manage_guild` permission to
-        do this.
+    .. versionadded:: 2.0
 
-        Raises
-        -------
-        Forbidden
-            You do not have permission to delete the integration.
-        HTTPException
-            Deleting the integration failed.
-        """
-        await self._state.http.delete_integration(self.guild.id, self.id)
+    Attributes
+    ----------
+    id: :class:`int`
+        The ID for this application.
+    name: :class:`str`
+        The application's name.
+    icon: Optional[:class:`str`]
+        The application's icon hash.
+    description: :class:`str`
+        The application's description. Can be an empty string.
+    summary: :class:`str`
+        The summary of the application. Can be an empty string.
+    user: Optional[:class:`User`]
+        The bot user on this application.
+    """
+
+    __slots__ = (
+        'id',
+        'name',
+        'icon',
+        'description',
+        'summary',
+        'user',
+    )
+
+    def __init__(self, *, data: IntegrationApplicationPayload, state):
+        self.id: int = int(data['id'])
+        self.name: str = data['name']
+        self.icon: Optional[str] = data['icon']
+        self.description: str = data['description']
+        self.summary: str = data['summary']
+        user = data.get('bot')
+        self.user: Optional[User] = User(state=state, data=user) if user else None
+
+
+class BotIntegration(Integration):
+    """Represents a bot integration on discord.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ----------
+    id: :class:`int`
+        The integration ID.
+    name: :class:`str`
+        The integration name.
+    guild: :class:`Guild`
+        The guild of the integration.
+    type: :class:`str`
+        The integration type (i.e. Twitch).
+    enabled: :class:`bool`
+        Whether the integration is currently enabled.
+    user: :class:`User`
+        The user that added this integration.
+    account: :class:`IntegrationAccount`
+        The integration account information.
+    application: :class:`IntegrationApplication`
+        The application tied to this integration.
+    """
+
+    __slots__ = ('application',)
+
+    def _from_data(self, data: BotIntegrationPayload) -> None:
+        super()._from_data(data)
+        self.application = IntegrationApplication(data=data['application'], state=self._state)
+
+
+def _integration_factory(value: str) -> Tuple[Type[Integration], str]:
+    if value == 'discord':
+        return BotIntegration, value
+    elif value in ('twitch', 'youtube'):
+        return StreamIntegration, value
+    else:
+        return Integration, value

discord/interactions.py

@@ -25,20 +25,54 @@ DEALINGS IN THE SOFTWARE.
 """
 
 from __future__ import annotations
+from typing import Any, Dict, List, Optional, TYPE_CHECKING, Tuple, Union
+import asyncio
 
 from . import utils
-from .enums import try_enum, InteractionType
+from .enums import try_enum, InteractionType, InteractionResponseType
+from .errors import InteractionResponded, HTTPException, ClientException
+from .channel import PartialMessageable, ChannelType
+
+from .user import User
+from .member import Member
+from .message import Message, Attachment
+from .object import Object
+from .permissions import Permissions
+from .webhook.async_ import async_context, Webhook, handle_message_parameters
 
 __all__ = (
     'Interaction',
+    'InteractionMessage',
+    'InteractionResponse',
 )
 
+if TYPE_CHECKING:
+    from .types.interactions import (
+        Interaction as InteractionPayload,
+        InteractionData,
+    )
+    from .guild import Guild
+    from .state import ConnectionState
+    from .file import File
+    from .mentions import AllowedMentions
+    from aiohttp import ClientSession
+    from .embeds import Embed
+    from .ui.view import View
+    from .channel import VoiceChannel, StageChannel, TextChannel, CategoryChannel, StoreChannel, PartialMessageable
+    from .threads import Thread
+
+    InteractionChannel = Union[
+        VoiceChannel, StageChannel, TextChannel, CategoryChannel, StoreChannel, Thread, PartialMessageable
+    ]
+
+MISSING: Any = utils.MISSING
+
+
 class Interaction:
     """Represents a Discord interaction.
 
     An interaction happens when a user does an action that needs to
-    be notified. Current examples are slash commands but future examples
-    include forms and buttons.
+    be notified. Current examples are slash commands and components.
 
     .. versionadded:: 2.0
 
@@ -56,49 +90,678 @@ class Interaction:
         The application ID that the interaction was for.
     user: Optional[Union[:class:`User`, :class:`Member`]]
         The user or member that sent the interaction.
+    message: Optional[:class:`Message`]
+        The message that sent this interaction.
     token: :class:`str`
         The token to continue the interaction. These are valid
         for 15 minutes.
+    data: :class:`dict`
+        The raw interaction data.
     """
-    __slots__ = (
+
+    __slots__: Tuple[str, ...] = (
         'id',
         'type',
         'guild_id',
         'channel_id',
         'data',
         'application_id',
+        'message',
         'user',
         'token',
         'version',
+        '_permissions',
         '_state',
+        '_session',
+        '_original_message',
+        '_cs_response',
+        '_cs_followup',
+        '_cs_channel',
     )
 
-    def __init__(self, *, data, state=None):
-        self._state = state
+    def __init__(self, *, data: InteractionPayload, state: ConnectionState):
+        self._state: ConnectionState = state
+        self._session: ClientSession = state.http._HTTPClient__session
+        self._original_message: Optional[InteractionMessage] = None
         self._from_data(data)
 
-    def _from_data(self, data):
-        self.id = int(data['id'])
-        self.type = try_enum(InteractionType, data['type'])
-        self.data = data.get('data')
-        self.token = data['token']
-        self.version = data['version']
-        self.channel_id = utils._get_as_snowflake(data, 'channel_id')
-        self.guild_id = utils._get_as_snowflake(data, 'guild_id')
-        self.application_id = utils._get_as_snowflake(data, 'application_id')
+    def _from_data(self, data: InteractionPayload):
+        self.id: int = int(data['id'])
+        self.type: InteractionType = try_enum(InteractionType, data['type'])
+        self.data: Optional[InteractionData] = data.get('data')
+        self.token: str = data['token']
+        self.version: int = data['version']
+        self.channel_id: Optional[int] = utils._get_as_snowflake(data, 'channel_id')
+        self.guild_id: Optional[int] = utils._get_as_snowflake(data, 'guild_id')
+        self.application_id: int = int(data['application_id'])
+
+        self.message: Optional[Message]
+        try:
+            self.message = Message(state=self._state, channel=self.channel, data=data['message'])  # type: ignore
+        except KeyError:
+            self.message = None
+
+        self.user: Optional[Union[User, Member]] = None
+        self._permissions: int = 0
+
+        # TODO: there's a potential data loss here
+        if self.guild_id:
+            guild = self.guild or Object(id=self.guild_id)
+            try:
+                member = data['member']  # type: ignore
+            except KeyError:
+                pass
+            else:
+                self.user = Member(state=self._state, guild=guild, data=member)  # type: ignore
+                self._permissions = int(member.get('permissions', 0))
+        else:
+            try:
+                self.user = User(state=self._state, data=data['user'])
+            except KeyError:
+                pass
 
     @property
-    def guild(self):
+    def guild(self) -> Optional[Guild]:
         """Optional[:class:`Guild`]: The guild the interaction was sent from."""
-        return self._state and self._state.get_guild(self.guild_id)
+        return self._state and self._state._get_guild(self.guild_id)
 
-    @property
-    def channel(self):
-        """Optional[:class:`abc.GuildChannel`]: The channel the interaction was sent from.
+    @utils.cached_slot_property('_cs_channel')
+    def channel(self) -> Optional[InteractionChannel]:
+        """Optional[Union[:class:`abc.GuildChannel`, :class:`PartialMessageable`, :class:`Thread`]]: The channel the interaction was sent from.
 
         Note that due to a Discord limitation, DM channels are not resolved since there is
-        no data to complete them.
+        no data to complete them. These are :class:`PartialMessageable` instead.
         """
         guild = self.guild
-        return guild and guild.get_channel(self.channel_id)
+        channel = guild and guild._resolve_channel(self.channel_id)
+        if channel is None:
+            if self.channel_id is not None:
+                type = ChannelType.text if self.guild_id is not None else ChannelType.private
+                return PartialMessageable(state=self._state, id=self.channel_id, type=type)
+            return None
+        return channel
 
+    @property
+    def permissions(self) -> Permissions:
+        """:class:`Permissions`: The resolved permissions of the member in the channel, including overwrites.
+
+        In a non-guild context where this doesn't apply, an empty permissions object is returned.
+        """
+        return Permissions(self._permissions)
+
+    @utils.cached_slot_property('_cs_response')
+    def response(self) -> InteractionResponse:
+        """:class:`InteractionResponse`: Returns an object responsible for handling responding to the interaction.
+
+        A response can only be done once. If secondary messages need to be sent, consider using :attr:`followup`
+        instead.
+        """
+        return InteractionResponse(self)
+
+    @utils.cached_slot_property('_cs_followup')
+    def followup(self) -> Webhook:
+        """:class:`Webhook`: Returns the follow up webhook for follow up interactions."""
+        payload = {
+            'id': self.application_id,
+            'type': 3,
+            'token': self.token,
+        }
+        return Webhook.from_state(data=payload, state=self._state)
+
+    async def original_message(self) -> InteractionMessage:
+        """|coro|
+
+        Fetches the original interaction response message associated with the interaction.
+
+        If the interaction response was :meth:`InteractionResponse.send_message` then this would
+        return the message that was sent using that response. Otherwise, this would return
+        the message that triggered the interaction.
+
+        Repeated calls to this will return a cached value.
+
+        Raises
+        -------
+        HTTPException
+            Fetching the original response message failed.
+        ClientException
+            The channel for the message could not be resolved.
+
+        Returns
+        --------
+        InteractionMessage
+            The original interaction response message.
+        """
+
+        if self._original_message is not None:
+            return self._original_message
+
+        # TODO: fix later to not raise?
+        channel = self.channel
+        if channel is None:
+            raise ClientException('Channel for message could not be resolved')
+
+        adapter = async_context.get()
+        data = await adapter.get_original_interaction_response(
+            application_id=self.application_id,
+            token=self.token,
+            session=self._session,
+        )
+        state = _InteractionMessageState(self, self._state)
+        message = InteractionMessage(state=state, channel=channel, data=data)  # type: ignore
+        self._original_message = message
+        return message
+
+    async def edit_original_message(
+        self,
+        *,
+        content: Optional[str] = MISSING,
+        embeds: List[Embed] = MISSING,
+        embed: Optional[Embed] = MISSING,
+        file: File = MISSING,
+        files: List[File] = MISSING,
+        view: Optional[View] = MISSING,
+        allowed_mentions: Optional[AllowedMentions] = None,
+    ) -> InteractionMessage:
+        """|coro|
+
+        Edits the original interaction response message.
+
+        This is a lower level interface to :meth:`InteractionMessage.edit` in case
+        you do not want to fetch the message and save an HTTP request.
+
+        This method is also the only way to edit the original message if
+        the message sent was ephemeral.
+
+        Parameters
+        ------------
+        content: Optional[:class:`str`]
+            The content to edit the message with or ``None`` to clear it.
+        embeds: List[:class:`Embed`]
+            A list of embeds to edit the message with.
+        embed: Optional[:class:`Embed`]
+            The embed to edit the message with. ``None`` suppresses the embeds.
+            This should not be mixed with the ``embeds`` parameter.
+        file: :class:`File`
+            The file to upload. This cannot be mixed with ``files`` parameter.
+        files: List[:class:`File`]
+            A list of files to send with the content. This cannot be mixed with the
+            ``file`` parameter.
+        allowed_mentions: :class:`AllowedMentions`
+            Controls the mentions being processed in this message.
+            See :meth:`.abc.Messageable.send` for more information.
+        view: Optional[:class:`~discord.ui.View`]
+            The updated view to update this message with. If ``None`` is passed then
+            the view is removed.
+
+        Raises
+        -------
+        HTTPException
+            Editing the message failed.
+        Forbidden
+            Edited a message that is not yours.
+        TypeError
+            You specified both ``embed`` and ``embeds`` or ``file`` and ``files``
+        ValueError
+            The length of ``embeds`` was invalid.
+
+        Returns
+        --------
+        :class:`InteractionMessage`
+            The newly edited message.
+        """
+
+        previous_mentions: Optional[AllowedMentions] = self._state.allowed_mentions
+        params = handle_message_parameters(
+            content=content,
+            file=file,
+            files=files,
+            embed=embed,
+            embeds=embeds,
+            view=view,
+            allowed_mentions=allowed_mentions,
+            previous_allowed_mentions=previous_mentions,
+        )
+        adapter = async_context.get()
+        data = await adapter.edit_original_interaction_response(
+            self.application_id,
+            self.token,
+            session=self._session,
+            payload=params.payload,
+            multipart=params.multipart,
+            files=params.files,
+        )
+
+        # The message channel types should always match
+        message = InteractionMessage(state=self._state, channel=self.channel, data=data)  # type: ignore
+        if view and not view.is_finished():
+            self._state.store_view(view, message.id)
+        return message
+
+    async def delete_original_message(self) -> None:
+        """|coro|
+
+        Deletes the original interaction response message.
+
+        This is a lower level interface to :meth:`InteractionMessage.delete` in case
+        you do not want to fetch the message and save an HTTP request.
+
+        Raises
+        -------
+        HTTPException
+            Deleting the message failed.
+        Forbidden
+            Deleted a message that is not yours.
+        """
+        adapter = async_context.get()
+        await adapter.delete_original_interaction_response(
+            self.application_id,
+            self.token,
+            session=self._session,
+        )
+
+
+class InteractionResponse:
+    """Represents a Discord interaction response.
+
+    This type can be accessed through :attr:`Interaction.response`.
+
+    .. versionadded:: 2.0
+    """
+
+    __slots__: Tuple[str, ...] = (
+        '_responded',
+        '_parent',
+    )
+
+    def __init__(self, parent: Interaction):
+        self._parent: Interaction = parent
+        self._responded: bool = False
+
+    def is_done(self) -> bool:
+        """:class:`bool`: Indicates whether an interaction response has been done before.
+
+        An interaction can only be responded to once.
+        """
+        return self._responded
+
+    async def defer(self, *, ephemeral: bool = False) -> None:
+        """|coro|
+
+        Defers the interaction response.
+
+        This is typically used when the interaction is acknowledged
+        and a secondary action will be done later.
+
+        Parameters
+        -----------
+        ephemeral: :class:`bool`
+            Indicates whether the deferred message will eventually be ephemeral.
+            This only applies for interactions of type :attr:`InteractionType.application_command`.
+
+        Raises
+        -------
+        HTTPException
+            Deferring the interaction failed.
+        InteractionResponded
+            This interaction has already been responded to before.
+        """
+        if self._responded:
+            raise InteractionResponded(self._parent)
+
+        defer_type: int = 0
+        data: Optional[Dict[str, Any]] = None
+        parent = self._parent
+        if parent.type is InteractionType.component:
+            defer_type = InteractionResponseType.deferred_message_update.value
+        elif parent.type is InteractionType.application_command:
+            defer_type = InteractionResponseType.deferred_channel_message.value
+            if ephemeral:
+                data = {'flags': 64}
+
+        if defer_type:
+            adapter = async_context.get()
+            await adapter.create_interaction_response(
+                parent.id, parent.token, session=parent._session, type=defer_type, data=data
+            )
+            self._responded = True
+
+    async def pong(self) -> None:
+        """|coro|
+
+        Pongs the ping interaction.
+
+        This should rarely be used.
+
+        Raises
+        -------
+        HTTPException
+            Ponging the interaction failed.
+        InteractionResponded
+            This interaction has already been responded to before.
+        """
+        if self._responded:
+            raise InteractionResponded(self._parent)
+
+        parent = self._parent
+        if parent.type is InteractionType.ping:
+            adapter = async_context.get()
+            await adapter.create_interaction_response(
+                parent.id, parent.token, session=parent._session, type=InteractionResponseType.pong.value
+            )
+            self._responded = True
+
+    async def send_message(
+        self,
+        content: Optional[Any] = None,
+        *,
+        embed: Embed = MISSING,
+        embeds: List[Embed] = MISSING,
+        view: View = MISSING,
+        tts: bool = False,
+        ephemeral: bool = False,
+    ) -> None:
+        """|coro|
+
+        Responds to this interaction by sending a message.
+
+        Parameters
+        -----------
+        content: Optional[:class:`str`]
+            The content of the message to send.
+        embeds: List[:class:`Embed`]
+            A list of embeds to send with the content. Maximum of 10. This cannot
+            be mixed with the ``embed`` parameter.
+        embed: :class:`Embed`
+            The rich embed for the content to send. This cannot be mixed with
+            ``embeds`` parameter.
+        tts: :class:`bool`
+            Indicates if the message should be sent using text-to-speech.
+        view: :class:`discord.ui.View`
+            The view to send with the message.
+        ephemeral: :class:`bool`
+            Indicates if the message should only be visible to the user who started the interaction.
+            If a view is sent with an ephemeral message and it has no timeout set then the timeout
+            is set to 15 minutes.
+
+        Raises
+        -------
+        HTTPException
+            Sending the message failed.
+        TypeError
+            You specified both ``embed`` and ``embeds``.
+        ValueError
+            The length of ``embeds`` was invalid.
+        InteractionResponded
+            This interaction has already been responded to before.
+        """
+        if self._responded:
+            raise InteractionResponded(self._parent)
+
+        payload: Dict[str, Any] = {
+            'tts': tts,
+        }
+
+        if embed is not MISSING and embeds is not MISSING:
+            raise TypeError('cannot mix embed and embeds keyword arguments')
+
+        if embed is not MISSING:
+            embeds = [embed]
+
+        if embeds:
+            if len(embeds) > 10:
+                raise ValueError('embeds cannot exceed maximum of 10 elements')
+            payload['embeds'] = [e.to_dict() for e in embeds]
+
+        if content is not None:
+            payload['content'] = str(content)
+
+        if ephemeral:
+            payload['flags'] = 64
+
+        if view is not MISSING:
+            payload['components'] = view.to_components()
+
+        parent = self._parent
+        adapter = async_context.get()
+        await adapter.create_interaction_response(
+            parent.id,
+            parent.token,
+            session=parent._session,
+            type=InteractionResponseType.channel_message.value,
+            data=payload,
+        )
+
+        if view is not MISSING:
+            if ephemeral and view.timeout is None:
+                view.timeout = 15 * 60.0
+
+            self._parent._state.store_view(view)
+
+        self._responded = True
+
+    async def edit_message(
+        self,
+        *,
+        content: Optional[Any] = MISSING,
+        embed: Optional[Embed] = MISSING,
+        embeds: List[Embed] = MISSING,
+        attachments: List[Attachment] = MISSING,
+        view: Optional[View] = MISSING,
+    ) -> None:
+        """|coro|
+
+        Responds to this interaction by editing the original message of
+        a component interaction.
+
+        Parameters
+        -----------
+        content: Optional[:class:`str`]
+            The new content to replace the message with. ``None`` removes the content.
+        embeds: List[:class:`Embed`]
+            A list of embeds to edit the message with.
+        embed: Optional[:class:`Embed`]
+            The embed to edit the message with. ``None`` suppresses the embeds.
+            This should not be mixed with the ``embeds`` parameter.
+        attachments: List[:class:`Attachment`]
+            A list of attachments to keep in the message. If ``[]`` is passed
+            then all attachments are removed.
+        view: Optional[:class:`~discord.ui.View`]
+            The updated view to update this message with. If ``None`` is passed then
+            the view is removed.
+
+        Raises
+        -------
+        HTTPException
+            Editing the message failed.
+        TypeError
+            You specified both ``embed`` and ``embeds``.
+        InteractionResponded
+            This interaction has already been responded to before.
+        """
+        if self._responded:
+            raise InteractionResponded(self._parent)
+
+        parent = self._parent
+        msg = parent.message
+        state = parent._state
+        message_id = msg.id if msg else None
+        if parent.type is not InteractionType.component:
+            return
+
+        payload = {}
+        if content is not MISSING:
+            if content is None:
+                payload['content'] = None
+            else:
+                payload['content'] = str(content)
+
+        if embed is not MISSING and embeds is not MISSING:
+            raise TypeError('cannot mix both embed and embeds keyword arguments')
+
+        if embed is not MISSING:
+            if embed is None:
+                embeds = []
+            else:
+                embeds = [embed]
+
+        if embeds is not MISSING:
+            payload['embeds'] = [e.to_dict() for e in embeds]
+
+        if attachments is not MISSING:
+            payload['attachments'] = [a.to_dict() for a in attachments]
+
+        if view is not MISSING:
+            state.prevent_view_updates_for(message_id)
+            if view is None:
+                payload['components'] = []
+            else:
+                payload['components'] = view.to_components()
+
+        adapter = async_context.get()
+        await adapter.create_interaction_response(
+            parent.id,
+            parent.token,
+            session=parent._session,
+            type=InteractionResponseType.message_update.value,
+            data=payload,
+        )
+
+        if view and not view.is_finished():
+            state.store_view(view, message_id)
+
+        self._responded = True
+
+
+class _InteractionMessageState:
+    __slots__ = ('_parent', '_interaction')
+
+    def __init__(self, interaction: Interaction, parent: ConnectionState):
+        self._interaction: Interaction = interaction
+        self._parent: ConnectionState = parent
+
+    def _get_guild(self, guild_id):
+        return self._parent._get_guild(guild_id)
+
+    def store_user(self, data):
+        return self._parent.store_user(data)
+
+    def create_user(self, data):
+        return self._parent.create_user(data)
+
+    @property
+    def http(self):
+        return self._parent.http
+
+    def __getattr__(self, attr):
+        return getattr(self._parent, attr)
+
+
+class InteractionMessage(Message):
+    """Represents the original interaction response message.
+
+    This allows you to edit or delete the message associated with
+    the interaction response. To retrieve this object see :meth:`Interaction.original_message`.
+
+    This inherits from :class:`discord.Message` with changes to
+    :meth:`edit` and :meth:`delete` to work.
+
+    .. versionadded:: 2.0
+    """
+
+    __slots__ = ()
+    _state: _InteractionMessageState
+
+    async def edit(
+        self,
+        content: Optional[str] = MISSING,
+        embeds: List[Embed] = MISSING,
+        embed: Optional[Embed] = MISSING,
+        file: File = MISSING,
+        files: List[File] = MISSING,
+        view: Optional[View] = MISSING,
+        allowed_mentions: Optional[AllowedMentions] = None,
+    ) -> InteractionMessage:
+        """|coro|
+
+        Edits the message.
+
+        Parameters
+        ------------
+        content: Optional[:class:`str`]
+            The content to edit the message with or ``None`` to clear it.
+        embeds: List[:class:`Embed`]
+            A list of embeds to edit the message with.
+        embed: Optional[:class:`Embed`]
+            The embed to edit the message with. ``None`` suppresses the embeds.
+            This should not be mixed with the ``embeds`` parameter.
+        file: :class:`File`
+            The file to upload. This cannot be mixed with ``files`` parameter.
+        files: List[:class:`File`]
+            A list of files to send with the content. This cannot be mixed with the
+            ``file`` parameter.
+        allowed_mentions: :class:`AllowedMentions`
+            Controls the mentions being processed in this message.
+            See :meth:`.abc.Messageable.send` for more information.
+        view: Optional[:class:`~discord.ui.View`]
+            The updated view to update this message with. If ``None`` is passed then
+            the view is removed.
+
+        Raises
+        -------
+        HTTPException
+            Editing the message failed.
+        Forbidden
+            Edited a message that is not yours.
+        TypeError
+            You specified both ``embed`` and ``embeds`` or ``file`` and ``files``
+        ValueError
+            The length of ``embeds`` was invalid.
+
+        Returns
+        ---------
+        :class:`InteractionMessage`
+            The newly edited message.
+        """
+        return await self._state._interaction.edit_original_message(
+            content=content,
+            embeds=embeds,
+            embed=embed,
+            file=file,
+            files=files,
+            view=view,
+            allowed_mentions=allowed_mentions,
+        )
+
+    async def delete(self, *, delay: Optional[float] = None) -> None:
+        """|coro|
+
+        Deletes the message.
+
+        Parameters
+        -----------
+        delay: Optional[:class:`float`]
+            If provided, the number of seconds to wait before deleting the message.
+            The waiting is done in the background and deletion failures are ignored.
+
+        Raises
+        ------
+        Forbidden
+            You do not have proper permissions to delete the message.
+        NotFound
+            The message was deleted already.
+        HTTPException
+            Deleting the message failed.
+        """
+
+        if delay is not None:
+
+            async def inner_call(delay: float = delay):
+                await asyncio.sleep(delay)
+                try:
+                    await self._state._interaction.delete_original_message()
+                except HTTPException:
+                    pass
+
+            asyncio.create_task(inner_call())
+        else:
+            await self._state._interaction.delete_original_message()

discord/invite.py

@@ -22,11 +22,15 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import List, Optional, Type, TypeVar, Union, TYPE_CHECKING
 from .asset import Asset
 from .utils import parse_time, snowflake_time, _get_as_snowflake
 from .object import Object
 from .mixins import Hashable
-from .enums import ChannelType, VerificationLevel, try_enum
+from .enums import ChannelType, VerificationLevel, InviteTarget, try_enum
+from .appinfo import PartialAppInfo
 
 __all__ = (
     'PartialInviteChannel',
@@ -34,6 +38,26 @@ __all__ = (
     'Invite',
 )
 
+if TYPE_CHECKING:
+    from .types.invite import (
+        Invite as InvitePayload,
+        InviteGuild as InviteGuildPayload,
+        GatewayInvite as GatewayInvitePayload,
+    )
+    from .types.channel import (
+        PartialChannel as InviteChannelPayload,
+    )
+    from .state import ConnectionState
+    from .guild import Guild
+    from .abc import GuildChannel
+    from .user import User
+
+    InviteGuildType = Union[Guild, 'PartialInviteGuild', Object]
+    InviteChannelType = Union[GuildChannel, 'PartialInviteChannel', Object]
+
+    import datetime
+
+
 class PartialInviteChannel:
     """Represents a "partial" invite channel.
 
@@ -70,27 +94,28 @@ class PartialInviteChannel:
 
     __slots__ = ('id', 'name', 'type')
 
-    def __init__(self, **kwargs):
-        self.id = kwargs.pop('id')
-        self.name = kwargs.pop('name')
-        self.type = kwargs.pop('type')
+    def __init__(self, data: InviteChannelPayload):
+        self.id: int = int(data['id'])
+        self.name: str = data['name']
+        self.type: ChannelType = try_enum(ChannelType, data['type'])
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name
 
-    def __repr__(self):
-        return '<PartialInviteChannel id={0.id} name={0.name} type={0.type!r}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<PartialInviteChannel id={self.id} name={self.name} type={self.type!r}>'
 
     @property
-    def mention(self):
+    def mention(self) -> str:
         """:class:`str`: The string that allows you to mention the channel."""
         return f'<#{self.id}>'
 
     @property
-    def created_at(self):
+    def created_at(self) -> datetime.datetime:
         """:class:`datetime.datetime`: Returns the channel's creation time in UTC."""
         return snowflake_time(self.id)
 
+
 class PartialInviteGuild:
     """Represents a "partial" invite guild.
 
@@ -125,93 +150,61 @@ class PartialInviteGuild:
         The partial guild's verification level.
     features: List[:class:`str`]
         A list of features the guild has. See :attr:`Guild.features` for more information.
-    icon: Optional[:class:`str`]
-        The partial guild's icon.
-    banner: Optional[:class:`str`]
-        The partial guild's banner.
-    splash: Optional[:class:`str`]
-        The partial guild's invite splash.
     description: Optional[:class:`str`]
         The partial guild's description.
     """
 
-    __slots__ = ('_state', 'features', 'icon', 'banner', 'id', 'name', 'splash',
-                 'verification_level', 'description')
+    __slots__ = ('_state', 'features', '_icon', '_banner', 'id', 'name', '_splash', 'verification_level', 'description')
 
-    def __init__(self, state, data, id):
-        self._state = state
-        self.id = id
-        self.name = data['name']
-        self.features = data.get('features', [])
-        self.icon = data.get('icon')
-        self.banner = data.get('banner')
-        self.splash = data.get('splash')
-        self.verification_level = try_enum(VerificationLevel, data.get('verification_level'))
-        self.description = data.get('description')
+    def __init__(self, state: ConnectionState, data: InviteGuildPayload, id: int):
+        self._state: ConnectionState = state
+        self.id: int = id
+        self.name: str = data['name']
+        self.features: List[str] = data.get('features', [])
+        self._icon: Optional[str] = data.get('icon')
+        self._banner: Optional[str] = data.get('banner')
+        self._splash: Optional[str] = data.get('splash')
+        self.verification_level: VerificationLevel = try_enum(VerificationLevel, data.get('verification_level'))
+        self.description: Optional[str] = data.get('description')
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name
 
-    def __repr__(self):
-        return '<{0.__class__.__name__} id={0.id} name={0.name!r} features={0.features} ' \
-               'description={0.description!r}>'.format(self)
+    def __repr__(self) -> str:
+        return (
+            f'<{self.__class__.__name__} id={self.id} name={self.name!r} features={self.features} '
+            f'description={self.description!r}>'
+        )
 
     @property
-    def created_at(self):
+    def created_at(self) -> datetime.datetime:
         """:class:`datetime.datetime`: Returns the guild's creation time in UTC."""
         return snowflake_time(self.id)
 
     @property
-    def icon_url(self):
-        """:class:`Asset`: Returns the guild's icon asset."""
-        return self.icon_url_as()
-
-    def is_icon_animated(self):
-        """:class:`bool`: Returns ``True`` if the guild has an animated icon.
-
-        .. versionadded:: 1.4
-        """
-        return bool(self.icon and self.icon.startswith('a_'))
-
-    def icon_url_as(self, *, format=None, static_format='webp', size=1024):
-        """The same operation as :meth:`Guild.icon_url_as`.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_guild_icon(self._state, self, format=format, static_format=static_format, size=size)
+    def icon(self) -> Optional[Asset]:
+        """Optional[:class:`Asset`]: Returns the guild's icon asset, if available."""
+        if self._icon is None:
+            return None
+        return Asset._from_guild_icon(self._state, self.id, self._icon)
 
     @property
-    def banner_url(self):
-        """:class:`Asset`: Returns the guild's banner asset."""
-        return self.banner_url_as()
-
-    def banner_url_as(self, *, format='webp', size=2048):
-        """The same operation as :meth:`Guild.banner_url_as`.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_guild_image(self._state, self.id, self.banner, 'banners', format=format, size=size)
+    def banner(self) -> Optional[Asset]:
+        """Optional[:class:`Asset`]: Returns the guild's banner asset, if available."""
+        if self._banner is None:
+            return None
+        return Asset._from_guild_image(self._state, self.id, self._banner, path='banners')
 
     @property
-    def splash_url(self):
-        """:class:`Asset`: Returns the guild's invite splash asset."""
-        return self.splash_url_as()
+    def splash(self) -> Optional[Asset]:
+        """Optional[:class:`Asset`]: Returns the guild's invite splash asset, if available."""
+        if self._splash is None:
+            return None
+        return Asset._from_guild_image(self._state, self.id, self._splash, path='splashes')
 
-    def splash_url_as(self, *, format='webp', size=2048):
-        """The same operation as :meth:`Guild.splash_url_as`.
 
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_guild_image(self._state, self.id, self.splash, 'splashes', format=format, size=size)
+I = TypeVar('I', bound='Invite')
+
 
 class Invite(Hashable):
     r"""Represents a Discord :class:`Guild` or :class:`abc.GuildChannel` invite.
@@ -237,32 +230,35 @@ class Invite(Hashable):
 
             Returns the invite URL.
 
+
     The following table illustrates what methods will obtain the attributes:
 
-    +------------------------------------+----------------------------------------------------------+
-    |             Attribute              |                          Method                          |
-    +====================================+==========================================================+
-    | :attr:`max_age`                    | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites` |
-    +------------------------------------+----------------------------------------------------------+
-    | :attr:`max_uses`                   | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites` |
-    +------------------------------------+----------------------------------------------------------+
-    | :attr:`created_at`                 | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites` |
-    +------------------------------------+----------------------------------------------------------+
-    | :attr:`temporary`                  | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites` |
-    +------------------------------------+----------------------------------------------------------+
-    | :attr:`uses`                       | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites` |
-    +------------------------------------+----------------------------------------------------------+
-    | :attr:`approximate_member_count`   | :meth:`Client.fetch_invite`                              |
-    +------------------------------------+----------------------------------------------------------+
-    | :attr:`approximate_presence_count` | :meth:`Client.fetch_invite`                              |
-    +------------------------------------+----------------------------------------------------------+
+    +------------------------------------+------------------------------------------------------------+
+    |             Attribute              |                          Method                            |
+    +====================================+============================================================+
+    | :attr:`max_age`                    | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites`   |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`max_uses`                   | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites`   |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`created_at`                 | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites`   |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`temporary`                  | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites`   |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`uses`                       | :meth:`abc.GuildChannel.invites`\, :meth:`Guild.invites`   |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`approximate_member_count`   | :meth:`Client.fetch_invite` with `with_counts` enabled     |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`approximate_presence_count` | :meth:`Client.fetch_invite` with `with_counts` enabled     |
+    +------------------------------------+------------------------------------------------------------+
+    | :attr:`expires_at`                 | :meth:`Client.fetch_invite` with `with_expiration` enabled |
+    +------------------------------------+------------------------------------------------------------+
 
     If it's not in the table above then it is available by all methods.
 
     Attributes
     -----------
     max_age: :class:`int`
-        How long the before the invite expires in seconds.
+        How long before the invite expires in seconds.
         A value of ``0`` indicates that it doesn't expire.
     code: :class:`str`
         The URL fragment used for the invite.
@@ -280,105 +276,188 @@ class Invite(Hashable):
     max_uses: :class:`int`
         How many times the invite can be used.
         A value of ``0`` indicates that it has unlimited uses.
-    inviter: :class:`User`
+    inviter: Optional[:class:`User`]
         The user who created the invite.
     approximate_member_count: Optional[:class:`int`]
         The approximate number of members in the guild.
     approximate_presence_count: Optional[:class:`int`]
         The approximate number of members currently active in the guild.
         This includes idle, dnd, online, and invisible members. Offline members are excluded.
+    expires_at: Optional[:class:`datetime.datetime`]
+        The expiration date of the invite. If the value is ``None`` when received through
+        `Client.fetch_invite` with `with_expiration` enabled, the invite will never expire.
+
+        .. versionadded:: 2.0
+
     channel: Union[:class:`abc.GuildChannel`, :class:`Object`, :class:`PartialInviteChannel`]
         The channel the invite is for.
+    target_type: :class:`InviteTarget`
+        The type of target for the voice channel invite.
+
+        .. versionadded:: 2.0
+
+    target_user: Optional[:class:`User`]
+        The user whose stream to display for this invite, if any.
+
+        .. versionadded:: 2.0
+
+    target_application: Optional[:class:`PartialAppInfo`]
+        The embedded application the invite targets, if any.
+
+        .. versionadded:: 2.0
     """
 
-    __slots__ = ('max_age', 'code', 'guild', 'revoked', 'created_at', 'uses',
-                 'temporary', 'max_uses', 'inviter', 'channel', '_state',
-                 'approximate_member_count', 'approximate_presence_count' )
+    __slots__ = (
+        'max_age',
+        'code',
+        'guild',
+        'revoked',
+        'created_at',
+        'uses',
+        'temporary',
+        'max_uses',
+        'inviter',
+        'channel',
+        'target_user',
+        'target_type',
+        '_state',
+        'approximate_member_count',
+        'approximate_presence_count',
+        'target_application',
+        'expires_at',
+    )
 
     BASE = 'https://discord.gg'
 
-    def __init__(self, *, state, data):
-        self._state = state
-        self.max_age = data.get('max_age')
-        self.code = data.get('code')
-        self.guild = data.get('guild')
-        self.revoked = data.get('revoked')
-        self.created_at = parse_time(data.get('created_at'))
-        self.temporary = data.get('temporary')
-        self.uses = data.get('uses')
-        self.max_uses = data.get('max_uses')
-        self.approximate_presence_count = data.get('approximate_presence_count')
-        self.approximate_member_count = data.get('approximate_member_count')
+    def __init__(
+        self,
+        *,
+        state: ConnectionState,
+        data: InvitePayload,
+        guild: Optional[Union[PartialInviteGuild, Guild]] = None,
+        channel: Optional[Union[PartialInviteChannel, GuildChannel]] = None,
+    ):
+        self._state: ConnectionState = state
+        self.max_age: Optional[int] = data.get('max_age')
+        self.code: str = data['code']
+        self.guild: Optional[InviteGuildType] = self._resolve_guild(data.get('guild'), guild)
+        self.revoked: Optional[bool] = data.get('revoked')
+        self.created_at: Optional[datetime.datetime] = parse_time(data.get('created_at'))
+        self.temporary: Optional[bool] = data.get('temporary')
+        self.uses: Optional[int] = data.get('uses')
+        self.max_uses: Optional[int] = data.get('max_uses')
+        self.approximate_presence_count: Optional[int] = data.get('approximate_presence_count')
+        self.approximate_member_count: Optional[int] = data.get('approximate_member_count')
+
+        expires_at = data.get('expires_at', None)
+        self.expires_at: Optional[datetime.datetime] = parse_time(expires_at) if expires_at else None
 
         inviter_data = data.get('inviter')
-        self.inviter = None if inviter_data is None else self._state.store_user(inviter_data)
-        self.channel = data.get('channel')
+        self.inviter: Optional[User] = None if inviter_data is None else self._state.create_user(inviter_data)
+
+        self.channel: Optional[InviteChannelType] = self._resolve_channel(data.get('channel'), channel)
+
+        target_user_data = data.get('target_user')
+        self.target_user: Optional[User] = None if target_user_data is None else self._state.create_user(target_user_data)
+
+        self.target_type: InviteTarget = try_enum(InviteTarget, data.get("target_type", 0))
+
+        application = data.get('target_application')
+        self.target_application: Optional[PartialAppInfo] = (
+            PartialAppInfo(data=application, state=state) if application else None
+        )
 
     @classmethod
-    def from_incomplete(cls, *, state, data):
+    def from_incomplete(cls: Type[I], *, state: ConnectionState, data: InvitePayload) -> I:
+        guild: Optional[Union[Guild, PartialInviteGuild]]
         try:
-            guild_id = int(data['guild']['id'])
+            guild_data = data['guild']
         except KeyError:
             # If we're here, then this is a group DM
             guild = None
         else:
+            guild_id = int(guild_data['id'])
             guild = state._get_guild(guild_id)
             if guild is None:
                 # If it's not cached, then it has to be a partial guild
-                guild_data = data['guild']
                 guild = PartialInviteGuild(state, guild_data, guild_id)
 
         # As far as I know, invites always need a channel
         # So this should never raise.
-        channel_data = data['channel']
-        channel_id = int(channel_data['id'])
-        channel_type = try_enum(ChannelType, channel_data['type'])
-        channel = PartialInviteChannel(id=channel_id, name=channel_data['name'], type=channel_type)
+        channel: Union[PartialInviteChannel, GuildChannel] = PartialInviteChannel(data['channel'])
         if guild is not None and not isinstance(guild, PartialInviteGuild):
             # Upgrade the partial data if applicable
-            channel = guild.get_channel(channel_id) or channel
+            channel = guild.get_channel(channel.id) or channel
 
-        data['guild'] = guild
-        data['channel'] = channel
-        return cls(state=state, data=data)
+        return cls(state=state, data=data, guild=guild, channel=channel)
 
     @classmethod
-    def from_gateway(cls, *, state, data):
-        guild_id = _get_as_snowflake(data, 'guild_id')
-        guild = state._get_guild(guild_id)
-        channel_id = _get_as_snowflake(data, 'channel_id')
+    def from_gateway(cls: Type[I], *, state: ConnectionState, data: GatewayInvitePayload) -> I:
+        guild_id: Optional[int] = _get_as_snowflake(data, 'guild_id')
+        guild: Optional[Union[Guild, Object]] = state._get_guild(guild_id)
+        channel_id = int(data['channel_id'])
         if guild is not None:
-            channel = guild.get_channel(channel_id) or Object(id=channel_id)
+            channel = guild.get_channel(channel_id) or Object(id=channel_id)  # type: ignore
         else:
-            guild = Object(id=guild_id)
+            guild = Object(id=guild_id) if guild_id is not None else None
             channel = Object(id=channel_id)
 
-        data['guild'] = guild
-        data['channel'] = channel
-        return cls(state=state, data=data)
+        return cls(state=state, data=data, guild=guild, channel=channel)  # type: ignore
 
-    def __str__(self):
+    def _resolve_guild(
+        self,
+        data: Optional[InviteGuildPayload],
+        guild: Optional[Union[Guild, PartialInviteGuild]] = None,
+    ) -> Optional[InviteGuildType]:
+        if guild is not None:
+            return guild
+
+        if data is None:
+            return None
+
+        guild_id = int(data['id'])
+        return PartialInviteGuild(self._state, data, guild_id)
+
+    def _resolve_channel(
+        self,
+        data: Optional[InviteChannelPayload],
+        channel: Optional[Union[PartialInviteChannel, GuildChannel]] = None,
+    ) -> Optional[InviteChannelType]:
+        if channel is not None:
+            return channel
+
+        if data is None:
+            return None
+
+        return PartialInviteChannel(data)
+
+    def __str__(self) -> str:
         return self.url
 
-    def __repr__(self):
-        return '<Invite code={0.code!r} guild={0.guild!r} ' \
-                'online={0.approximate_presence_count} ' \
-                'members={0.approximate_member_count}>'.format(self)
+    def __int__(self) -> int:
+        return 0  # To keep the object compatible with the hashable abc.
 
-    def __hash__(self):
+    def __repr__(self) -> str:
+        return (
+            f'<Invite code={self.code!r} guild={self.guild!r} '
+            f'online={self.approximate_presence_count} '
+            f'members={self.approximate_member_count}>'
+        )
+
+    def __hash__(self) -> int:
         return hash(self.code)
 
     @property
-    def id(self):
+    def id(self) -> str:
         """:class:`str`: Returns the proper code portion of the invite."""
         return self.code
 
     @property
-    def url(self):
+    def url(self) -> str:
         """:class:`str`: A property that retrieves the invite URL."""
         return self.BASE + '/' + self.code
 
-    async def delete(self, *, reason=None):
+    async def delete(self, *, reason: Optional[str] = None):
         """|coro|
 
         Revokes the instant invite.

discord/iterators.py

@@ -26,10 +26,10 @@ from __future__ import annotations
 
 import asyncio
 import datetime
-from typing import TYPE_CHECKING, TypeVar, Optional, Any, Callable, Union, List, AsyncIterator, Coroutine
+from typing import Awaitable, TYPE_CHECKING, TypeVar, Optional, Any, Callable, Union, List, AsyncIterator
 
 from .errors import NoMoreItems
-from .utils import time_snowflake, maybe_coroutine
+from .utils import snowflake_time, time_snowflake, maybe_coroutine
 from .object import Object
 from .audit_logs import AuditLogEntry
 
@@ -42,24 +42,46 @@ __all__ = (
 )
 
 if TYPE_CHECKING:
+    from .types.audit_log import (
+        AuditLog as AuditLogPayload,
+    )
+    from .types.guild import (
+        Guild as GuildPayload,
+    )
+    from .types.message import (
+        Message as MessagePayload,
+    )
+    from .types.user import (
+        PartialUser as PartialUserPayload,
+    )
+
+    from .types.threads import (
+        Thread as ThreadPayload,
+    )
+
     from .member import Member
     from .user import User
     from .message import Message
     from .audit_logs import AuditLogEntry
     from .guild import Guild
+    from .threads import Thread
+    from .abc import Snowflake
 
 T = TypeVar('T')
 OT = TypeVar('OT')
-_Func = Callable[[T], Union[OT, Coroutine[Any, Any, OT]]]
-_Predicate = Callable[[T], Union[T, Coroutine[Any, Any, T]]]
+_Func = Callable[[T], Union[OT, Awaitable[OT]]]
 
 OLDEST_OBJECT = Object(id=0)
 
+
 class _AsyncIterator(AsyncIterator[T]):
     __slots__ = ()
 
-    def get(self, **attrs: Any) -> Optional[T]:
-        def predicate(elem):
+    async def next(self) -> T:
+        raise NotImplementedError
+
+    def get(self, **attrs: Any) -> Awaitable[Optional[T]]:
+        def predicate(elem: T):
             for attr, val in attrs.items():
                 nested = attr.split('__')
                 obj = elem
@@ -72,7 +94,7 @@ class _AsyncIterator(AsyncIterator[T]):
 
         return self.find(predicate)
 
-    async def find(self, predicate: _Predicate[T]) -> Optional[T]:
+    async def find(self, predicate: _Func[T, bool]) -> Optional[T]:
         while True:
             try:
                 elem = await self.next()
@@ -91,7 +113,7 @@ class _AsyncIterator(AsyncIterator[T]):
     def map(self, func: _Func[T, OT]) -> _MappedAsyncIterator[OT]:
         return _MappedAsyncIterator(self, func)
 
-    def filter(self, predicate: _Predicate[T]) -> _FilteredAsyncIterator[T]:
+    def filter(self, predicate: _Func[T, bool]) -> _FilteredAsyncIterator[T]:
         return _FilteredAsyncIterator(self, predicate)
 
     async def flatten(self) -> List[T]:
@@ -103,16 +125,18 @@ class _AsyncIterator(AsyncIterator[T]):
         except NoMoreItems:
             raise StopAsyncIteration()
 
+
 def _identity(x):
     return x
 
-class _ChunkedAsyncIterator(_AsyncIterator[T]):
+
+class _ChunkedAsyncIterator(_AsyncIterator[List[T]]):
     def __init__(self, iterator, max_size):
         self.iterator = iterator
         self.max_size = max_size
 
-    async def next(self) -> T:
-        ret = []
+    async def next(self) -> List[T]:
+        ret: List[T] = []
         n = 0
         while n < self.max_size:
             try:
@@ -126,6 +150,7 @@ class _ChunkedAsyncIterator(_AsyncIterator[T]):
                 n += 1
         return ret
 
+
 class _MappedAsyncIterator(_AsyncIterator[T]):
     def __init__(self, iterator, func):
         self.iterator = iterator
@@ -136,6 +161,7 @@ class _MappedAsyncIterator(_AsyncIterator[T]):
         item = await self.iterator.next()
         return await maybe_coroutine(self.func, item)
 
+
 class _FilteredAsyncIterator(_AsyncIterator[T]):
     def __init__(self, iterator, predicate):
         self.iterator = iterator
@@ -155,6 +181,7 @@ class _FilteredAsyncIterator(_AsyncIterator[T]):
             if ret:
                 return item
 
+
 class ReactionIterator(_AsyncIterator[Union['User', 'Member']]):
     def __init__(self, message, emoji, limit=100, after=None):
         self.message = message
@@ -168,7 +195,7 @@ class ReactionIterator(_AsyncIterator[Union['User', 'Member']]):
         self.channel_id = message.channel.id
         self.users = asyncio.Queue()
 
-    async def next(self) -> T:
+    async def next(self) -> Union[User, Member]:
         if self.users.empty():
             await self.fill_users()
 
@@ -185,7 +212,9 @@ class ReactionIterator(_AsyncIterator[Union['User', 'Member']]):
             retrieve = self.limit if self.limit <= 100 else 100
 
             after = self.after.id if self.after else None
-            data = await self.getter(self.channel_id, self.message.id, self.emoji, retrieve, after=after)
+            data: List[PartialUserPayload] = await self.getter(
+                self.channel_id, self.message.id, self.emoji, retrieve, after=after
+            )
 
             if data:
                 self.limit -= retrieve
@@ -203,6 +232,7 @@ class ReactionIterator(_AsyncIterator[Union['User', 'Member']]):
                     else:
                         await self.users.put(User(state=self.state, data=element))
 
+
 class HistoryIterator(_AsyncIterator['Message']):
     """Iterator for receiving a channel's message history.
 
@@ -237,8 +267,7 @@ class HistoryIterator(_AsyncIterator['Message']):
         ``True`` if `after` is specified, otherwise ``False``.
     """
 
-    def __init__(self, messageable, limit,
-                 before=None, after=None, around=None, oldest_first=None):
+    def __init__(self, messageable, limit, before=None, after=None, around=None, oldest_first=None):
 
         if isinstance(before, datetime.datetime):
             before = Object(id=time_snowflake(before, high=False))
@@ -272,7 +301,7 @@ class HistoryIterator(_AsyncIterator['Message']):
             elif self.limit == 101:
                 self.limit = 100  # Thanks discord
 
-            self._retrieve_messages = self._retrieve_messages_around_strategy
+            self._retrieve_messages = self._retrieve_messages_around_strategy  # type: ignore
             if self.before and self.after:
                 self._filter = lambda m: self.after.id < int(m['id']) < self.before.id
             elif self.before:
@@ -281,15 +310,15 @@ class HistoryIterator(_AsyncIterator['Message']):
                 self._filter = lambda m: self.after.id < int(m['id'])
         else:
             if self.reverse:
-                self._retrieve_messages = self._retrieve_messages_after_strategy
-                if (self.before):
+                self._retrieve_messages = self._retrieve_messages_after_strategy  # type: ignore
+                if self.before:
                     self._filter = lambda m: int(m['id']) < self.before.id
             else:
-                self._retrieve_messages = self._retrieve_messages_before_strategy
-                if (self.after and self.after != OLDEST_OBJECT):
+                self._retrieve_messages = self._retrieve_messages_before_strategy  # type: ignore
+                if self.after and self.after != OLDEST_OBJECT:
                     self._filter = lambda m: int(m['id']) > self.after.id
 
-    async def next(self) -> T:
+    async def next(self) -> Message:
         if self.messages.empty():
             await self.fill_messages()
 
@@ -316,7 +345,7 @@ class HistoryIterator(_AsyncIterator['Message']):
         if self._get_retrieve():
             data = await self._retrieve_messages(self.retrieve)
             if len(data) < 100:
-                self.limit = 0 # terminate the infinite loop
+                self.limit = 0  # terminate the infinite loop
 
             if self.reverse:
                 data = reversed(data)
@@ -327,14 +356,14 @@ class HistoryIterator(_AsyncIterator['Message']):
             for element in data:
                 await self.messages.put(self.state.create_message(channel=channel, data=element))
 
-    async def _retrieve_messages(self, retrieve):
+    async def _retrieve_messages(self, retrieve) -> List[Message]:
         """Retrieve messages and update next parameters."""
-        pass
+        raise NotImplementedError
 
     async def _retrieve_messages_before_strategy(self, retrieve):
         """Retrieve messages using before parameter."""
         before = self.before.id if self.before else None
-        data = await self.logs_from(self.channel.id, retrieve, before=before)
+        data: List[MessagePayload] = await self.logs_from(self.channel.id, retrieve, before=before)
         if len(data):
             if self.limit is not None:
                 self.limit -= retrieve
@@ -344,7 +373,7 @@ class HistoryIterator(_AsyncIterator['Message']):
     async def _retrieve_messages_after_strategy(self, retrieve):
         """Retrieve messages using after parameter."""
         after = self.after.id if self.after else None
-        data = await self.logs_from(self.channel.id, retrieve, after=after)
+        data: List[MessagePayload] = await self.logs_from(self.channel.id, retrieve, after=after)
         if len(data):
             if self.limit is not None:
                 self.limit -= retrieve
@@ -355,11 +384,12 @@ class HistoryIterator(_AsyncIterator['Message']):
         """Retrieve messages using around parameter."""
         if self.around:
             around = self.around.id if self.around else None
-            data = await self.logs_from(self.channel.id, retrieve, around=around)
+            data: List[MessagePayload] = await self.logs_from(self.channel.id, retrieve, around=around)
             self.around = None
             return data
         return []
 
+
 class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
     def __init__(self, guild, limit=None, before=None, after=None, oldest_first=None, user_id=None, action_type=None):
         if isinstance(before, datetime.datetime):
@@ -367,7 +397,6 @@ class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
         if isinstance(after, datetime.datetime):
             after = Object(id=time_snowflake(after, high=True))
 
-
         if oldest_first is None:
             self.reverse = after is not None
         else:
@@ -384,12 +413,10 @@ class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
         self._users = {}
         self._state = guild._state
 
-
         self._filter = None  # entry dict -> bool
 
         self.entries = asyncio.Queue()
 
-
         if self.reverse:
             self._strategy = self._after_strategy
             if self.before:
@@ -401,8 +428,9 @@ class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
 
     async def _before_strategy(self, retrieve):
         before = self.before.id if self.before else None
-        data = await self.request(self.guild.id, limit=retrieve, user_id=self.user_id,
-                                  action_type=self.action_type, before=before)
+        data: AuditLogPayload = await self.request(
+            self.guild.id, limit=retrieve, user_id=self.user_id, action_type=self.action_type, before=before
+        )
 
         entries = data.get('audit_log_entries', [])
         if len(data) and entries:
@@ -413,8 +441,9 @@ class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
 
     async def _after_strategy(self, retrieve):
         after = self.after.id if self.after else None
-        data = await self.request(self.guild.id, limit=retrieve, user_id=self.user_id,
-                                  action_type=self.action_type, after=after)
+        data: AuditLogPayload = await self.request(
+            self.guild.id, limit=retrieve, user_id=self.user_id, action_type=self.action_type, after=after
+        )
         entries = data.get('audit_log_entries', [])
         if len(data) and entries:
             if self.limit is not None:
@@ -422,7 +451,7 @@ class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
             self.after = Object(id=int(entries[0]['id']))
         return data.get('users', []), entries
 
-    async def next(self) -> T:
+    async def next(self) -> AuditLogEntry:
         if self.entries.empty():
             await self._fill()
 
@@ -446,7 +475,7 @@ class AuditLogIterator(_AsyncIterator['AuditLogEntry']):
         if self._get_retrieve():
             users, data = await self._strategy(self.retrieve)
             if len(data) < 100:
-                self.limit = 0 # terminate the infinite loop
+                self.limit = 0  # terminate the infinite loop
 
             if self.reverse:
                 data = reversed(data)
@@ -493,6 +522,7 @@ class GuildIterator(_AsyncIterator['Guild']):
     after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
         Object after which all guilds must be.
     """
+
     def __init__(self, bot, limit, before=None, after=None):
 
         if isinstance(before, datetime.datetime):
@@ -512,14 +542,14 @@ class GuildIterator(_AsyncIterator['Guild']):
         self.guilds = asyncio.Queue()
 
         if self.before and self.after:
-            self._retrieve_guilds = self._retrieve_guilds_before_strategy
+            self._retrieve_guilds = self._retrieve_guilds_before_strategy  # type: ignore
             self._filter = lambda m: int(m['id']) > self.after.id
         elif self.after:
-            self._retrieve_guilds = self._retrieve_guilds_after_strategy
+            self._retrieve_guilds = self._retrieve_guilds_after_strategy  # type: ignore
         else:
-            self._retrieve_guilds = self._retrieve_guilds_before_strategy
+            self._retrieve_guilds = self._retrieve_guilds_before_strategy  # type: ignore
 
-    async def next(self) -> T:
+    async def next(self) -> Guild:
         if self.guilds.empty():
             await self.fill_guilds()
 
@@ -539,6 +569,7 @@ class GuildIterator(_AsyncIterator['Guild']):
 
     def create_guild(self, data):
         from .guild import Guild
+
         return Guild(state=self.state, data=data)
 
     async def fill_guilds(self):
@@ -553,14 +584,14 @@ class GuildIterator(_AsyncIterator['Guild']):
             for element in data:
                 await self.guilds.put(self.create_guild(element))
 
-    async def _retrieve_guilds(self, retrieve):
+    async def _retrieve_guilds(self, retrieve) -> List[Guild]:
         """Retrieve guilds and update next parameters."""
-        pass
+        raise NotImplementedError
 
     async def _retrieve_guilds_before_strategy(self, retrieve):
         """Retrieve guilds using before parameter."""
         before = self.before.id if self.before else None
-        data = await self.get_guilds(retrieve, before=before)
+        data: List[GuildPayload] = await self.get_guilds(retrieve, before=before)
         if len(data):
             if self.limit is not None:
                 self.limit -= retrieve
@@ -570,13 +601,14 @@ class GuildIterator(_AsyncIterator['Guild']):
     async def _retrieve_guilds_after_strategy(self, retrieve):
         """Retrieve guilds using after parameter."""
         after = self.after.id if self.after else None
-        data = await self.get_guilds(retrieve, after=after)
+        data: List[GuildPayload] = await self.get_guilds(retrieve, after=after)
         if len(data):
             if self.limit is not None:
                 self.limit -= retrieve
             self.after = Object(id=int(data[0]['id']))
         return data
 
+
 class MemberIterator(_AsyncIterator['Member']):
     def __init__(self, guild, limit=1000, after=None):
 
@@ -591,7 +623,7 @@ class MemberIterator(_AsyncIterator['Member']):
         self.get_members = self.state.http.get_members
         self.members = asyncio.Queue()
 
-    async def next(self) -> T:
+    async def next(self) -> Member:
         if self.members.empty():
             await self.fill_members()
 
@@ -618,7 +650,7 @@ class MemberIterator(_AsyncIterator['Member']):
                 return
 
             if len(data) < 1000:
-                self.limit = 0 # terminate loop
+                self.limit = 0  # terminate loop
 
             self.after = Object(id=int(data[-1]['user']['id']))
 
@@ -627,4 +659,95 @@ class MemberIterator(_AsyncIterator['Member']):
 
     def create_member(self, data):
         from .member import Member
+
         return Member(data=data, guild=self.guild, state=self.state)
+
+
+class ArchivedThreadIterator(_AsyncIterator['Thread']):
+    def __init__(
+        self,
+        channel_id: int,
+        guild: Guild,
+        limit: Optional[int],
+        joined: bool,
+        private: bool,
+        before: Optional[Union[Snowflake, datetime.datetime]] = None,
+    ):
+        self.channel_id = channel_id
+        self.guild = guild
+        self.limit = limit
+        self.joined = joined
+        self.private = private
+        self.http = guild._state.http
+
+        if joined and not private:
+            raise ValueError('Cannot iterate over joined public archived threads')
+
+        self.before: Optional[str]
+        if before is None:
+            self.before = None
+        elif isinstance(before, datetime.datetime):
+            if joined:
+                self.before = str(time_snowflake(before, high=False))
+            else:
+                self.before = before.isoformat()
+        else:
+            if joined:
+                self.before = str(before.id)
+            else:
+                self.before = snowflake_time(before.id).isoformat()
+
+        self.update_before: Callable[[ThreadPayload], str] = self.get_archive_timestamp
+
+        if joined:
+            self.endpoint = self.http.get_joined_private_archived_threads
+            self.update_before = self.get_thread_id
+        elif private:
+            self.endpoint = self.http.get_private_archived_threads
+        else:
+            self.endpoint = self.http.get_public_archived_threads
+
+        self.queue: asyncio.Queue[Thread] = asyncio.Queue()
+        self.has_more: bool = True
+
+    async def next(self) -> Thread:
+        if self.queue.empty():
+            await self.fill_queue()
+
+        try:
+            return self.queue.get_nowait()
+        except asyncio.QueueEmpty:
+            raise NoMoreItems()
+
+    @staticmethod
+    def get_archive_timestamp(data: ThreadPayload) -> str:
+        return data['thread_metadata']['archive_timestamp']
+
+    @staticmethod
+    def get_thread_id(data: ThreadPayload) -> str:
+        return data['id']  # type: ignore
+
+    async def fill_queue(self) -> None:
+        if not self.has_more:
+            raise NoMoreItems()
+
+        limit = 50 if self.limit is None else max(self.limit, 50)
+        data = await self.endpoint(self.channel_id, before=self.before, limit=limit)
+
+        # This stuff is obviously WIP because 'members' is always empty
+        threads: List[ThreadPayload] = data.get('threads', [])
+        for d in reversed(threads):
+            self.queue.put_nowait(self.create_thread(d))
+
+        self.has_more = data.get('has_more', False)
+        if self.limit is not None:
+            self.limit -= len(threads)
+            if self.limit <= 0:
+                self.has_more = False
+
+        if self.has_more:
+            self.before = self.update_before(threads[-1])
+
+    def create_thread(self, data: ThreadPayload) -> Thread:
+        from .threads import Thread
+        return Thread(guild=self.guild, state=self.guild._state, data=data)

discord/member.py

@@ -22,18 +22,22 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 import datetime
 import inspect
 import itertools
 import sys
 from operator import attrgetter
+from typing import Any, Dict, List, Literal, Optional, TYPE_CHECKING, Tuple, Type, TypeVar, Union, overload
 
 import discord.abc
 
 from . import utils
-from .errors import ClientException
-from .user import BaseUser, User
-from .activity import create_activity
+from .asset import Asset
+from .utils import MISSING
+from .user import BaseUser, User, _UserTag
+from .activity import create_activity, ActivityTypes
 from .permissions import Permissions
 from .enums import Status, try_enum
 from .colour import Colour
@@ -44,6 +48,27 @@ __all__ = (
     'Member',
 )
 
+if TYPE_CHECKING:
+    from .asset import Asset
+    from .channel import DMChannel, VoiceChannel, StageChannel
+    from .flags import PublicUserFlags
+    from .guild import Guild
+    from .types.activity import PartialPresenceUpdate
+    from .types.member import (
+        MemberWithUser as MemberWithUserPayload,
+        Member as MemberPayload,
+        UserWithMember as UserWithMemberPayload,
+    )
+    from .types.user import User as UserPayload
+    from .abc import Snowflake
+    from .state import ConnectionState
+    from .message import Message
+    from .role import Role
+    from .types.voice import VoiceState as VoiceStatePayload
+
+    VocalGuildChannel = Union[VoiceChannel, StageChannel]
+
+
 class VoiceState:
     """Represents a Discord user's voice state.
 
@@ -87,38 +112,49 @@ class VoiceState:
         is not currently in a voice channel.
     """
 
-    __slots__ = ('session_id', 'deaf', 'mute', 'self_mute',
-                 'self_stream', 'self_video', 'self_deaf', 'afk', 'channel',
-                 'requested_to_speak_at', 'suppress')
+    __slots__ = (
+        'session_id',
+        'deaf',
+        'mute',
+        'self_mute',
+        'self_stream',
+        'self_video',
+        'self_deaf',
+        'afk',
+        'channel',
+        'requested_to_speak_at',
+        'suppress',
+    )
 
-    def __init__(self, *, data, channel=None):
-        self.session_id = data.get('session_id')
+    def __init__(self, *, data: VoiceStatePayload, channel: Optional[VocalGuildChannel] = None):
+        self.session_id: str = data.get('session_id')
         self._update(data, channel)
 
-    def _update(self, data, channel):
-        self.self_mute = data.get('self_mute', False)
-        self.self_deaf = data.get('self_deaf', False)
-        self.self_stream = data.get('self_stream', False)
-        self.self_video = data.get('self_video', False)
-        self.afk = data.get('suppress', False)
-        self.mute = data.get('mute', False)
-        self.deaf = data.get('deaf', False)
-        self.suppress = data.get('suppress', False)
-        self.requested_to_speak_at = utils.parse_time(data.get('request_to_speak_timestamp'))
-        self.channel = channel
+    def _update(self, data: VoiceStatePayload, channel: Optional[VocalGuildChannel]):
+        self.self_mute: bool = data.get('self_mute', False)
+        self.self_deaf: bool = data.get('self_deaf', False)
+        self.self_stream: bool = data.get('self_stream', False)
+        self.self_video: bool = data.get('self_video', False)
+        self.afk: bool = data.get('suppress', False)
+        self.mute: bool = data.get('mute', False)
+        self.deaf: bool = data.get('deaf', False)
+        self.suppress: bool = data.get('suppress', False)
+        self.requested_to_speak_at: Optional[datetime.datetime] = utils.parse_time(data.get('request_to_speak_timestamp'))
+        self.channel: Optional[VocalGuildChannel] = channel
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         attrs = [
             ('self_mute', self.self_mute),
             ('self_deaf', self.self_deaf),
             ('self_stream', self.self_stream),
             ('suppress', self.suppress),
             ('requested_to_speak_at', self.requested_to_speak_at),
-            ('channel', self.channel)
+            ('channel', self.channel),
         ]
         inner = ' '.join('%s=%r' % t for t in attrs)
         return f'<{self.__class__.__name__} {inner}>'
 
+
 def flatten_user(cls):
     for attr, value in itertools.chain(BaseUser.__dict__.items(), User.__dict__.items()):
         # ignore private/special methods
@@ -142,9 +178,12 @@ def flatten_user(cls):
             def generate_function(x):
                 # We want sphinx to properly show coroutine functions as coroutines
                 if inspect.iscoroutinefunction(value):
-                    async def general(self, *args, **kwargs):
+
+                    async def general(self, *args, **kwargs):  # type: ignore
                         return await getattr(self._user, x)(*args, **kwargs)
+
                 else:
+
                     def general(self, *args, **kwargs):
                         return getattr(self._user, x)(*args, **kwargs)
 
@@ -157,10 +196,12 @@ def flatten_user(cls):
 
     return cls
 
-_BaseUser = discord.abc.User
+
+M = TypeVar('M', bound='Member')
+
 
 @flatten_user
-class Member(discord.abc.Messageable, _BaseUser):
+class Member(discord.abc.Messageable, _UserTag):
     """Represents a Discord member to a :class:`Guild`.
 
     This implements a lot of the functionality of :class:`User`.
@@ -185,6 +226,10 @@ class Member(discord.abc.Messageable, _BaseUser):
 
             Returns the member's name with the discriminator.
 
+        .. describe:: int(x)
+
+            Returns the user's ID.
+
     Attributes
     ----------
     joined_at: Optional[:class:`datetime.datetime`]
@@ -192,6 +237,13 @@ class Member(discord.abc.Messageable, _BaseUser):
         If the member left and rejoined the guild, this will be the latest date. In certain cases, this can be ``None``.
     activities: Tuple[Union[:class:`BaseActivity`, :class:`Spotify`]]
         The activities that the user is currently doing.
+
+        .. note::
+
+            Due to a Discord API limitation, a user's Spotify activity may not appear
+            if they are listening to a song with a title longer
+            than 128 characters. See :issue:`1738` for more information.
+
     guild: :class:`Guild`
         The guild that the member belongs to.
     nick: Optional[:class:`str`]
@@ -202,80 +254,101 @@ class Member(discord.abc.Messageable, _BaseUser):
         .. versionadded:: 1.6
     premium_since: Optional[:class:`datetime.datetime`]
         An aware datetime object that specifies the date and time in UTC when the member used their
-        Nitro boost on the guild, if available. This could be ``None``.
+        "Nitro boost" on the guild, if available. This could be ``None``.
     """
 
-    __slots__ = ('_roles', 'joined_at', 'premium_since', '_client_status',
-                 'activities', 'guild', 'pending', 'nick', '_user', '_state')
+    __slots__ = (
+        '_roles',
+        'joined_at',
+        'premium_since',
+        'activities',
+        'guild',
+        'pending',
+        'nick',
+        '_client_status',
+        '_user',
+        '_state',
+        '_avatar',
+    )
 
-    def __init__(self, *, data, guild, state):
-        self._state = state
-        self._user = state.store_user(data['user'])
-        self.guild = guild
-        self.joined_at = utils.parse_time(data.get('joined_at'))
-        self.premium_since = utils.parse_time(data.get('premium_since'))
-        self._update_roles(data)
-        self._client_status = {
-            None: 'offline'
-        }
-        self.activities = tuple(map(create_activity, data.get('activities', [])))
-        self.nick = data.get('nick', None)
-        self.pending = data.get('pending', False)
+    if TYPE_CHECKING:
+        name: str
+        id: int
+        discriminator: str
+        bot: bool
+        system: bool
+        created_at: datetime.datetime
+        default_avatar: Asset
+        avatar: Optional[Asset]
+        dm_channel: Optional[DMChannel]
+        create_dm = User.create_dm
+        mutual_guilds: List[Guild]
+        public_flags: PublicUserFlags
+        banner: Optional[Asset]
+        accent_color: Optional[Colour]
+        accent_colour: Optional[Colour]
 
-    def __str__(self):
+    def __init__(self, *, data: MemberWithUserPayload, guild: Guild, state: ConnectionState):
+        self._state: ConnectionState = state
+        self._user: User = state.store_user(data['user'])
+        self.guild: Guild = guild
+        self.joined_at: Optional[datetime.datetime] = utils.parse_time(data.get('joined_at'))
+        self.premium_since: Optional[datetime.datetime] = utils.parse_time(data.get('premium_since'))
+        self._roles: utils.SnowflakeList = utils.SnowflakeList(map(int, data['roles']))
+        self._client_status: Dict[Optional[str], str] = {None: 'offline'}
+        self.activities: Tuple[ActivityTypes, ...] = tuple()
+        self.nick: Optional[str] = data.get('nick', None)
+        self.pending: bool = data.get('pending', False)
+        self._avatar: Optional[str] = data.get('avatar')
+
+    def __str__(self) -> str:
         return str(self._user)
 
-    def __repr__(self):
-        return f'<Member id={self._user.id} name={self._user.name!r} discriminator={self._user.discriminator!r}' \
-               f' bot={self._user.bot} nick={self.nick!r} guild={self.guild!r}>'
+    def __int__(self) -> int:
+        return self.id
 
-    def __eq__(self, other):
-        return isinstance(other, _BaseUser) and other.id == self.id
+    def __repr__(self) -> str:
+        return (
+            f'<Member id={self._user.id} name={self._user.name!r} discriminator={self._user.discriminator!r}'
+            f' bot={self._user.bot} nick={self.nick!r} guild={self.guild!r}>'
+        )
 
-    def __ne__(self, other):
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, _UserTag) and other.id == self.id
+
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self._user)
 
     @classmethod
-    def _from_message(cls, *, message, data):
+    def _from_message(cls: Type[M], *, message: Message, data: MemberPayload) -> M:
         author = message.author
-        data['user'] = author._to_minimal_user_json()
-        return cls(data=data, guild=message.guild, state=message._state)
+        data['user'] = author._to_minimal_user_json()  # type: ignore
+        return cls(data=data, guild=message.guild, state=message._state)  # type: ignore
 
-    def _update_from_message(self, data):
+    def _update_from_message(self, data: MemberPayload) -> None:
         self.joined_at = utils.parse_time(data.get('joined_at'))
         self.premium_since = utils.parse_time(data.get('premium_since'))
-        self._update_roles(data)
+        self._roles = utils.SnowflakeList(map(int, data['roles']))
         self.nick = data.get('nick', None)
         self.pending = data.get('pending', False)
 
     @classmethod
-    def _try_upgrade(cls, *,  data, guild, state):
+    def _try_upgrade(cls: Type[M], *, data: UserWithMemberPayload, guild: Guild, state: ConnectionState) -> Union[User, M]:
         # A User object with a 'member' key
         try:
             member_data = data.pop('member')
         except KeyError:
-            return state.store_user(data)
+            return state.create_user(data)
         else:
-            member_data['user'] = data
-            return cls(data=member_data, guild=guild, state=state)
+            member_data['user'] = data  # type: ignore
+            return cls(data=member_data, guild=guild, state=state)  # type: ignore
 
     @classmethod
-    def _from_presence_update(cls, *, data, guild, state):
-        clone = cls(data=data, guild=guild, state=state)
-        to_return = cls(data=data, guild=guild, state=state)
-        to_return._client_status = {
-            sys.intern(key): sys.intern(value)
-            for key, value in data.get('client_status', {}).items()
-        }
-        to_return._client_status[None] = sys.intern(data['status'])
-        return to_return, clone
-
-    @classmethod
-    def _copy(cls, member):
-        self = cls.__new__(cls) # to bypass __init__
+    def _copy(cls: Type[M], member: M) -> M:
+        self: M = cls.__new__(cls)  # to bypass __init__
 
         self._roles = utils.SnowflakeList(member._roles, is_sorted=True)
         self.joined_at = member.joined_at
@@ -286,6 +359,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         self.pending = member.pending
         self.activities = member.activities
         self._state = member._state
+        self._avatar = member._avatar
 
         # Reference will not be copied unless necessary by PRESENCE_UPDATE
         # See below
@@ -296,10 +370,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         ch = await self.create_dm()
         return ch
 
-    def _update_roles(self, data):
-        self._roles = utils.SnowflakeList(map(int, data['roles']))
-
-    def _update(self, data):
+    def _update(self, data: MemberPayload) -> None:
         # the nickname change is optional,
         # if it isn't in the payload then it didn't change
         try:
@@ -313,38 +384,38 @@ class Member(discord.abc.Messageable, _BaseUser):
             pass
 
         self.premium_since = utils.parse_time(data.get('premium_since'))
-        self._update_roles(data)
+        self._roles = utils.SnowflakeList(map(int, data['roles']))
+        self._avatar = data.get('avatar')
 
-    def _presence_update(self, data, user):
-        self.activities = tuple(map(create_activity, data.get('activities', [])))
+    def _presence_update(self, data: PartialPresenceUpdate, user: UserPayload) -> Optional[Tuple[User, User]]:
+        self.activities = tuple(map(create_activity, data['activities']))
         self._client_status = {
-            sys.intern(key): sys.intern(value)
-            for key, value in data.get('client_status', {}).items()
+            sys.intern(key): sys.intern(value) for key, value in data.get('client_status', {}).items()  # type: ignore
         }
         self._client_status[None] = sys.intern(data['status'])
 
         if len(user) > 1:
             return self._update_inner_user(user)
-        return False
+        return None
 
-    def _update_inner_user(self, user):
+    def _update_inner_user(self, user: UserPayload) -> Optional[Tuple[User, User]]:
         u = self._user
-        original = (u.name, u.avatar, u.discriminator, u._public_flags)
+        original = (u.name, u._avatar, u.discriminator, u._public_flags)
         # These keys seem to always be available
         modified = (user['username'], user['avatar'], user['discriminator'], user.get('public_flags', 0))
         if original != modified:
             to_return = User._copy(self._user)
-            u.name, u.avatar, u.discriminator, u._public_flags = modified
+            u.name, u._avatar, u.discriminator, u._public_flags = modified
             # Signal to dispatch on_user_update
             return to_return, u
 
     @property
-    def status(self):
+    def status(self) -> Status:
         """:class:`Status`: The member's overall status. If the value is unknown, then it will be a :class:`str` instead."""
         return try_enum(Status, self._client_status[None])
 
     @property
-    def raw_status(self):
+    def raw_status(self) -> str:
         """:class:`str`: The member's overall status as a string value.
 
         .. versionadded:: 1.5
@@ -352,31 +423,31 @@ class Member(discord.abc.Messageable, _BaseUser):
         return self._client_status[None]
 
     @status.setter
-    def status(self, value):
+    def status(self, value: Status) -> None:
         # internal use only
         self._client_status[None] = str(value)
 
     @property
-    def mobile_status(self):
+    def mobile_status(self) -> Status:
         """:class:`Status`: The member's status on a mobile device, if applicable."""
         return try_enum(Status, self._client_status.get('mobile', 'offline'))
 
     @property
-    def desktop_status(self):
+    def desktop_status(self) -> Status:
         """:class:`Status`: The member's status on the desktop client, if applicable."""
         return try_enum(Status, self._client_status.get('desktop', 'offline'))
 
     @property
-    def web_status(self):
+    def web_status(self) -> Status:
         """:class:`Status`: The member's status on the web client, if applicable."""
         return try_enum(Status, self._client_status.get('web', 'offline'))
 
-    def is_on_mobile(self):
+    def is_on_mobile(self) -> bool:
         """:class:`bool`: A helper function that determines if a member is active on a mobile device."""
         return 'mobile' in self._client_status
 
     @property
-    def colour(self):
+    def colour(self) -> Colour:
         """:class:`Colour`: A property that returns a colour denoting the rendered colour
         for the member. If the default colour is the one rendered then an instance
         of :meth:`Colour.default` is returned.
@@ -384,7 +455,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         There is an alias for this named :attr:`color`.
         """
 
-        roles = self.roles[1:] # remove @everyone
+        roles = self.roles[1:]  # remove @everyone
 
         # highest order of the colour is the one that gets rendered.
         # if the highest is the default colour then the next one with a colour
@@ -395,7 +466,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         return Colour.default()
 
     @property
-    def color(self):
+    def color(self) -> Colour:
         """:class:`Colour`: A property that returns a color denoting the rendered color for
         the member. If the default color is the one rendered then an instance of :meth:`Colour.default`
         is returned.
@@ -405,7 +476,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         return self.colour
 
     @property
-    def roles(self):
+    def roles(self) -> List[Role]:
         """List[:class:`Role`]: A :class:`list` of :class:`Role` that the member belongs to. Note
         that the first element of this list is always the default '@everyone'
         role.
@@ -423,14 +494,14 @@ class Member(discord.abc.Messageable, _BaseUser):
         return result
 
     @property
-    def mention(self):
+    def mention(self) -> str:
         """:class:`str`: Returns a string that allows you to mention the member."""
         if self.nick:
             return f'<@!{self._user.id}>'
         return f'<@{self._user.id}>'
 
     @property
-    def display_name(self):
+    def display_name(self) -> str:
         """:class:`str`: Returns the user's display name.
 
         For regular users this is just their username, but
@@ -440,10 +511,39 @@ class Member(discord.abc.Messageable, _BaseUser):
         return self.nick or self.name
 
     @property
-    def activity(self):
-        """Union[:class:`BaseActivity`, :class:`Spotify`]: Returns the primary
+    def display_avatar(self) -> Asset:
+        """:class:`Asset`: Returns the member's display avatar.
+
+        For regular members this is just their avatar, but
+        if they have a guild specific avatar then that
+        is returned instead.
+
+        .. versionadded:: 2.0
+        """
+        return self.guild_avatar or self._user.avatar or self._user.default_avatar
+
+    @property
+    def guild_avatar(self) -> Optional[Asset]:
+        """Optional[:class:`Asset`]: Returns an :class:`Asset` for the guild avatar
+        the member has. If unavailable, ``None`` is returned.
+
+        .. versionadded:: 2.0
+        """
+        if self._avatar is None:
+            return None
+        return Asset._from_guild_avatar(self._state, self.guild.id, self.id, self._avatar)
+
+    @property
+    def activity(self) -> Optional[ActivityTypes]:
+        """Optional[Union[:class:`BaseActivity`, :class:`Spotify`]]: Returns the primary
         activity the user is currently doing. Could be ``None`` if no activity is being done.
 
+        .. note::
+
+            Due to a Discord API limitation, this may be ``None`` if
+            the user is listening to a song on Spotify with a title longer
+            than 128 characters. See :issue:`1738` for more information.
+
         .. note::
 
             A user may have multiple activities, these can be accessed under :attr:`activities`.
@@ -451,7 +551,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         if self.activities:
             return self.activities[0]
 
-    def mentioned_in(self, message):
+    def mentioned_in(self, message: Message) -> bool:
         """Checks if the member is mentioned in the specified message.
 
         Parameters
@@ -472,29 +572,8 @@ class Member(discord.abc.Messageable, _BaseUser):
 
         return any(self._roles.has(role.id) for role in message.role_mentions)
 
-    def permissions_in(self, channel):
-        """An alias for :meth:`abc.GuildChannel.permissions_for`.
-
-        Basically equivalent to:
-
-        .. code-block:: python3
-
-            channel.permissions_for(self)
-
-        Parameters
-        -----------
-        channel: :class:`abc.GuildChannel`
-            The channel to check your permissions for.
-
-        Returns
-        -------
-        :class:`Permissions`
-            The resolved permissions for the member.
-        """
-        return channel.permissions_for(self)
-
     @property
-    def top_role(self):
+    def top_role(self) -> Role:
         """:class:`Role`: Returns the member's highest role.
 
         This is useful for figuring where a member stands in the role
@@ -507,14 +586,13 @@ class Member(discord.abc.Messageable, _BaseUser):
         return max(guild.get_role(rid) or guild.default_role for rid in self._roles)
 
     @property
-    def guild_permissions(self):
+    def guild_permissions(self) -> Permissions:
         """:class:`Permissions`: Returns the member's guild permissions.
 
         This only takes into consideration the guild permissions
         and not most of the implied permissions or any of the
         channel permission overwrites. For 100% accurate permission
-        calculation, please use either :meth:`permissions_in` or
-        :meth:`abc.GuildChannel.permissions_for`.
+        calculation, please use :meth:`abc.GuildChannel.permissions_for`.
 
         This does take into consideration guild ownership and the
         administrator implication.
@@ -533,32 +611,47 @@ class Member(discord.abc.Messageable, _BaseUser):
         return base
 
     @property
-    def voice(self):
+    def voice(self) -> Optional[VoiceState]:
         """Optional[:class:`VoiceState`]: Returns the member's current voice state."""
         return self.guild._voice_state_for(self._user.id)
 
-    async def ban(self, **kwargs):
+    async def ban(
+        self,
+        *,
+        delete_message_days: Literal[0, 1, 2, 3, 4, 5, 6, 7] = 1,
+        reason: Optional[str] = None,
+    ) -> None:
         """|coro|
 
         Bans this member. Equivalent to :meth:`Guild.ban`.
         """
-        await self.guild.ban(self, **kwargs)
+        await self.guild.ban(self, reason=reason, delete_message_days=delete_message_days)
 
-    async def unban(self, *, reason=None):
+    async def unban(self, *, reason: Optional[str] = None) -> None:
         """|coro|
 
         Unbans this member. Equivalent to :meth:`Guild.unban`.
         """
         await self.guild.unban(self, reason=reason)
 
-    async def kick(self, *, reason=None):
+    async def kick(self, *, reason: Optional[str] = None) -> None:
         """|coro|
 
         Kicks this member. Equivalent to :meth:`Guild.kick`.
         """
         await self.guild.kick(self, reason=reason)
 
-    async def edit(self, *, reason=None, **fields):
+    async def edit(
+        self,
+        *,
+        nick: Optional[str] = MISSING,
+        mute: bool = MISSING,
+        deafen: bool = MISSING,
+        suppress: bool = MISSING,
+        roles: List[discord.abc.Snowflake] = MISSING,
+        voice_channel: Optional[VocalGuildChannel] = MISSING,
+        reason: Optional[str] = None,
+    ) -> Optional[Member]:
         """|coro|
 
         Edits the member's data.
@@ -584,6 +677,9 @@ class Member(discord.abc.Messageable, _BaseUser):
         .. versionchanged:: 1.1
             Can now pass ``None`` to ``voice_channel`` to kick a member from voice.
 
+        .. versionchanged:: 2.0
+            The newly member is now optionally returned, if applicable.
+
         Parameters
         -----------
         nick: Optional[:class:`str`]
@@ -597,7 +693,7 @@ class Member(discord.abc.Messageable, _BaseUser):
 
             .. versionadded:: 1.7
 
-        roles: Optional[List[:class:`Role`]]
+        roles: List[:class:`Role`]
             The member's new list of roles. This *replaces* the roles.
         voice_channel: Optional[:class:`VoiceChannel`]
             The voice channel to move the member to.
@@ -611,34 +707,32 @@ class Member(discord.abc.Messageable, _BaseUser):
             You do not have the proper permissions to the action requested.
         HTTPException
             The operation failed.
+
+        Returns
+        --------
+        Optional[:class:`.Member`]
+            The newly updated member, if applicable. This is only returned
+            when certain fields are updated.
         """
         http = self._state.http
         guild_id = self.guild.id
         me = self._state.self_id == self.id
-        payload = {}
+        payload: Dict[str, Any] = {}
 
-        try:
-            nick = fields['nick']
-        except KeyError:
-            # nick not present so...
-            pass
-        else:
+        if nick is not MISSING:
             nick = nick or ''
             if me:
                 await http.change_my_nickname(guild_id, nick, reason=reason)
             else:
                 payload['nick'] = nick
 
-        deafen = fields.get('deafen')
-        if deafen is not None:
+        if deafen is not MISSING:
             payload['deaf'] = deafen
 
-        mute = fields.get('mute')
-        if mute is not None:
+        if mute is not MISSING:
             payload['mute'] = mute
 
-        suppress = fields.get('suppress')
-        if suppress is not None:
+        if suppress is not MISSING:
             voice_state_payload = {
                 'channel_id': self.voice.channel.id,
                 'suppress': suppress,
@@ -654,26 +748,17 @@ class Member(discord.abc.Messageable, _BaseUser):
                     voice_state_payload['request_to_speak_timestamp'] = datetime.datetime.utcnow().isoformat()
                 await http.edit_voice_state(guild_id, self.id, voice_state_payload)
 
-        try:
-            vc = fields['voice_channel']
-        except KeyError:
-            pass
-        else:
-            payload['channel_id'] = vc and vc.id
+        if voice_channel is not MISSING:
+            payload['channel_id'] = voice_channel and voice_channel.id
 
-        try:
-            roles = fields['roles']
-        except KeyError:
-            pass
-        else:
+        if roles is not MISSING:
             payload['roles'] = tuple(r.id for r in roles)
 
         if payload:
-            await http.edit_member(guild_id, self.id, reason=reason, **payload)
+            data = await http.edit_member(guild_id, self.id, reason=reason, **payload)
+            return Member(data=data, guild=self.guild, state=self._state)
 
-        # TODO: wait for WS event for modify-in-place behaviour
-
-    async def request_to_speak(self):
+    async def request_to_speak(self) -> None:
         """|coro|
 
         Request to speak in the connected channel.
@@ -705,7 +790,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         else:
             await self._state.http.edit_my_voice_state(self.guild.id, payload)
 
-    async def move_to(self, channel, *, reason=None):
+    async def move_to(self, channel: VocalGuildChannel, *, reason: Optional[str] = None) -> None:
         """|coro|
 
         Moves a member to a new voice channel (they must be connected first).
@@ -728,7 +813,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         """
         await self.edit(voice_channel=channel, reason=reason)
 
-    async def add_roles(self, *roles, reason=None, atomic=True):
+    async def add_roles(self, *roles: Snowflake, reason: Optional[str] = None, atomic: bool = True) -> None:
         r"""|coro|
 
         Gives the member a number of :class:`Role`\s.
@@ -767,7 +852,7 @@ class Member(discord.abc.Messageable, _BaseUser):
             for role in roles:
                 await req(guild_id, user_id, role.id, reason=reason)
 
-    async def remove_roles(self, *roles, reason=None, atomic=True):
+    async def remove_roles(self, *roles: Snowflake, reason: Optional[str] = None, atomic: bool = True) -> None:
         r"""|coro|
 
         Removes :class:`Role`\s from this member.
@@ -797,7 +882,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         """
 
         if not atomic:
-            new_roles = [Object(id=r.id) for r in self.roles[1:]] # remove @everyone
+            new_roles = [Object(id=r.id) for r in self.roles[1:]]  # remove @everyone
             for role in roles:
                 try:
                     new_roles.remove(Object(id=role.id))
@@ -811,3 +896,20 @@ class Member(discord.abc.Messageable, _BaseUser):
             user_id = self.id
             for role in roles:
                 await req(guild_id, user_id, role.id, reason=reason)
+
+    def get_role(self, role_id: int, /) -> Optional[Role]:
+        """Returns a role with the given ID from roles which the member has.
+
+        .. versionadded:: 2.0
+
+        Parameters
+        -----------
+        role_id: :class:`int`
+            The ID to search for.
+
+        Returns
+        --------
+        Optional[:class:`Role`]
+            The role or ``None`` if not found in the member's roles.
+        """
+        return self.guild.get_role(role_id) if self._roles.has(role_id) else None

discord/mentions.py

@@ -22,10 +22,18 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+from typing import Type, TypeVar, Union, List, TYPE_CHECKING, Any, Union
+
 __all__ = (
     'AllowedMentions',
 )
 
+if TYPE_CHECKING:
+    from .types.message import AllowedMentions as AllowedMentionsPayload
+    from .abc import Snowflake
+
+
 class _FakeBool:
     def __repr__(self):
         return 'True'
@@ -36,7 +44,11 @@ class _FakeBool:
     def __bool__(self):
         return True
 
-default = _FakeBool()
+
+default: Any = _FakeBool()
+
+A = TypeVar('A', bound='AllowedMentions')
+
 
 class AllowedMentions:
     """A class that represents what mentions are allowed in a message.
@@ -70,14 +82,21 @@ class AllowedMentions:
 
     __slots__ = ('everyone', 'users', 'roles', 'replied_user')
 
-    def __init__(self, *, everyone=default, users=default, roles=default, replied_user=default):
+    def __init__(
+        self,
+        *,
+        everyone: bool = default,
+        users: Union[bool, List[Snowflake]] = default,
+        roles: Union[bool, List[Snowflake]] = default,
+        replied_user: bool = default,
+    ):
         self.everyone = everyone
         self.users = users
         self.roles = roles
         self.replied_user = replied_user
 
     @classmethod
-    def all(cls):
+    def all(cls: Type[A]) -> A:
         """A factory method that returns a :class:`AllowedMentions` with all fields explicitly set to ``True``
 
         .. versionadded:: 1.5
@@ -85,14 +104,14 @@ class AllowedMentions:
         return cls(everyone=True, users=True, roles=True, replied_user=True)
 
     @classmethod
-    def none(cls):
+    def none(cls: Type[A]) -> A:
         """A factory method that returns a :class:`AllowedMentions` with all fields set to ``False``
 
         .. versionadded:: 1.5
         """
         return cls(everyone=False, users=False, roles=False, replied_user=False)
 
-    def to_dict(self):
+    def to_dict(self) -> AllowedMentionsPayload:
         parse = []
         data = {}
 
@@ -113,9 +132,9 @@ class AllowedMentions:
             data['replied_user'] = True
 
         data['parse'] = parse
-        return data
+        return data  # type: ignore
 
-    def merge(self, other):
+    def merge(self, other: AllowedMentions) -> AllowedMentions:
         # Creates a new AllowedMentions by merging from another one.
         # Merge is done by using the 'self' values unless explicitly
         # overridden by the 'other' values.
@@ -125,5 +144,8 @@ class AllowedMentions:
         replied_user = self.replied_user if other.replied_user is default else other.replied_user
         return AllowedMentions(everyone=everyone, roles=roles, users=users, replied_user=replied_user)
 
-    def __repr__(self):
-        return '{0.__class__.__qualname__}(everyone={0.everyone}, users={0.users}, roles={0.roles}, replied_user={0.replied_user})'.format(self)
+    def __repr__(self) -> str:
+        return (
+            f'{self.__class__.__name__}(everyone={self.everyone}, '
+            f'users={self.users}, roles={self.roles}, replied_user={self.replied_user})'
+        )

discord/mixins.py

@@ -30,10 +30,12 @@ __all__ = (
 class EqualityComparable:
     __slots__ = ()
 
-    def __eq__(self, other):
+    id: int
+
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, self.__class__) and other.id == self.id
 
-    def __ne__(self, other):
+    def __ne__(self, other: object) -> bool:
         if isinstance(other, self.__class__):
             return other.id != self.id
         return True
@@ -41,5 +43,8 @@ class EqualityComparable:
 class Hashable(EqualityComparable):
     __slots__ = ()
 
-    def __hash__(self):
+    def __int__(self) -> int:
+        return self.id
+
+    def __hash__(self) -> int:
         return self.id >> 22

discord/object.py

@@ -22,9 +22,21 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 from . import utils
 from .mixins import Hashable
 
+from typing import (
+    SupportsInt,
+    TYPE_CHECKING,
+    Union,
+)
+
+if TYPE_CHECKING:
+    import datetime
+    SupportsIntCast = Union[SupportsInt, str, bytes, bytearray]
+
 __all__ = (
     'Object',
 )
@@ -57,13 +69,17 @@ class Object(Hashable):
 
             Returns the object's hash.
 
+        .. describe:: int(x)
+
+            Returns the object's ID.
+
     Attributes
     -----------
     id: :class:`int`
         The ID of the object.
     """
 
-    def __init__(self, id):
+    def __init__(self, id: SupportsIntCast):
         try:
             id = int(id)
         except ValueError:
@@ -71,10 +87,10 @@ class Object(Hashable):
         else:
             self.id = id
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f'<Object id={self.id!r}>'
 
     @property
-    def created_at(self):
+    def created_at(self) -> datetime.datetime:
         """:class:`datetime.datetime`: Returns the snowflake's creation time in UTC."""
         return utils.snowflake_time(self.id)

discord/oggparse.py

@@ -22,8 +22,12 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 import struct
 
+from typing import TYPE_CHECKING, ClassVar, IO, Generator, Tuple, Optional
+
 from .errors import DiscordException
 
 __all__ = (
@@ -40,22 +44,29 @@ class OggError(DiscordException):
 # https://tools.ietf.org/html/rfc7845
 
 class OggPage:
-    _header = struct.Struct('<xBQIIIB')
+    _header: ClassVar[struct.Struct] = struct.Struct('<xBQIIIB')
+    if TYPE_CHECKING:
+        flag: int
+        gran_pos: int
+        serial: int
+        pagenum: int
+        crc: int
+        segnum: int
 
-    def __init__(self, stream):
+    def __init__(self, stream: IO[bytes]) -> None:
         try:
             header = stream.read(struct.calcsize(self._header.format))
 
             self.flag, self.gran_pos, self.serial, \
             self.pagenum, self.crc, self.segnum = self._header.unpack(header)
 
-            self.segtable = stream.read(self.segnum)
+            self.segtable: bytes = stream.read(self.segnum)
             bodylen = sum(struct.unpack('B'*self.segnum, self.segtable))
-            self.data = stream.read(bodylen)
+            self.data: bytes = stream.read(bodylen)
         except Exception:
             raise OggError('bad data stream') from None
 
-    def iter_packets(self):
+    def iter_packets(self) -> Generator[Tuple[bytes, bool], None, None]:
         packetlen = offset = 0
         partial = True
 
@@ -74,10 +85,10 @@ class OggPage:
             yield self.data[offset:], False
 
 class OggStream:
-    def __init__(self, stream):
-        self.stream = stream
+    def __init__(self, stream: IO[bytes]) -> None:
+        self.stream: IO[bytes] = stream
 
-    def _next_page(self):
+    def _next_page(self) -> Optional[OggPage]:
         head = self.stream.read(4)
         if head == b'OggS':
             return OggPage(self.stream)
@@ -86,13 +97,13 @@ class OggStream:
         else:
             raise OggError('invalid header magic')
 
-    def _iter_pages(self):
+    def _iter_pages(self) -> Generator[OggPage, None, None]:
         page = self._next_page()
         while page:
             yield page
             page = self._next_page()
 
-    def iter_packets(self):
+    def iter_packets(self) -> Generator[bytes, None, None]:
         partial = b''
         for page in self._iter_pages():
             for data, complete in page.iter_packets():

discord/opus.py

@@ -22,6 +22,10 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import List, Tuple, TypedDict, Any, TYPE_CHECKING, Callable, TypeVar, Literal, Optional, overload
+
 import array
 import ctypes
 import ctypes.util
@@ -31,7 +35,24 @@ import os.path
 import struct
 import sys
 
-from .errors import DiscordException
+from .errors import DiscordException, InvalidArgument
+
+if TYPE_CHECKING:
+    T = TypeVar('T')
+    BAND_CTL = Literal['narrow', 'medium', 'wide', 'superwide', 'full']
+    SIGNAL_CTL = Literal['auto', 'voice', 'music']
+
+class BandCtl(TypedDict):
+    narrow: int
+    medium: int
+    wide: int
+    superwide: int
+    full: int
+
+class SignalCtl(TypedDict):
+    auto: int
+    voice: int
+    music: int
 
 __all__ = (
     'Encoder',
@@ -39,7 +60,7 @@ __all__ = (
     'OpusNotLoaded',
 )
 
-log = logging.getLogger(__name__)
+_log = logging.getLogger(__name__)
 
 c_int_ptr   = ctypes.POINTER(ctypes.c_int)
 c_int16_ptr = ctypes.POINTER(ctypes.c_int16)
@@ -76,7 +97,7 @@ CTL_SET_SIGNAL       = 4024
 CTL_SET_GAIN             = 4034
 CTL_LAST_PACKET_DURATION = 4039
 
-band_ctl = {
+band_ctl: BandCtl = {
     'narrow': 1101,
     'medium': 1102,
     'wide': 1103,
@@ -84,22 +105,22 @@ band_ctl = {
     'full': 1105,
 }
 
-signal_ctl = {
+signal_ctl: SignalCtl = {
     'auto': -1000,
     'voice': 3001,
     'music': 3002,
 }
 
-def _err_lt(result, func, args):
+def _err_lt(result: int, func: Callable, args: List) -> int:
     if result < OK:
-        log.info('error has happened in %s', func.__name__)
+        _log.info('error has happened in %s', func.__name__)
         raise OpusError(result)
     return result
 
-def _err_ne(result, func, args):
+def _err_ne(result: T, func: Callable, args: List) -> T:
     ret = args[-1]._obj
     if ret.value != OK:
-        log.info('error has happened in %s', func.__name__)
+        _log.info('error has happened in %s', func.__name__)
         raise OpusError(ret.value)
     return result
 
@@ -108,7 +129,7 @@ def _err_ne(result, func, args):
 # The second one are the types of arguments it takes.
 # The third is the result type.
 # The fourth is the error handler.
-exported_functions = [
+exported_functions: List[Tuple[Any, ...]] = [
     # Generic
     ('opus_get_version_string',
         None, ctypes.c_char_p, None),
@@ -158,7 +179,7 @@ exported_functions = [
         [ctypes.c_char_p, ctypes.c_int], ctypes.c_int, _err_lt),
 ]
 
-def libopus_loader(name):
+def libopus_loader(name: str) -> Any:
     # create the library...
     lib = ctypes.cdll.LoadLibrary(name)
 
@@ -178,11 +199,11 @@ def libopus_loader(name):
             if item[3]:
                 func.errcheck = item[3]
         except KeyError:
-            log.exception("Error assigning check function to %s", func)
+            _log.exception("Error assigning check function to %s", func)
 
     return lib
 
-def _load_default():
+def _load_default() -> bool:
     global _lib
     try:
         if sys.platform == 'win32':
@@ -198,7 +219,7 @@ def _load_default():
 
     return _lib is not None
 
-def load_opus(name):
+def load_opus(name: str) -> None:
     """Loads the libopus shared library for use with voice.
 
     If this function is not called then the library uses the function
@@ -236,7 +257,7 @@ def load_opus(name):
     global _lib
     _lib = libopus_loader(name)
 
-def is_loaded():
+def is_loaded() -> bool:
     """Function to check if opus lib is successfully loaded either
     via the :func:`ctypes.util.find_library` call of :func:`load_opus`.
 
@@ -259,10 +280,10 @@ class OpusError(DiscordException):
         The error code returned.
     """
 
-    def __init__(self, code):
-        self.code = code
+    def __init__(self, code: int):
+        self.code: int = code
         msg = _lib.opus_strerror(self.code).decode('utf-8')
-        log.info('"%s" has happened', msg)
+        _log.info('"%s" has happened', msg)
         super().__init__(msg)
 
 class OpusNotLoaded(DiscordException):
@@ -286,92 +307,96 @@ class _OpusStruct:
         return _lib.opus_get_version_string().decode('utf-8')
 
 class Encoder(_OpusStruct):
-    def __init__(self, application=APPLICATION_AUDIO):
+    def __init__(self, application: int = APPLICATION_AUDIO):
         _OpusStruct.get_opus_version()
 
-        self.application = application
-        self._state = self._create_state()
+        self.application: int = application
+        self._state: EncoderStruct = self._create_state()
         self.set_bitrate(128)
         self.set_fec(True)
         self.set_expected_packet_loss_percent(0.15)
         self.set_bandwidth('full')
         self.set_signal_type('auto')
 
-    def __del__(self):
+    def __del__(self) -> None:
         if hasattr(self, '_state'):
             _lib.opus_encoder_destroy(self._state)
-            self._state = None
+            # This is a destructor, so it's okay to assign None
+            self._state = None # type: ignore
 
-    def _create_state(self):
+    def _create_state(self) -> EncoderStruct:
         ret = ctypes.c_int()
         return _lib.opus_encoder_create(self.SAMPLING_RATE, self.CHANNELS, self.application, ctypes.byref(ret))
 
-    def set_bitrate(self, kbps):
+    def set_bitrate(self, kbps: int) -> int:
         kbps = min(512, max(16, int(kbps)))
 
         _lib.opus_encoder_ctl(self._state, CTL_SET_BITRATE, kbps * 1024)
         return kbps
 
-    def set_bandwidth(self, req):
+    def set_bandwidth(self, req: BAND_CTL) -> None:
         if req not in band_ctl:
             raise KeyError(f'{req!r} is not a valid bandwidth setting. Try one of: {",".join(band_ctl)}')
 
         k = band_ctl[req]
         _lib.opus_encoder_ctl(self._state, CTL_SET_BANDWIDTH, k)
 
-    def set_signal_type(self, req):
+    def set_signal_type(self, req: SIGNAL_CTL) -> None:
         if req not in signal_ctl:
             raise KeyError(f'{req!r} is not a valid bandwidth setting. Try one of: {",".join(signal_ctl)}')
 
         k = signal_ctl[req]
         _lib.opus_encoder_ctl(self._state, CTL_SET_SIGNAL, k)
 
-    def set_fec(self, enabled=True):
+    def set_fec(self, enabled: bool = True) -> None:
         _lib.opus_encoder_ctl(self._state, CTL_SET_FEC, 1 if enabled else 0)
 
-    def set_expected_packet_loss_percent(self, percentage):
-        _lib.opus_encoder_ctl(self._state, CTL_SET_PLP, min(100, max(0, int(percentage * 100))))
+    def set_expected_packet_loss_percent(self, percentage: float) -> None:
+        _lib.opus_encoder_ctl(self._state, CTL_SET_PLP, min(100, max(0, int(percentage * 100)))) # type: ignore
 
-    def encode(self, pcm, frame_size):
+    def encode(self, pcm: bytes, frame_size: int) -> bytes:
         max_data_bytes = len(pcm)
-        pcm = ctypes.cast(pcm, c_int16_ptr)
+        # bytes can be used to reference pointer
+        pcm_ptr = ctypes.cast(pcm, c_int16_ptr) # type: ignore
         data = (ctypes.c_char * max_data_bytes)()
 
-        ret = _lib.opus_encode(self._state, pcm, frame_size, data, max_data_bytes)
+        ret = _lib.opus_encode(self._state, pcm_ptr, frame_size, data, max_data_bytes)
 
-        return array.array('b', data[:ret]).tobytes()
+        # array can be initialized with bytes but mypy doesn't know
+        return array.array('b', data[:ret]).tobytes() # type: ignore
 
 class Decoder(_OpusStruct):
     def __init__(self):
         _OpusStruct.get_opus_version()
 
-        self._state = self._create_state()
+        self._state: DecoderStruct = self._create_state()
 
-    def __del__(self):
+    def __del__(self) -> None:
         if hasattr(self, '_state'):
             _lib.opus_decoder_destroy(self._state)
-            self._state = None
+            # This is a destructor, so it's okay to assign None
+            self._state = None # type: ignore
 
-    def _create_state(self):
+    def _create_state(self) -> DecoderStruct:
         ret = ctypes.c_int()
         return _lib.opus_decoder_create(self.SAMPLING_RATE, self.CHANNELS, ctypes.byref(ret))
 
     @staticmethod
-    def packet_get_nb_frames(data):
+    def packet_get_nb_frames(data: bytes) -> int:
         """Gets the number of frames in an Opus packet"""
         return _lib.opus_packet_get_nb_frames(data, len(data))
 
     @staticmethod
-    def packet_get_nb_channels(data):
+    def packet_get_nb_channels(data: bytes) -> int:
         """Gets the number of channels in an Opus packet"""
         return _lib.opus_packet_get_nb_channels(data)
 
     @classmethod
-    def packet_get_samples_per_frame(cls, data):
+    def packet_get_samples_per_frame(cls, data: bytes) -> int:
         """Gets the number of samples per frame from an Opus packet"""
         return _lib.opus_packet_get_samples_per_frame(data, cls.SAMPLING_RATE)
 
-    def _set_gain(self, adjustment):
+    def _set_gain(self, adjustment: int) -> int:
         """Configures decoder gain adjustment.
 
         Scales the decoded output by a factor specified in Q8 dB units.
@@ -383,26 +408,34 @@ class Decoder(_OpusStruct):
         """
         return _lib.opus_decoder_ctl(self._state, CTL_SET_GAIN, adjustment)
 
-    def set_gain(self, dB):
+    def set_gain(self, dB: float) -> int:
         """Sets the decoder gain in dB, from -128 to 128."""
 
         dB_Q8 = max(-32768, min(32767, round(dB * 256))) # dB * 2^n where n is 8 (Q8)
         return self._set_gain(dB_Q8)
 
-    def set_volume(self, mult):
+    def set_volume(self, mult: float) -> int:
         """Sets the output volume as a float percent, i.e. 0.5 for 50%, 1.75 for 175%, etc."""
         return self.set_gain(20 * math.log10(mult)) # amplitude ratio
 
-    def _get_last_packet_duration(self):
+    def _get_last_packet_duration(self) -> int:
         """Gets the duration (in samples) of the last packet successfully decoded or concealed."""
 
         ret = ctypes.c_int32()
         _lib.opus_decoder_ctl(self._state, CTL_LAST_PACKET_DURATION, ctypes.byref(ret))
         return ret.value
 
-    def decode(self, data, *, fec=False):
+    @overload
+    def decode(self, data: bytes, *, fec: bool) -> bytes:
+        ...
+    
+    @overload
+    def decode(self, data: Literal[None], *, fec: Literal[False]) -> bytes:
+        ...
+
+    def decode(self, data: Optional[bytes], *, fec: bool = False) -> bytes:
         if data is None and fec:
-            raise OpusError("Invalid arguments: FEC cannot be used with null data")
+            raise InvalidArgument("Invalid arguments: FEC cannot be used with null data")
 
         if data is None:
             frame_size = self._get_last_packet_duration() or self.SAMPLES_PER_FRAME

discord/partial_emoji.py

@@ -22,17 +22,37 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
-from .asset import Asset
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, TYPE_CHECKING, Type, TypeVar, Union
+import re
+
+from .asset import Asset, AssetMixin
+from .errors import InvalidArgument
 from . import utils
 
 __all__ = (
     'PartialEmoji',
 )
 
+if TYPE_CHECKING:
+    from .state import ConnectionState
+    from datetime import datetime
+    from .types.message import PartialEmoji as PartialEmojiPayload
+
 class _EmojiTag:
     __slots__ = ()
 
-class PartialEmoji(_EmojiTag):
+    id: int
+
+    def _to_partial(self) -> PartialEmoji:
+        raise NotImplementedError
+
+
+PE = TypeVar('PE', bound='PartialEmoji')
+
+
+class PartialEmoji(_EmojiTag, AssetMixin):
     """Represents a "partial" emoji.
 
     This model will be given in two scenarios:
@@ -72,35 +92,80 @@ class PartialEmoji(_EmojiTag):
 
     __slots__ = ('animated', 'name', 'id', '_state')
 
-    def __init__(self, *, name, animated=False, id=None):
+    _CUSTOM_EMOJI_RE = re.compile(r'<?(?P<animated>a)?:?(?P<name>[A-Za-z0-9\_]+):(?P<id>[0-9]{13,20})>?')
+
+    if TYPE_CHECKING:
+        id: Optional[int]
+
+    def __init__(self, *, name: str, animated: bool = False, id: Optional[int] = None):
         self.animated = animated
         self.name = name
         self.id = id
-        self._state = None
+        self._state: Optional[ConnectionState] = None
 
     @classmethod
-    def from_dict(cls, data):
+    def from_dict(cls: Type[PE], data: Union[PartialEmojiPayload, Dict[str, Any]]) -> PE:
         return cls(
             animated=data.get('animated', False),
             id=utils._get_as_snowflake(data, 'id'),
-            name=data.get('name'),
+            name=data.get('name') or '',
         )
 
-    def to_dict(self):
-        o = { 'name': self.name }
+    @classmethod
+    def from_str(cls: Type[PE], value: str) -> PE:
+        """Converts a Discord string representation of an emoji to a :class:`PartialEmoji`.
+
+        The formats accepted are:
+
+        - ``a:name:id``
+        - ``<a:name:id>``
+        - ``name:id``
+        - ``<:name:id>``
+
+        If the format does not match then it is assumed to be a unicode emoji.
+
+        .. versionadded:: 2.0
+
+        Parameters
+        ------------
+        value: :class:`str`
+            The string representation of an emoji.
+
+        Returns
+        --------
+        :class:`PartialEmoji`
+            The partial emoji from this string.
+        """
+        match = cls._CUSTOM_EMOJI_RE.match(value)
+        if match is not None:
+            groups = match.groupdict()
+            animated = bool(groups['animated'])
+            emoji_id = int(groups['id'])
+            name = groups['name']
+            return cls(name=name, animated=animated, id=emoji_id)
+
+        return cls(name=value, id=None, animated=False)
+
+    def to_dict(self) -> Dict[str, Any]:
+        o: Dict[str, Any] = {'name': self.name}
         if self.id:
             o['id'] = self.id
         if self.animated:
             o['animated'] = self.animated
         return o
 
+    def _to_partial(self) -> PartialEmoji:
+        return self
+
     @classmethod
-    def with_state(cls, state, *, name, animated=False, id=None):
+    def with_state(
+        cls: Type[PE], state: ConnectionState, *, name: str, animated: bool = False, id: Optional[int] = None
+    ) -> PE:
         self = cls(name=name, animated=animated, id=id)
         self._state = state
         return self
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.id is None:
             return self.name
         if self.animated:
@@ -108,9 +173,9 @@ class PartialEmoji(_EmojiTag):
         return f'<:{self.name}:{self.id}>'
 
     def __repr__(self):
-        return '<{0.__class__.__name__} animated={0.animated} name={0.name!r} id={0.id}>'.format(self)
+        return f'<{self.__class__.__name__} animated={self.animated} name={self.name!r} id={self.id}>'
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         if self.is_unicode_emoji():
             return isinstance(other, PartialEmoji) and self.name == other.name
 
@@ -118,75 +183,50 @@ class PartialEmoji(_EmojiTag):
             return self.id == other.id
         return False
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash((self.id, self.name))
 
-    def is_custom_emoji(self):
+    def is_custom_emoji(self) -> bool:
         """:class:`bool`: Checks if this is a custom non-Unicode emoji."""
         return self.id is not None
 
-    def is_unicode_emoji(self):
+    def is_unicode_emoji(self) -> bool:
         """:class:`bool`: Checks if this is a Unicode emoji."""
         return self.id is None
 
-    def _as_reaction(self):
+    def _as_reaction(self) -> str:
         if self.id is None:
             return self.name
         return f'{self.name}:{self.id}'
 
     @property
-    def created_at(self):
+    def created_at(self) -> Optional[datetime]:
         """Optional[:class:`datetime.datetime`]: Returns the emoji's creation time in UTC, or None if Unicode emoji.
 
         .. versionadded:: 1.6
         """
-        if self.is_unicode_emoji():
+        if self.id is None:
             return None
 
         return utils.snowflake_time(self.id)
 
     @property
-    def url(self):
-        """:class:`Asset`: Returns the asset of the emoji, if it is custom.
+    def url(self) -> str:
+        """:class:`str`: Returns the URL of the emoji, if it is custom.
 
-        This is equivalent to calling :meth:`url_as` with
-        the default parameters (i.e. png/gif detection).
-        """
-        return self.url_as(format=None)
-
-    def url_as(self, *, format=None, static_format="png"):
-        """Returns an :class:`Asset` for the emoji's url, if it is custom.
-
-        The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif'.
-        'gif' is only valid for animated emojis.
-
-        .. versionadded:: 1.7
-
-        Parameters
-        -----------
-        format: Optional[:class:`str`]
-            The format to attempt to convert the emojis to.
-            If the format is ``None``, then it is automatically
-            detected as either 'gif' or static_format, depending on whether the
-            emoji is animated or not.
-        static_format: Optional[:class:`str`]
-            Format to attempt to convert only non-animated emoji's to.
-            Defaults to 'png'
-
-        Raises
-        -------
-        InvalidArgument
-            Bad image format passed to ``format`` or ``static_format``.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
+        If this isn't a custom emoji then an empty string is returned
         """
         if self.is_unicode_emoji():
-            return Asset(self._state)
+            return ''
 
-        return Asset._from_emoji(self._state, self, format=format, static_format=static_format)
+        fmt = 'gif' if self.animated else 'png'
+        return f'{Asset.BASE}/emojis/{self.id}.{fmt}'
+
+    async def read(self) -> bytes:
+        if self.is_unicode_emoji():
+            raise InvalidArgument('PartialEmoji is not a custom emoji')
+
+        return await super().read()

discord/permissions.py

@@ -22,6 +22,9 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import Callable, Any, ClassVar, Dict, Iterator, Set, TYPE_CHECKING, Tuple, Type, TypeVar, Optional
 from .flags import BaseFlags, flag_value, fill_with_flags, alias_flag_value
 
 __all__ = (
@@ -32,15 +35,19 @@ __all__ = (
 # A permission alias works like a regular flag but is marked
 # So the PermissionOverwrite knows to work with it
 class permission_alias(alias_flag_value):
-    pass
+    alias: str
 
-def make_permission_alias(alias):
-    def decorator(func):
+
+def make_permission_alias(alias: str) -> Callable[[Callable[[Any], int]], permission_alias]:
+    def decorator(func: Callable[[Any], int]) -> permission_alias:
         ret = permission_alias(func)
         ret.alias = alias
         return ret
+
     return decorator
 
+P = TypeVar('P', bound='Permissions')
+
 @fill_with_flags()
 class Permissions(BaseFlags):
     """Wraps up the Discord permission value.
@@ -92,7 +99,7 @@ class Permissions(BaseFlags):
 
     __slots__ = ()
 
-    def __init__(self, permissions=0, **kwargs):
+    def __init__(self, permissions: int = 0, **kwargs: bool):
         if not isinstance(permissions, int):
             raise TypeError(f'Expected int parameter, received {permissions.__class__.__name__} instead.')
 
@@ -102,25 +109,25 @@ class Permissions(BaseFlags):
                 raise TypeError(f'{key!r} is not a valid permission name.')
             setattr(self, key, value)
 
-    def is_subset(self, other):
+    def is_subset(self, other: Permissions) -> bool:
         """Returns ``True`` if self has the same or fewer permissions as other."""
         if isinstance(other, Permissions):
             return (self.value & other.value) == self.value
         else:
             raise TypeError(f"cannot compare {self.__class__.__name__} with {other.__class__.__name__}")
 
-    def is_superset(self, other):
+    def is_superset(self, other: Permissions) -> bool:
         """Returns ``True`` if self has the same or more permissions as other."""
         if isinstance(other, Permissions):
             return (self.value | other.value) == self.value
         else:
             raise TypeError(f"cannot compare {self.__class__.__name__} with {other.__class__.__name__}")
 
-    def is_strict_subset(self, other):
+    def is_strict_subset(self, other: Permissions) -> bool:
         """Returns ``True`` if the permissions on other are a strict subset of those on self."""
         return self.is_subset(other) and self != other
 
-    def is_strict_superset(self, other):
+    def is_strict_superset(self, other: Permissions) -> bool:
         """Returns ``True`` if the permissions on other are a strict superset of those on self."""
         return self.is_superset(other) and self != other
 
@@ -130,20 +137,20 @@ class Permissions(BaseFlags):
     __gt__ = is_strict_superset
 
     @classmethod
-    def none(cls):
+    def none(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         permissions set to ``False``."""
         return cls(0)
 
     @classmethod
-    def all(cls):
+    def all(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         permissions set to ``True``.
         """
-        return cls(0b111111111111111111111111111111111)
+        return cls(0b111111111111111111111111111111111111111)
 
     @classmethod
-    def all_channel(cls):
+    def all_channel(cls: Type[P]) -> P:
         """A :class:`Permissions` with all channel-specific permissions set to
         ``True`` and the guild-specific ones set to ``False``. The guild-specific
         permissions are currently:
@@ -160,11 +167,16 @@ class Permissions(BaseFlags):
 
         .. versionchanged:: 1.7
            Added :attr:`stream`, :attr:`priority_speaker` and :attr:`use_slash_commands` permissions.
+
+        .. versionchanged:: 2.0
+           Added :attr:`create_public_threads`, :attr:`create_private_threads`, :attr:`manage_threads`,
+           :attr:`use_external_stickers`, :attr:`send_messages_in_threads` and
+           :attr:`request_to_speak` permissions.
         """
-        return cls(0b10110011111101111111111101010001)
+        return cls(0b111110110110011111101111111111101010001)
 
     @classmethod
-    def general(cls):
+    def general(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "General" permissions from the official Discord UI set to ``True``.
 
@@ -177,7 +189,7 @@ class Permissions(BaseFlags):
         return cls(0b01110000000010000000010010110000)
 
     @classmethod
-    def membership(cls):
+    def membership(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "Membership" permissions from the official Discord UI set to ``True``.
 
@@ -186,24 +198,28 @@ class Permissions(BaseFlags):
         return cls(0b00001100000000000000000000000111)
 
     @classmethod
-    def text(cls):
+    def text(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "Text" permissions from the official Discord UI set to ``True``.
 
         .. versionchanged:: 1.7
            Permission :attr:`read_messages` is no longer part of the text permissions.
            Added :attr:`use_slash_commands` permission.
+
+        .. versionchanged:: 2.0
+           Added :attr:`create_public_threads`, :attr:`create_private_threads`, :attr:`manage_threads`,
+           :attr:`send_messages_in_threads` and :attr:`use_external_stickers` permissions.
         """
-        return cls(0b10000000000001111111100001000000)
+        return cls(0b111110010000000000001111111100001000000)
 
     @classmethod
-    def voice(cls):
+    def voice(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "Voice" permissions from the official Discord UI set to ``True``."""
         return cls(0b00000011111100000000001100000000)
 
     @classmethod
-    def stage(cls):
+    def stage(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "Stage Channel" permissions from the official Discord UI set to ``True``.
 
@@ -212,7 +228,7 @@ class Permissions(BaseFlags):
         return cls(1 << 32)
 
     @classmethod
-    def stage_moderator(cls):
+    def stage_moderator(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "Stage Moderator" permissions from the official Discord UI set to ``True``.
 
@@ -221,7 +237,7 @@ class Permissions(BaseFlags):
         return cls(0b100000001010000000000000000000000)
 
     @classmethod
-    def advanced(cls):
+    def advanced(cls: Type[P]) -> P:
         """A factory method that creates a :class:`Permissions` with all
         "Advanced" permissions from the official Discord UI set to ``True``.
 
@@ -229,7 +245,7 @@ class Permissions(BaseFlags):
         """
         return cls(1 << 3)
 
-    def update(self, **kwargs):
+    def update(self, **kwargs: bool) -> None:
         r"""Bulk updates this permission object.
 
         Allows you to set multiple attributes by using keyword
@@ -245,7 +261,7 @@ class Permissions(BaseFlags):
             if key in self.VALID_FLAGS:
                 setattr(self, key, value)
 
-    def handle_overwrite(self, allow, deny):
+    def handle_overwrite(self, allow: int, deny: int) -> None:
         # Basically this is what's happening here.
         # We have an original bit array, e.g. 1010
         # Then we have another bit array that is 'denied', e.g. 1111
@@ -261,22 +277,22 @@ class Permissions(BaseFlags):
         self.value = (self.value & ~deny) | allow
 
     @flag_value
-    def create_instant_invite(self):
+    def create_instant_invite(self) -> int:
         """:class:`bool`: Returns ``True`` if the user can create instant invites."""
         return 1 << 0
 
     @flag_value
-    def kick_members(self):
+    def kick_members(self) -> int:
         """:class:`bool`: Returns ``True`` if the user can kick users from the guild."""
         return 1 << 1
 
     @flag_value
-    def ban_members(self):
+    def ban_members(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can ban users from the guild."""
         return 1 << 2
 
     @flag_value
-    def administrator(self):
+    def administrator(self) -> int:
         """:class:`bool`: Returns ``True`` if a user is an administrator. This role overrides all other permissions.
 
         This also bypasses all channel-specific overrides.
@@ -284,44 +300,44 @@ class Permissions(BaseFlags):
         return 1 << 3
 
     @flag_value
-    def manage_channels(self):
+    def manage_channels(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can edit, delete, or create channels in the guild.
 
         This also corresponds to the "Manage Channel" channel-specific override."""
         return 1 << 4
 
     @flag_value
-    def manage_guild(self):
+    def manage_guild(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can edit guild properties."""
         return 1 << 5
 
     @flag_value
-    def add_reactions(self):
+    def add_reactions(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can add reactions to messages."""
         return 1 << 6
 
     @flag_value
-    def view_audit_log(self):
+    def view_audit_log(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can view the guild's audit log."""
         return 1 << 7
 
     @flag_value
-    def priority_speaker(self):
+    def priority_speaker(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can be more easily heard while talking."""
         return 1 << 8
 
     @flag_value
-    def stream(self):
+    def stream(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can stream in a voice channel."""
         return 1 << 9
 
     @flag_value
-    def read_messages(self):
+    def read_messages(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can read messages from all or specific text channels."""
         return 1 << 10
 
     @make_permission_alias('read_messages')
-    def view_channel(self):
+    def view_channel(self) -> int:
         """:class:`bool`: An alias for :attr:`read_messages`.
 
         .. versionadded:: 1.3
@@ -329,17 +345,17 @@ class Permissions(BaseFlags):
         return 1 << 10
 
     @flag_value
-    def send_messages(self):
+    def send_messages(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can send messages from all or specific text channels."""
         return 1 << 11
 
     @flag_value
-    def send_tts_messages(self):
+    def send_tts_messages(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can send TTS messages from all or specific text channels."""
         return 1 << 12
 
     @flag_value
-    def manage_messages(self):
+    def manage_messages(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can delete or pin messages in a text channel.
 
         .. note::
@@ -349,32 +365,32 @@ class Permissions(BaseFlags):
         return 1 << 13
 
     @flag_value
-    def embed_links(self):
+    def embed_links(self) -> int:
         """:class:`bool`: Returns ``True`` if a user's messages will automatically be embedded by Discord."""
         return 1 << 14
 
     @flag_value
-    def attach_files(self):
+    def attach_files(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can send files in their messages."""
         return 1 << 15
 
     @flag_value
-    def read_message_history(self):
+    def read_message_history(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can read a text channel's previous messages."""
         return 1 << 16
 
     @flag_value
-    def mention_everyone(self):
+    def mention_everyone(self) -> int:
         """:class:`bool`: Returns ``True`` if a user's @everyone or @here will mention everyone in the text channel."""
         return 1 << 17
 
     @flag_value
-    def external_emojis(self):
+    def external_emojis(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can use emojis from other guilds."""
         return 1 << 18
 
     @make_permission_alias('external_emojis')
-    def use_external_emojis(self):
+    def use_external_emojis(self) -> int:
         """:class:`bool`: An alias for :attr:`external_emojis`.
 
         .. versionadded:: 1.3
@@ -382,7 +398,7 @@ class Permissions(BaseFlags):
         return 1 << 18
 
     @flag_value
-    def view_guild_insights(self):
+    def view_guild_insights(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can view the guild's insights.
 
         .. versionadded:: 1.3
@@ -390,47 +406,47 @@ class Permissions(BaseFlags):
         return 1 << 19
 
     @flag_value
-    def connect(self):
+    def connect(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can connect to a voice channel."""
         return 1 << 20
 
     @flag_value
-    def speak(self):
+    def speak(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can speak in a voice channel."""
         return 1 << 21
 
     @flag_value
-    def mute_members(self):
+    def mute_members(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can mute other users."""
         return 1 << 22
 
     @flag_value
-    def deafen_members(self):
+    def deafen_members(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can deafen other users."""
         return 1 << 23
 
     @flag_value
-    def move_members(self):
+    def move_members(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can move users between other voice channels."""
         return 1 << 24
 
     @flag_value
-    def use_voice_activation(self):
+    def use_voice_activation(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can use voice activation in voice channels."""
         return 1 << 25
 
     @flag_value
-    def change_nickname(self):
+    def change_nickname(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can change their nickname in the guild."""
         return 1 << 26
 
     @flag_value
-    def manage_nicknames(self):
+    def manage_nicknames(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can change other user's nickname in the guild."""
         return 1 << 27
 
     @flag_value
-    def manage_roles(self):
+    def manage_roles(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can create or edit roles less than their role's position.
 
         This also corresponds to the "Manage Permissions" channel-specific override.
@@ -438,7 +454,7 @@ class Permissions(BaseFlags):
         return 1 << 28
 
     @make_permission_alias('manage_roles')
-    def manage_permissions(self):
+    def manage_permissions(self) -> int:
         """:class:`bool`: An alias for :attr:`manage_roles`.
 
         .. versionadded:: 1.3
@@ -446,17 +462,25 @@ class Permissions(BaseFlags):
         return 1 << 28
 
     @flag_value
-    def manage_webhooks(self):
+    def manage_webhooks(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can create, edit, or delete webhooks."""
         return 1 << 29
 
     @flag_value
-    def manage_emojis(self):
+    def manage_emojis(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can create, edit, or delete emojis."""
         return 1 << 30
 
+    @make_permission_alias('manage_emojis')
+    def manage_emojis_and_stickers(self) -> int:
+        """:class:`bool`: An alias for :attr:`manage_emojis`.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 30
+
     @flag_value
-    def use_slash_commands(self):
+    def use_slash_commands(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can use slash commands.
 
         .. versionadded:: 1.7
@@ -464,14 +488,72 @@ class Permissions(BaseFlags):
         return 1 << 31
 
     @flag_value
-    def request_to_speak(self):
+    def request_to_speak(self) -> int:
         """:class:`bool`: Returns ``True`` if a user can request to speak in a stage channel.
 
         .. versionadded:: 1.7
         """
         return 1 << 32
 
-def augment_from_permissions(cls):
+    @flag_value
+    def manage_events(self) -> int:
+        """:class:`bool`: Returns ``True`` if a user can manage guild events.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 33
+
+    @flag_value
+    def manage_threads(self) -> int:
+        """:class:`bool`: Returns ``True`` if a user can manage threads.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 34
+
+    @flag_value
+    def create_public_threads(self) -> int:
+        """:class:`bool`: Returns ``True`` if a user can create public threads.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 35
+
+    @flag_value
+    def create_private_threads(self) -> int:
+        """:class:`bool`: Returns ``True`` if a user can create private threads.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 36
+
+    @flag_value
+    def external_stickers(self) -> int:
+        """:class:`bool`: Returns ``True`` if a user can use stickers from other guilds.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 37
+
+    @make_permission_alias('external_stickers')
+    def use_external_stickers(self) -> int:
+        """:class:`bool`: An alias for :attr:`external_stickers`.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 37
+
+    @flag_value
+    def send_messages_in_threads(self) -> int:
+        """:class:`bool`: Returns ``True`` if a user can send messages in threads.
+
+        .. versionadded:: 2.0
+        """
+        return 1 << 38
+
+PO = TypeVar('PO', bound='PermissionOverwrite')
+
+def _augment_from_permissions(cls):
     cls.VALID_NAMES = set(Permissions.VALID_FLAGS)
     aliases = set()
 
@@ -488,6 +570,7 @@ def augment_from_permissions(cls):
         # god bless Python
         def getter(self, x=key):
             return self._values.get(x)
+
         def setter(self, value, x=key):
             self._set(x, value)
 
@@ -497,7 +580,8 @@ def augment_from_permissions(cls):
     cls.PURE_FLAGS = cls.VALID_NAMES - aliases
     return cls
 
-@augment_from_permissions
+
+@_augment_from_permissions
 class PermissionOverwrite:
     r"""A type that is used to represent a channel specific permission.
 
@@ -532,8 +616,57 @@ class PermissionOverwrite:
 
     __slots__ = ('_values',)
 
-    def __init__(self, **kwargs):
-        self._values = {}
+    if TYPE_CHECKING:
+        VALID_NAMES: ClassVar[Set[str]]
+        PURE_FLAGS: ClassVar[Set[str]]
+        # I wish I didn't have to do this
+        create_instant_invite: Optional[bool]
+        kick_members: Optional[bool]
+        ban_members: Optional[bool]
+        administrator: Optional[bool]
+        manage_channels: Optional[bool]
+        manage_guild: Optional[bool]
+        add_reactions: Optional[bool]
+        view_audit_log: Optional[bool]
+        priority_speaker: Optional[bool]
+        stream: Optional[bool]
+        read_messages: Optional[bool]
+        view_channel: Optional[bool]
+        send_messages: Optional[bool]
+        send_tts_messages: Optional[bool]
+        manage_messages: Optional[bool]
+        embed_links: Optional[bool]
+        attach_files: Optional[bool]
+        read_message_history: Optional[bool]
+        mention_everyone: Optional[bool]
+        external_emojis: Optional[bool]
+        use_external_emojis: Optional[bool]
+        view_guild_insights: Optional[bool]
+        connect: Optional[bool]
+        speak: Optional[bool]
+        mute_members: Optional[bool]
+        deafen_members: Optional[bool]
+        move_members: Optional[bool]
+        use_voice_activation: Optional[bool]
+        change_nickname: Optional[bool]
+        manage_nicknames: Optional[bool]
+        manage_roles: Optional[bool]
+        manage_permissions: Optional[bool]
+        manage_webhooks: Optional[bool]
+        manage_emojis: Optional[bool]
+        manage_emojis_and_stickers: Optional[bool]
+        use_slash_commands: Optional[bool]
+        request_to_speak: Optional[bool]
+        manage_events: Optional[bool]
+        manage_threads: Optional[bool]
+        create_public_threads: Optional[bool]
+        create_private_threads: Optional[bool]
+        send_messages_in_threads: Optional[bool]
+        external_stickers: Optional[bool]
+        use_external_stickers: Optional[bool]
+
+    def __init__(self, **kwargs: Optional[bool]):
+        self._values: Dict[str, Optional[bool]] = {}
 
         for key, value in kwargs.items():
             if key not in self.VALID_NAMES:
@@ -541,10 +674,10 @@ class PermissionOverwrite:
 
             setattr(self, key, value)
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         return isinstance(other, PermissionOverwrite) and self._values == other._values
 
-    def _set(self, key, value):
+    def _set(self, key: str, value: Optional[bool]) -> None:
         if value not in (True, None, False):
             raise TypeError(f'Expected bool or NoneType, received {value.__class__.__name__}')
 
@@ -553,7 +686,7 @@ class PermissionOverwrite:
         else:
             self._values[key] = value
 
-    def pair(self):
+    def pair(self) -> Tuple[Permissions, Permissions]:
         """Tuple[:class:`Permissions`, :class:`Permissions`]: Returns the (allow, deny) pair from this overwrite."""
 
         allow = Permissions.none()
@@ -568,7 +701,7 @@ class PermissionOverwrite:
         return allow, deny
 
     @classmethod
-    def from_pair(cls, allow, deny):
+    def from_pair(cls: Type[PO], allow: Permissions, deny: Permissions) -> PO:
         """Creates an overwrite from an allow/deny pair of :class:`Permissions`."""
         ret = cls()
         for key, value in allow:
@@ -581,7 +714,7 @@ class PermissionOverwrite:
 
         return ret
 
-    def is_empty(self):
+    def is_empty(self) -> bool:
         """Checks if the permission overwrite is currently empty.
 
         An empty permission overwrite is one that has no overwrites set
@@ -594,7 +727,7 @@ class PermissionOverwrite:
         """
         return len(self._values) == 0
 
-    def update(self, **kwargs):
+    def update(self, **kwargs: bool) -> None:
         r"""Bulk updates this permission overwrite object.
 
         Allows you to set multiple attributes by using keyword
@@ -612,6 +745,6 @@ class PermissionOverwrite:
 
             setattr(self, key, value)
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Tuple[str, Optional[bool]]]:
         for key in self.PURE_FLAGS:
             yield key, self._values.get(key)

discord/player.py

@@ -21,6 +21,7 @@ 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 threading
 import traceback
@@ -33,12 +34,23 @@ import time
 import json
 import sys
 import re
+import io
+
+from typing import Any, Callable,  Generic, IO, Optional, TYPE_CHECKING, Tuple, Type, TypeVar, Union
 
 from .errors import ClientException
 from .opus import Encoder as OpusEncoder
 from .oggparse import OggStream
+from .utils import MISSING
 
-log = logging.getLogger(__name__)
+if TYPE_CHECKING:
+    from .voice_client import VoiceClient
+
+
+AT = TypeVar('AT', bound='AudioSource')
+FT = TypeVar('FT', bound='FFmpegOpusAudio')
+
+_log = logging.getLogger(__name__)
 
 __all__ = (
     'AudioSource',
@@ -49,6 +61,8 @@ __all__ = (
     'PCMVolumeTransformer',
 )
 
+CREATE_NO_WINDOW: int
+
 if sys.platform != 'win32':
     CREATE_NO_WINDOW = 0
 else:
@@ -65,7 +79,7 @@ class AudioSource:
         The audio source reads are done in a separate thread.
     """
 
-    def read(self):
+    def read(self) -> bytes:
         """Reads 20ms worth of audio.
 
         Subclasses must implement this.
@@ -73,7 +87,7 @@ class AudioSource:
         If the audio is complete, then returning an empty
         :term:`py:bytes-like object` to signal this is the way to do so.
 
-        If :meth:`is_opus` method returns ``True``, then it must return
+        If :meth:`~AudioSource.is_opus` method returns ``True``, then it must return
         20ms worth of Opus encoded audio. Otherwise, it must be 20ms
         worth of 16-bit 48KHz stereo PCM, which is about 3,840 bytes
         per frame (20ms worth of audio).
@@ -85,11 +99,11 @@ class AudioSource:
         """
         raise NotImplementedError
 
-    def is_opus(self):
+    def is_opus(self) -> bool:
         """Checks if the audio source is already encoded in Opus."""
         return False
 
-    def cleanup(self):
+    def cleanup(self) -> None:
         """Called when clean-up is needed to be done.
 
         Useful for clearing buffer data or processes after
@@ -97,7 +111,7 @@ class AudioSource:
         """
         pass
 
-    def __del__(self):
+    def __del__(self) -> None:
         self.cleanup()
 
 class PCMAudio(AudioSource):
@@ -108,10 +122,10 @@ class PCMAudio(AudioSource):
     stream: :term:`py:file object`
         A file-like object that reads byte data representing raw PCM.
     """
-    def __init__(self, stream):
-        self.stream = stream
+    def __init__(self, stream: io.BufferedIOBase) -> None:
+        self.stream: io.BufferedIOBase = stream
 
-    def read(self):
+    def read(self) -> bytes:
         ret = self.stream.read(OpusEncoder.FRAME_SIZE)
         if len(ret) != OpusEncoder.FRAME_SIZE:
             return b''
@@ -126,17 +140,27 @@ class FFmpegAudio(AudioSource):
     .. versionadded:: 1.3
     """
 
-    def __init__(self, source, *, executable='ffmpeg', args, **subprocess_kwargs):
-        self._process = self._stdout = None
+    def __init__(self, source: Union[str, io.BufferedIOBase], *, executable: str = 'ffmpeg', args: Any, **subprocess_kwargs: Any):
+        piping = subprocess_kwargs.get('stdin') == subprocess.PIPE
+        if piping and isinstance(source, str):
+            raise TypeError("parameter conflict: 'source' parameter cannot be a string when piping to stdin")
 
         args = [executable, *args]
         kwargs = {'stdout': subprocess.PIPE}
         kwargs.update(subprocess_kwargs)
 
-        self._process = self._spawn_process(args, **kwargs)
-        self._stdout = self._process.stdout
+        self._process: subprocess.Popen = self._spawn_process(args, **kwargs)
+        self._stdout: IO[bytes] = self._process.stdout  # type: ignore
+        self._stdin: Optional[IO[Bytes]] = None
+        self._pipe_thread: Optional[threading.Thread] = None
 
-    def _spawn_process(self, args, **subprocess_kwargs):
+        if piping:
+            n = f'popen-stdin-writer:{id(self):#x}'
+            self._stdin = self._process.stdin
+            self._pipe_thread = threading.Thread(target=self._pipe_writer, args=(source,), daemon=True, name=n)
+            self._pipe_thread.start()
+
+    def _spawn_process(self, args: Any, **subprocess_kwargs: Any) -> subprocess.Popen:
         process = None
         try:
             process = subprocess.Popen(args, creationflags=CREATE_NO_WINDOW, **subprocess_kwargs)
@@ -144,30 +168,48 @@ class FFmpegAudio(AudioSource):
             executable = args.partition(' ')[0] if isinstance(args, str) else args[0]
             raise ClientException(executable + ' was not found.') from None
         except subprocess.SubprocessError as exc:
-            raise ClientException('Popen failed: {0.__class__.__name__}: {0}'.format(exc)) from exc
+            raise ClientException(f'Popen failed: {exc.__class__.__name__}: {exc}') from exc
         else:
             return process
 
-    def cleanup(self):
+    def _kill_process(self) -> None:
         proc = self._process
-        if proc is None:
+        if proc is MISSING:
             return
 
-        log.info('Preparing to terminate ffmpeg process %s.', proc.pid)
+        _log.info('Preparing to terminate ffmpeg process %s.', proc.pid)
 
         try:
             proc.kill()
         except Exception:
-            log.exception("Ignoring error attempting to kill ffmpeg process %s", proc.pid)
+            _log.exception('Ignoring error attempting to kill ffmpeg process %s', proc.pid)
 
         if proc.poll() is None:
-            log.info('ffmpeg process %s has not terminated. Waiting to terminate...', proc.pid)
+            _log.info('ffmpeg process %s has not terminated. Waiting to terminate...', proc.pid)
             proc.communicate()
-            log.info('ffmpeg process %s should have terminated with a return code of %s.', proc.pid, proc.returncode)
+            _log.info('ffmpeg process %s should have terminated with a return code of %s.', proc.pid, proc.returncode)
         else:
-            log.info('ffmpeg process %s successfully terminated with return code of %s.', proc.pid, proc.returncode)
+            _log.info('ffmpeg process %s successfully terminated with return code of %s.', proc.pid, proc.returncode)
 
-        self._process = self._stdout = None
+
+    def _pipe_writer(self, source: io.BufferedIOBase) -> None:
+        while self._process:
+            # arbitrarily large read size
+            data = source.read(8192)
+            if not data:
+                self._process.terminate()
+                return
+            try:
+                self._stdin.write(data)
+            except Exception:
+                _log.debug('Write error for %s, this is probably not a problem', self, exc_info=True)
+                # at this point the source data is either exhausted or the process is fubar
+                self._process.terminate()
+                return
+
+    def cleanup(self) -> None:
+        self._kill_process()
+        self._process = self._stdout = self._stdin = MISSING
 
 class FFmpegPCMAudio(FFmpegAudio):
     """An audio source from FFmpeg (or AVConv).
@@ -204,9 +246,18 @@ class FFmpegPCMAudio(FFmpegAudio):
         The subprocess failed to be created.
     """
 
-    def __init__(self, source, *, executable='ffmpeg', pipe=False, stderr=None, before_options=None, options=None):
+    def __init__(
+        self,
+        source: Union[str, io.BufferedIOBase],
+        *,
+        executable: str = 'ffmpeg',
+        pipe: bool = False,
+        stderr: Optional[IO[str]] = None,
+        before_options: Optional[str] = None,
+        options: Optional[str] = None
+    ) -> None:
         args = []
-        subprocess_kwargs = {'stdin': source if pipe else subprocess.DEVNULL, 'stderr': stderr}
+        subprocess_kwargs = {'stdin': subprocess.PIPE if pipe else subprocess.DEVNULL, 'stderr': stderr}
 
         if isinstance(before_options, str):
             args.extend(shlex.split(before_options))
@@ -222,13 +273,13 @@ class FFmpegPCMAudio(FFmpegAudio):
 
         super().__init__(source, executable=executable, args=args, **subprocess_kwargs)
 
-    def read(self):
+    def read(self) -> bytes:
         ret = self._stdout.read(OpusEncoder.FRAME_SIZE)
         if len(ret) != OpusEncoder.FRAME_SIZE:
             return b''
         return ret
 
-    def is_opus(self):
+    def is_opus(self) -> bool:
         return False
 
 class FFmpegOpusAudio(FFmpegAudio):
@@ -292,11 +343,21 @@ class FFmpegOpusAudio(FFmpegAudio):
         The subprocess failed to be created.
     """
 
-    def __init__(self, source, *, bitrate=128, codec=None, executable='ffmpeg',
-                 pipe=False, stderr=None, before_options=None, options=None):
+    def __init__(
+        self,
+        source: Union[str, io.BufferedIOBase],
+        *,
+        bitrate: int = 128,
+        codec: Optional[str] = None,
+        executable: str = 'ffmpeg',
+        pipe=False,
+        stderr=None,
+        before_options=None,
+        options=None,
+    ) -> None:
 
         args = []
-        subprocess_kwargs = {'stdin': source if pipe else subprocess.DEVNULL, 'stderr': stderr}
+        subprocess_kwargs = {'stdin': subprocess.PIPE if pipe else subprocess.DEVNULL, 'stderr': stderr}
 
         if isinstance(before_options, str):
             args.extend(shlex.split(before_options))
@@ -323,7 +384,13 @@ class FFmpegOpusAudio(FFmpegAudio):
         self._packet_iter = OggStream(self._stdout).iter_packets()
 
     @classmethod
-    async def from_probe(cls, source, *, method=None, **kwargs):
+    async def from_probe(
+        cls: Type[FT],
+        source: str,
+        *,
+        method: Optional[Union[str, Callable[[str, str], Tuple[Optional[str], Optional[int]]]]] = None,
+        **kwargs: Any,
+    ) -> FT:
         """|coro|
 
         A factory method that creates a :class:`FFmpegOpusAudio` after probing
@@ -347,7 +414,6 @@ class FFmpegOpusAudio(FFmpegAudio):
 
             def custom_probe(source, executable):
                 # some analysis code here
-
                 return codec, bitrate
 
             source = await discord.FFmpegOpusAudio.from_probe("song.webm", method=custom_probe)
@@ -382,10 +448,16 @@ class FFmpegOpusAudio(FFmpegAudio):
 
         executable = kwargs.get('executable')
         codec, bitrate = await cls.probe(source, method=method, executable=executable)
-        return cls(source, bitrate=bitrate, codec=codec, **kwargs)
+        return cls(source, bitrate=bitrate, codec=codec, **kwargs)  # type: ignore
 
     @classmethod
-    async def probe(cls, source, *, method=None, executable=None):
+    async def probe(
+        cls,
+        source: str,
+        *,
+        method: Optional[Union[str, Callable[[str, str], Tuple[Optional[str], Optional[int]]]]] = None,
+        executable: Optional[str] = None,
+    ) -> Tuple[Optional[str], Optional[int]]:
         """|coro|
 
         Probes the input source for bitrate and codec information.
@@ -408,7 +480,7 @@ class FFmpegOpusAudio(FFmpegAudio):
 
         Returns
         ---------
-        Tuple[Optional[:class:`str`], Optional[:class:`int`]]
+        Optional[Tuple[Optional[:class:`str`], Optional[:class:`int`]]]
             A 2-tuple with the codec and bitrate of the input source.
         """
 
@@ -434,26 +506,26 @@ class FFmpegOpusAudio(FFmpegAudio):
         codec = bitrate = None
         loop = asyncio.get_event_loop()
         try:
-            codec, bitrate = await loop.run_in_executor(None, lambda: probefunc(source, executable))
+            codec, bitrate = await loop.run_in_executor(None, lambda: probefunc(source, executable))  # type: ignore
         except Exception:
             if not fallback:
-                log.exception("Probe '%s' using '%s' failed", method, executable)
-                return
+                _log.exception("Probe '%s' using '%s' failed", method, executable)
+                return  # type: ignore
 
-            log.exception("Probe '%s' using '%s' failed, trying fallback", method, executable)
+            _log.exception("Probe '%s' using '%s' failed, trying fallback", method, executable)
             try:
-                codec, bitrate = await loop.run_in_executor(None, lambda: fallback(source, executable))
+                codec, bitrate = await loop.run_in_executor(None, lambda: fallback(source, executable))  # type: ignore
             except Exception:
-                log.exception("Fallback probe using '%s' failed", executable)
+                _log.exception("Fallback probe using '%s' failed", executable)
             else:
-                log.info("Fallback probe found codec=%s, bitrate=%s", codec, bitrate)
+                _log.info("Fallback probe found codec=%s, bitrate=%s", codec, bitrate)
         else:
-            log.info("Probe found codec=%s, bitrate=%s", codec, bitrate)
+            _log.info("Probe found codec=%s, bitrate=%s", codec, bitrate)
         finally:
             return codec, bitrate
 
     @staticmethod
-    def _probe_codec_native(source, executable='ffmpeg'):
+    def _probe_codec_native(source, executable: str = 'ffmpeg') -> Tuple[Optional[str], Optional[int]]:
         exe = executable[:2] + 'probe' if executable in ('ffmpeg', 'avconv') else executable
         args = [exe, '-v', 'quiet', '-print_format', 'json', '-show_streams', '-select_streams', 'a:0', source]
         output = subprocess.check_output(args, timeout=20)
@@ -465,12 +537,12 @@ class FFmpegOpusAudio(FFmpegAudio):
 
             codec = streamdata.get('codec_name')
             bitrate = int(streamdata.get('bit_rate', 0))
-            bitrate = max(round(bitrate/1000, 0), 512)
+            bitrate = max(round(bitrate/1000), 512)
 
         return codec, bitrate
 
     @staticmethod
-    def _probe_codec_fallback(source, executable='ffmpeg'):
+    def _probe_codec_fallback(source, executable: str = 'ffmpeg') -> Tuple[Optional[str], Optional[int]]:
         args = [executable, '-hide_banner', '-i',  source]
         proc = subprocess.Popen(args, creationflags=CREATE_NO_WINDOW, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
         out, _ = proc.communicate(timeout=20)
@@ -487,13 +559,13 @@ class FFmpegOpusAudio(FFmpegAudio):
 
         return codec, bitrate
 
-    def read(self):
+    def read(self) -> bytes:
         return next(self._packet_iter, b'')
 
-    def is_opus(self):
+    def is_opus(self) -> bool:
         return True
 
-class PCMVolumeTransformer(AudioSource):
+class PCMVolumeTransformer(AudioSource, Generic[AT]):
     """Transforms a previous :class:`AudioSource` to have volume controls.
 
     This does not work on audio sources that have :meth:`AudioSource.is_opus`
@@ -515,53 +587,53 @@ class PCMVolumeTransformer(AudioSource):
         The audio source is opus encoded.
     """
 
-    def __init__(self, original, volume=1.0):
+    def __init__(self, original: AT, volume: float = 1.0):
         if not isinstance(original, AudioSource):
             raise TypeError(f'expected AudioSource not {original.__class__.__name__}.')
 
         if original.is_opus():
             raise ClientException('AudioSource must not be Opus encoded.')
 
-        self.original = original
+        self.original: AT = original
         self.volume = volume
 
     @property
-    def volume(self):
+    def volume(self) -> float:
         """Retrieves or sets the volume as a floating point percentage (e.g. ``1.0`` for 100%)."""
         return self._volume
 
     @volume.setter
-    def volume(self, value):
+    def volume(self, value: float) -> None:
         self._volume = max(value, 0.0)
 
-    def cleanup(self):
+    def cleanup(self) -> None:
         self.original.cleanup()
 
-    def read(self):
+    def read(self) -> bytes:
         ret = self.original.read()
         return audioop.mul(ret, 2, min(self._volume, 2.0))
 
 class AudioPlayer(threading.Thread):
-    DELAY = OpusEncoder.FRAME_LENGTH / 1000.0
+    DELAY: float = OpusEncoder.FRAME_LENGTH / 1000.0
 
-    def __init__(self, source, client, *, after=None):
+    def __init__(self, source: AudioSource, client: VoiceClient, *, after=None):
         threading.Thread.__init__(self)
-        self.daemon = True
-        self.source = source
-        self.client = client
-        self.after = after
+        self.daemon: bool = True
+        self.source: AudioSource = source
+        self.client: VoiceClient = client
+        self.after: Optional[Callable[[Optional[Exception]], Any]] = after
 
-        self._end = threading.Event()
-        self._resumed = threading.Event()
+        self._end: threading.Event = threading.Event()
+        self._resumed: threading.Event = threading.Event()
         self._resumed.set() # we are not paused
-        self._current_error = None
-        self._connected = client._connected
-        self._lock = threading.Lock()
+        self._current_error: Optional[Exception] = None
+        self._connected: threading.Event = client._connected
+        self._lock: threading.Lock = threading.Lock()
 
         if after is not None and not callable(after):
             raise TypeError('Expected a callable for the "after" parameter.')
 
-    def _do_run(self):
+    def _do_run(self) -> None:
         self.loops = 0
         self._start = time.perf_counter()
 
@@ -596,7 +668,7 @@ class AudioPlayer(threading.Thread):
             delay = max(0, self.DELAY + (next_time - time.perf_counter()))
             time.sleep(delay)
 
-    def run(self):
+    def run(self) -> None:
         try:
             self._do_run()
         except Exception as exc:
@@ -606,53 +678,53 @@ class AudioPlayer(threading.Thread):
             self.source.cleanup()
             self._call_after()
 
-    def _call_after(self):
+    def _call_after(self) -> None:
         error = self._current_error
 
         if self.after is not None:
             try:
                 self.after(error)
             except Exception as exc:
-                log.exception('Calling the after function failed.')
+                _log.exception('Calling the after function failed.')
                 exc.__context__ = error
                 traceback.print_exception(type(exc), exc, exc.__traceback__)
         elif error:
             msg = f'Exception in voice thread {self.name}'
-            log.exception(msg, exc_info=error)
+            _log.exception(msg, exc_info=error)
             print(msg, file=sys.stderr)
             traceback.print_exception(type(error), error, error.__traceback__)
 
-    def stop(self):
+    def stop(self) -> None:
         self._end.set()
         self._resumed.set()
         self._speak(False)
 
-    def pause(self, *, update_speaking=True):
+    def pause(self, *, update_speaking: bool = True) -> None:
         self._resumed.clear()
         if update_speaking:
             self._speak(False)
 
-    def resume(self, *, update_speaking=True):
+    def resume(self, *, update_speaking: bool = True) -> None:
         self.loops = 0
         self._start = time.perf_counter()
         self._resumed.set()
         if update_speaking:
             self._speak(True)
 
-    def is_playing(self):
+    def is_playing(self) -> bool:
         return self._resumed.is_set() and not self._end.is_set()
 
-    def is_paused(self):
+    def is_paused(self) -> bool:
         return not self._end.is_set() and not self._resumed.is_set()
 
-    def _set_source(self, source):
+    def _set_source(self, source: AudioSource) -> None:
         with self._lock:
             self.pause(update_speaking=False)
             self.source = source
             self.resume(update_speaking=False)
 
-    def _speak(self, speaking):
+    def _speak(self, speaking: bool) -> None:
         try:
             asyncio.run_coroutine_threadsafe(self.client.ws.speak(speaking), self.client.loop)
         except Exception as e:
-            log.info("Speaking call in player failed: %s", e)
+            _log.info("Speaking call in player failed: %s", e)

discord/raw_models.py

@@ -22,6 +22,28 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Set, List
+
+if TYPE_CHECKING:
+    from .types.raw_models import (
+        MessageDeleteEvent,
+        BulkMessageDeleteEvent,
+        ReactionActionEvent,
+        MessageUpdateEvent,
+        ReactionClearEvent,
+        ReactionClearEmojiEvent,
+        IntegrationDeleteEvent
+    )
+    from .message import Message
+    from .partial_emoji import PartialEmoji
+    from .member import Member
+    from .threads import Thread
+
+
+from .enums import ChannelType, try_enum
+
 __all__ = (
     'RawMessageDeleteEvent',
     'RawBulkMessageDeleteEvent',
@@ -29,13 +51,17 @@ __all__ = (
     'RawReactionActionEvent',
     'RawReactionClearEvent',
     'RawReactionClearEmojiEvent',
+    'RawIntegrationDeleteEvent',
+    'RawThreadDeleteEvent',
 )
 
+
 class _RawReprMixin:
-    def __repr__(self):
+    def __repr__(self) -> str:
         value = ' '.join(f'{attr}={getattr(self, attr)!r}' for attr in self.__slots__)
         return f'<{self.__class__.__name__} {value}>'
 
+
 class RawMessageDeleteEvent(_RawReprMixin):
     """Represents the event payload for a :func:`on_raw_message_delete` event.
 
@@ -53,14 +79,15 @@ class RawMessageDeleteEvent(_RawReprMixin):
 
     __slots__ = ('message_id', 'channel_id', 'guild_id', 'cached_message')
 
-    def __init__(self, data):
-        self.message_id = int(data['id'])
-        self.channel_id = int(data['channel_id'])
-        self.cached_message = None
+    def __init__(self, data: MessageDeleteEvent) -> None:
+        self.message_id: int = int(data['id'])
+        self.channel_id: int = int(data['channel_id'])
+        self.cached_message: Optional[Message] = None
         try:
-            self.guild_id = int(data['guild_id'])
+            self.guild_id: Optional[int] = int(data['guild_id'])
         except KeyError:
-            self.guild_id = None
+            self.guild_id: Optional[int] = None
+
 
 class RawBulkMessageDeleteEvent(_RawReprMixin):
     """Represents the event payload for a :func:`on_raw_bulk_message_delete` event.
@@ -79,15 +106,16 @@ class RawBulkMessageDeleteEvent(_RawReprMixin):
 
     __slots__ = ('message_ids', 'channel_id', 'guild_id', 'cached_messages')
 
-    def __init__(self, data):
-        self.message_ids = {int(x) for x in data.get('ids', [])}
-        self.channel_id = int(data['channel_id'])
-        self.cached_messages = []
+    def __init__(self, data: BulkMessageDeleteEvent) -> None:
+        self.message_ids: Set[int] = {int(x) for x in data.get('ids', [])}
+        self.channel_id: int = int(data['channel_id'])
+        self.cached_messages: List[Message] = []
 
         try:
-            self.guild_id = int(data['guild_id'])
+            self.guild_id: Optional[int] = int(data['guild_id'])
         except KeyError:
-            self.guild_id = None
+            self.guild_id: Optional[int] = None
+
 
 class RawMessageUpdateEvent(_RawReprMixin):
     """Represents the payload for a :func:`on_raw_message_edit` event.
@@ -114,16 +142,17 @@ class RawMessageUpdateEvent(_RawReprMixin):
 
     __slots__ = ('message_id', 'channel_id', 'guild_id', 'data', 'cached_message')
 
-    def __init__(self, data):
-        self.message_id = int(data['id'])
-        self.channel_id = int(data['channel_id'])
-        self.data = data
-        self.cached_message = None
+    def __init__(self, data: MessageUpdateEvent) -> None:
+        self.message_id: int = int(data['id'])
+        self.channel_id: int = int(data['channel_id'])
+        self.data: MessageUpdateEvent = data
+        self.cached_message: Optional[Message] = None
 
         try:
-            self.guild_id = int(data['guild_id'])
+            self.guild_id: Optional[int] = int(data['guild_id'])
         except KeyError:
-            self.guild_id = None
+            self.guild_id: Optional[int] = None
+
 
 class RawReactionActionEvent(_RawReprMixin):
     """Represents the payload for a :func:`on_raw_reaction_add` or
@@ -157,18 +186,19 @@ class RawReactionActionEvent(_RawReprMixin):
     __slots__ = ('message_id', 'user_id', 'channel_id', 'guild_id', 'emoji',
                  'event_type', 'member')
 
-    def __init__(self, data, emoji, event_type):
-        self.message_id = int(data['message_id'])
-        self.channel_id = int(data['channel_id'])
-        self.user_id = int(data['user_id'])
-        self.emoji = emoji
-        self.event_type = event_type
-        self.member = None
+    def __init__(self, data: ReactionActionEvent, emoji: PartialEmoji, event_type: str) -> None:
+        self.message_id: int = int(data['message_id'])
+        self.channel_id: int = int(data['channel_id'])
+        self.user_id: int = int(data['user_id'])
+        self.emoji: PartialEmoji = emoji
+        self.event_type: str = event_type
+        self.member: Optional[Member] = None
 
         try:
-            self.guild_id = int(data['guild_id'])
+            self.guild_id: Optional[int] = int(data['guild_id'])
         except KeyError:
-            self.guild_id = None
+            self.guild_id: Optional[int] = None
+
 
 class RawReactionClearEvent(_RawReprMixin):
     """Represents the payload for a :func:`on_raw_reaction_clear` event.
@@ -185,14 +215,15 @@ class RawReactionClearEvent(_RawReprMixin):
 
     __slots__ = ('message_id', 'channel_id', 'guild_id')
 
-    def __init__(self, data):
-        self.message_id = int(data['message_id'])
-        self.channel_id = int(data['channel_id'])
+    def __init__(self, data: ReactionClearEvent) -> None:
+        self.message_id: int = int(data['message_id'])
+        self.channel_id: int = int(data['channel_id'])
 
         try:
-            self.guild_id = int(data['guild_id'])
+            self.guild_id: Optional[int] = int(data['guild_id'])
         except KeyError:
-            self.guild_id = None
+            self.guild_id: Optional[int] = None
+
 
 class RawReactionClearEmojiEvent(_RawReprMixin):
     """Represents the payload for a :func:`on_raw_reaction_clear_emoji` event.
@@ -213,12 +244,67 @@ class RawReactionClearEmojiEvent(_RawReprMixin):
 
     __slots__ = ('message_id', 'channel_id', 'guild_id', 'emoji')
 
-    def __init__(self, data, emoji):
-        self.emoji = emoji
-        self.message_id = int(data['message_id'])
-        self.channel_id = int(data['channel_id'])
+    def __init__(self, data: ReactionClearEmojiEvent, emoji: PartialEmoji) -> None:
+        self.emoji: PartialEmoji = emoji
+        self.message_id: int = int(data['message_id'])
+        self.channel_id: int = int(data['channel_id'])
 
         try:
-            self.guild_id = int(data['guild_id'])
+            self.guild_id: Optional[int] = int(data['guild_id'])
         except KeyError:
-            self.guild_id = None
+            self.guild_id: Optional[int] = None
+
+
+class RawIntegrationDeleteEvent(_RawReprMixin):
+    """Represents the payload for a :func:`on_raw_integration_delete` event.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    integration_id: :class:`int`
+        The ID of the integration that got deleted.
+    application_id: Optional[:class:`int`]
+        The ID of the bot/OAuth2 application for this deleted integration.
+    guild_id: :class:`int`
+        The guild ID where the integration got deleted.
+    """
+
+    __slots__ = ('integration_id', 'application_id', 'guild_id')
+
+    def __init__(self, data: IntegrationDeleteEvent) -> None:
+        self.integration_id: int = int(data['id'])
+        self.guild_id: int = int(data['guild_id'])
+
+        try:
+            self.application_id: Optional[int] = int(data['application_id'])
+        except KeyError:
+            self.application_id: Optional[int] = None
+
+class RawThreadDeleteEvent(_RawReprMixin):
+    """Represents the payload for a :func:`on_raw_thread_delete` event.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    ----------
+    thread_id: :class:`int`
+        The ID of the thread that was deleted.
+    thread_type: :class:`discord.ChannelType`
+        The channel type of the deleted thread.
+    guild_id: :class:`int`
+        The ID of the guild the thread was deleted in.
+    parent_id: :class:`int`
+        The ID of the channel the thread was belonged to.
+    thread: Optional[:class:`discord.Thread`]
+        The thread, if it could be found in the internal cache.
+    """
+
+    __slots__ = ('thread_id', 'thread_type', 'parent_id', 'guild_id', 'thread')
+
+    def __init__(self, data) -> None:
+        self.thread_id: int = int(data['id'])
+        self.thread_type: ChannelType = try_enum(ChannelType, data['type'])
+        self.guild_id: int = int(data['guild_id'])
+        self.parent_id: int = int(data['parent_id'])
+        self.thread: Optional[Thread] = None

discord/reaction.py

@@ -22,12 +22,22 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+from typing import Any, TYPE_CHECKING, Union, Optional
+
 from .iterators import ReactionIterator
 
 __all__ = (
     'Reaction',
 )
 
+if TYPE_CHECKING:
+    from .types.message import Reaction as ReactionPayload
+    from .message import Message
+    from .partial_emoji import PartialEmoji
+    from .emoji import Emoji
+    from .abc import Snowflake
+
 class Reaction:
     """Represents a reaction to a message.
 
@@ -67,35 +77,35 @@ class Reaction:
     """
     __slots__ = ('message', 'count', 'emoji', 'me')
 
-    def __init__(self, *, message, data, emoji=None):
-        self.message = message
-        self.emoji = emoji or message._state.get_reaction_emoji(data['emoji'])
-        self.count = data.get('count', 1)
-        self.me = data.get('me')
+    def __init__(self, *, message: Message, data: ReactionPayload, emoji: Optional[Union[PartialEmoji, Emoji, str]] = None):
+        self.message: Message = message
+        self.emoji: Union[PartialEmoji, Emoji, str] = emoji or message._state.get_reaction_emoji(data['emoji'])
+        self.count: int = data.get('count', 1)
+        self.me: bool = data.get('me')
 
-    @property
-    def custom_emoji(self):
+    # TODO: typeguard
+    def is_custom_emoji(self) -> bool:
         """:class:`bool`: If this is a custom emoji."""
         return not isinstance(self.emoji, str)
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any) -> bool:
         return isinstance(other, self.__class__) and other.emoji == self.emoji
 
-    def __ne__(self, other):
+    def __ne__(self, other: Any) -> bool:
         if isinstance(other, self.__class__):
             return other.emoji != self.emoji
         return True
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.emoji)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self.emoji)
 
-    def __repr__(self):
-        return '<Reaction emoji={0.emoji!r} me={0.me} count={0.count}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<Reaction emoji={self.emoji!r} me={self.me} count={self.count}>'
 
-    async def remove(self, user):
+    async def remove(self, user: Snowflake) -> None:
         """|coro|
 
         Remove the reaction by the provided :class:`User` from the message.
@@ -123,7 +133,7 @@ class Reaction:
 
         await self.message.remove_reaction(self.emoji, user)
 
-    async def clear(self):
+    async def clear(self) -> None:
         """|coro|
 
         Clears this reaction from the message.
@@ -145,7 +155,7 @@ class Reaction:
         """
         await self.message.clear_reaction(self.emoji)
 
-    def users(self, limit=None, after=None):
+    def users(self, *, limit: Optional[int] = None, after: Optional[Snowflake] = None) -> ReactionIterator:
         """Returns an :class:`AsyncIterator` representing the users that have reacted to the message.
 
         The ``after`` parameter must represent a member
@@ -158,22 +168,22 @@ class Reaction:
 
             # I do not actually recommend doing this.
             async for user in reaction.users():
-                await channel.send('{0} has reacted with {1.emoji}!'.format(user, reaction))
+                await channel.send(f'{user} has reacted with {reaction.emoji}!')
 
         Flattening into a list: ::
 
             users = await reaction.users().flatten()
             # users is now a list of User...
             winner = random.choice(users)
-            await channel.send('{} has won the raffle.'.format(winner))
+            await channel.send(f'{winner} has won the raffle.')
 
         Parameters
         ------------
-        limit: :class:`int`
+        limit: Optional[:class:`int`]
             The maximum number of results to return.
             If not provided, returns all the users who
             reacted to the message.
-        after: :class:`abc.Snowflake`
+        after: Optional[:class:`abc.Snowflake`]
             For pagination, reactions are sorted by member.
 
         Raises
@@ -190,8 +200,8 @@ class Reaction:
             if the member has left the guild.
         """
 
-        if self.custom_emoji:
-            emoji = '{0.name}:{0.id}'.format(self.emoji)
+        if not isinstance(self.emoji, str):
+            emoji = f'{self.emoji.name}:{self.emoji.id}'
         else:
             emoji = self.emoji
 

discord/role.py

@@ -22,17 +22,32 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+from typing import Any, Dict, List, Optional, TypeVar, Union, overload, TYPE_CHECKING
+
 from .permissions import Permissions
 from .errors import InvalidArgument
 from .colour import Colour
 from .mixins import Hashable
-from .utils import snowflake_time, _get_as_snowflake
+from .utils import snowflake_time, _get_as_snowflake, MISSING
 
 __all__ = (
     'RoleTags',
     'Role',
 )
 
+if TYPE_CHECKING:
+    import datetime
+    from .types.role import (
+        Role as RolePayload,
+        RoleTags as RoleTagPayload,
+    )
+    from .types.guild import RolePositionUpdate
+    from .guild import Guild
+    from .member import Member
+    from .state import ConnectionState
+
+
 class RoleTags:
     """Represents tags on a role.
 
@@ -52,32 +67,42 @@ class RoleTags:
         The integration ID that manages the role.
     """
 
-    __slots__ = ('bot_id', 'integration_id', '_premium_subscriber',)
+    __slots__ = (
+        'bot_id',
+        'integration_id',
+        '_premium_subscriber',
+    )
 
-    def __init__(self, data):
-        self.bot_id = _get_as_snowflake(data, 'bot_id')
-        self.integration_id = _get_as_snowflake(data, 'integration_id')
+    def __init__(self, data: RoleTagPayload):
+        self.bot_id: Optional[int] = _get_as_snowflake(data, 'bot_id')
+        self.integration_id: Optional[int] = _get_as_snowflake(data, 'integration_id')
         # NOTE: The API returns "null" for this if it's valid, which corresponds to None.
         # This is different from other fields where "null" means "not there".
         # So in this case, a value of None is the same as True.
-        # Which means we would need a different sentinel. For this purpose I used ellipsis.
-        self._premium_subscriber = data.get('premium_subscriber', ...)
+        # Which means we would need a different sentinel.
+        self._premium_subscriber: Optional[Any] = data.get('premium_subscriber', MISSING)
 
-    def is_bot_managed(self):
+    def is_bot_managed(self) -> bool:
         """:class:`bool`: Whether the role is associated with a bot."""
         return self.bot_id is not None
 
-    def is_premium_subscriber(self):
+    def is_premium_subscriber(self) -> bool:
         """:class:`bool`: Whether the role is the premium subscriber, AKA "boost", role for the guild."""
         return self._premium_subscriber is None
 
-    def is_integration(self):
+    def is_integration(self) -> bool:
         """:class:`bool`: Whether the role is managed by an integration."""
         return self.integration_id is not None
 
-    def __repr__(self):
-        return '<RoleTags bot_id={0.bot_id} integration_id={0.integration_id} ' \
-               'premium_subscriber={1}>'.format(self, self.is_premium_subscriber())
+    def __repr__(self) -> str:
+        return (
+            f'<RoleTags bot_id={self.bot_id} integration_id={self.integration_id} '
+            f'premium_subscriber={self.is_premium_subscriber()}>'
+        )
+
+
+R = TypeVar('R', bound='Role')
+
 
 class Role(Hashable):
     """Represents a Discord role in a :class:`Guild`.
@@ -116,6 +141,14 @@ class Role(Hashable):
 
             Returns the role's name.
 
+        .. describe:: str(x)
+
+            Returns the role's ID.
+
+        .. describe:: int(x)
+
+            Returns the role's ID.
+
     Attributes
     ----------
     id: :class:`int`
@@ -129,6 +162,15 @@ class Role(Hashable):
     position: :class:`int`
         The position of the role. This number is usually positive. The bottom
         role has a position of 0.
+
+        .. warning::
+
+            Multiple roles can have the same position number. As a consequence
+            of this, comparing via role position is prone to subtle bugs if
+            checking for role hierarchy. The recommended and correct way to
+            compare for roles in the hierarchy is using the comparison
+            operators on the role objects themselves.
+
     managed: :class:`bool`
         Indicates if the role is managed by the guild through some form of
         integrations such as Twitch.
@@ -138,22 +180,36 @@ class Role(Hashable):
         The role tags associated with this role.
     """
 
-    __slots__ = ('id', 'name', '_permissions', '_colour', 'position',
-                 'managed', 'mentionable', 'hoist', 'guild', 'tags', '_state')
+    __slots__ = (
+        'id',
+        'name',
+        '_permissions',
+        '_colour',
+        'position',
+        'managed',
+        'mentionable',
+        'hoist',
+        'guild',
+        'tags',
+        '_state',
+    )
 
-    def __init__(self, *, guild, state, data):
-        self.guild = guild
-        self._state = state
-        self.id = int(data['id'])
+    def __init__(self, *, guild: Guild, state: ConnectionState, data: RolePayload):
+        self.guild: Guild = guild
+        self._state: ConnectionState = state
+        self.id: int = int(data['id'])
         self._update(data)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name
 
-    def __repr__(self):
-        return '<Role id={0.id} name={0.name!r}>'.format(self)
+    def __int__(self) -> int:
+        return self.id
 
-    def __lt__(self, other):
+    def __repr__(self) -> str:
+        return f'<Role id={self.id} name={self.name!r}>'
+
+    def __lt__(self: R, other: R) -> bool:
         if not isinstance(other, Role) or not isinstance(self, Role):
             return NotImplemented
 
@@ -174,87 +230,96 @@ class Role(Hashable):
 
         return False
 
-    def __le__(self, other):
+    def __le__(self: R, other: R) -> bool:
         r = Role.__lt__(other, self)
         if r is NotImplemented:
             return NotImplemented
         return not r
 
-    def __gt__(self, other):
+    def __gt__(self: R, other: R) -> bool:
         return Role.__lt__(other, self)
 
-    def __ge__(self, other):
+    def __ge__(self: R, other: R) -> bool:
         r = Role.__lt__(self, other)
         if r is NotImplemented:
             return NotImplemented
         return not r
 
-    def _update(self, data):
-        self.name = data['name']
-        self._permissions = int(data.get('permissions_new', 0))
-        self.position = data.get('position', 0)
-        self._colour = data.get('color', 0)
-        self.hoist = data.get('hoist', False)
-        self.managed = data.get('managed', False)
-        self.mentionable = data.get('mentionable', False)
+    def _update(self, data: RolePayload):
+        self.name: str = data['name']
+        self._permissions: int = int(data.get('permissions', 0))
+        self.position: int = data.get('position', 0)
+        self._colour: int = data.get('color', 0)
+        self.hoist: bool = data.get('hoist', False)
+        self.managed: bool = data.get('managed', False)
+        self.mentionable: bool = data.get('mentionable', False)
+        self.tags: Optional[RoleTags]
 
         try:
             self.tags = RoleTags(data['tags'])
         except KeyError:
             self.tags = None
 
-    def is_default(self):
+    def is_default(self) -> bool:
         """:class:`bool`: Checks if the role is the default role."""
         return self.guild.id == self.id
 
-    def is_bot_managed(self):
+    def is_bot_managed(self) -> bool:
         """:class:`bool`: Whether the role is associated with a bot.
 
         .. versionadded:: 1.6
         """
         return self.tags is not None and self.tags.is_bot_managed()
 
-    def is_premium_subscriber(self):
+    def is_premium_subscriber(self) -> bool:
         """:class:`bool`: Whether the role is the premium subscriber, AKA "boost", role for the guild.
 
         .. versionadded:: 1.6
         """
         return self.tags is not None and self.tags.is_premium_subscriber()
 
-    def is_integration(self):
+    def is_integration(self) -> bool:
         """:class:`bool`: Whether the role is managed by an integration.
 
         .. versionadded:: 1.6
         """
         return self.tags is not None and self.tags.is_integration()
 
+    def is_assignable(self) -> bool:
+        """:class:`bool`: Whether the role is able to be assigned or removed by the bot.
+
+        .. versionadded:: 2.0
+        """
+        me = self.guild.me
+        return not self.is_default() and not self.managed and (me.top_role > self or me.id == self.guild.owner_id)
+
     @property
-    def permissions(self):
+    def permissions(self) -> Permissions:
         """:class:`Permissions`: Returns the role's permissions."""
         return Permissions(self._permissions)
 
     @property
-    def colour(self):
+    def colour(self) -> Colour:
         """:class:`Colour`: Returns the role colour. An alias exists under ``color``."""
         return Colour(self._colour)
 
     @property
-    def color(self):
+    def color(self) -> Colour:
         """:class:`Colour`: Returns the role color. An alias exists under ``colour``."""
         return self.colour
 
     @property
-    def created_at(self):
+    def created_at(self) -> datetime.datetime:
         """:class:`datetime.datetime`: Returns the role's creation time in UTC."""
         return snowflake_time(self.id)
 
     @property
-    def mention(self):
+    def mention(self) -> str:
         """:class:`str`: Returns a string that allows you to mention a role."""
         return f'<@&{self.id}>'
 
     @property
-    def members(self):
+    def members(self) -> List[Member]:
         """List[:class:`Member`]: Returns all the members with this role."""
         all_members = self.guild.members
         if self.is_default():
@@ -263,7 +328,7 @@ class Role(Hashable):
         role_id = self.id
         return [member for member in all_members if member._roles.has(role_id)]
 
-    async def _move(self, position, reason):
+    async def _move(self, position: int, reason: Optional[str]) -> None:
         if position <= 0:
             raise InvalidArgument("Cannot move role to position 0 or below")
 
@@ -283,10 +348,21 @@ class Role(Hashable):
         else:
             roles.append(self.id)
 
-        payload = [{"id": z[0], "position": z[1]} for z in zip(roles, change_range)]
+        payload: List[RolePositionUpdate] = [{"id": z[0], "position": z[1]} for z in zip(roles, change_range)]
         await http.move_role_position(self.guild.id, payload, reason=reason)
 
-    async def edit(self, *, reason=None, **fields):
+    async def edit(
+        self,
+        *,
+        name: str = MISSING,
+        permissions: Permissions = MISSING,
+        colour: Union[Colour, int] = MISSING,
+        color: Union[Colour, int] = MISSING,
+        hoist: bool = MISSING,
+        mentionable: bool = MISSING,
+        position: int = MISSING,
+        reason: Optional[str] = MISSING,
+    ) -> Optional[Role]:
         """|coro|
 
         Edits the role.
@@ -299,6 +375,9 @@ class Role(Hashable):
         .. versionchanged:: 1.4
             Can now pass ``int`` to ``colour`` keyword-only parameter.
 
+        .. versionchanged:: 2.0
+            Edits are no longer in-place, the newly edited role is returned instead.
+
         Parameters
         -----------
         name: :class:`str`
@@ -326,33 +405,41 @@ class Role(Hashable):
         InvalidArgument
             An invalid position was given or the default
             role was asked to be moved.
+
+        Returns
+        --------
+        :class:`Role`
+            The newly edited role.
         """
-
-        position = fields.get('position')
-        if position is not None:
+        if position is not MISSING:
             await self._move(position, reason=reason)
-            self.position = position
 
-        try:
-            colour = fields['colour']
-        except KeyError:
-            colour = fields.get('color', self.colour)
+        payload: Dict[str, Any] = {}
+        if color is not MISSING:
+            colour = color
 
-        if isinstance(colour, int):
-            colour = Colour(value=colour)
+        if colour is not MISSING:
+            if isinstance(colour, int):
+                payload['color'] = colour
+            else:
+                payload['color'] = colour.value
 
-        payload = {
-            'name': fields.get('name', self.name),
-            'permissions': str(fields.get('permissions', self.permissions).value),
-            'color': colour.value,
-            'hoist': fields.get('hoist', self.hoist),
-            'mentionable': fields.get('mentionable', self.mentionable)
-        }
+        if name is not MISSING:
+            payload['name'] = name
+
+        if permissions is not MISSING:
+            payload['permissions'] = permissions.value
+
+        if hoist is not MISSING:
+            payload['hoist'] = hoist
+
+        if mentionable is not MISSING:
+            payload['mentionable'] = mentionable
 
         data = await self._state.http.edit_role(self.guild.id, self.id, reason=reason, **payload)
-        self._update(data)
+        return Role(guild=self.guild, data=data, state=self._state)
 
-    async def delete(self, *, reason=None):
+    async def delete(self, *, reason: Optional[str] = None) -> None:
         """|coro|
 
         Deletes the role.

discord/shard.py

@@ -22,8 +22,9 @@ 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 itertools
 import logging
 
 import aiohttp
@@ -34,22 +35,30 @@ from .backoff import ExponentialBackoff
 from .gateway import *
 from .errors import (
     ClientException,
-    InvalidArgument,
     HTTPException,
     GatewayNotFound,
     ConnectionClosed,
     PrivilegedIntentsRequired,
 )
 
-from . import utils
 from .enums import Status
 
+from typing import TYPE_CHECKING, Any, Callable, Tuple, Type, Optional, List, Dict, TypeVar
+
+if TYPE_CHECKING:
+    from .gateway import DiscordWebSocket
+    from .activity import BaseActivity
+    from .enums import Status
+
+    EI = TypeVar('EI', bound='EventItem')
+
 __all__ = (
     'AutoShardedClient',
     'ShardInfo',
 )
 
-log = logging.getLogger(__name__)
+_log = logging.getLogger(__name__)
+
 
 class EventType:
     close = 0
@@ -59,39 +68,41 @@ class EventType:
     terminate = 4
     clean_close = 5
 
+
 class EventItem:
     __slots__ = ('type', 'shard', 'error')
 
-    def __init__(self, etype, shard, error):
-        self.type = etype
-        self.shard = shard
-        self.error = error
+    def __init__(self, etype: int, shard: Optional['Shard'], error: Optional[Exception]) -> None:
+        self.type: int = etype
+        self.shard: Optional['Shard'] = shard
+        self.error: Optional[Exception] = error
 
-    def __lt__(self, other):
+    def __lt__(self: EI, other: EI) -> bool:
         if not isinstance(other, EventItem):
             return NotImplemented
         return self.type < other.type
 
-    def __eq__(self, other):
+    def __eq__(self: EI, other: EI) -> bool:
         if not isinstance(other, EventItem):
             return NotImplemented
         return self.type == other.type
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.type)
 
+
 class Shard:
-    def __init__(self, ws, client, queue_put):
-        self.ws = ws
-        self._client = client
-        self._dispatch = client.dispatch
-        self._queue_put = queue_put
-        self.loop = self._client.loop
-        self._disconnect = False
+    def __init__(self, ws: DiscordWebSocket, client: AutoShardedClient, queue_put: Callable[[EventItem], None]) -> None:
+        self.ws: DiscordWebSocket = ws
+        self._client: Client = client
+        self._dispatch: Callable[..., None] = client.dispatch
+        self._queue_put: Callable[[EventItem], None] = queue_put
+        self.loop: asyncio.AbstractEventLoop = self._client.loop
+        self._disconnect: bool = False
         self._reconnect = client._reconnect
-        self._backoff = ExponentialBackoff()
-        self._task = None
-        self._handled_exceptions = (
+        self._backoff: ExponentialBackoff = ExponentialBackoff()
+        self._task: Optional[asyncio.Task] = None
+        self._handled_exceptions: Tuple[Type[Exception], ...] = (
             OSError,
             HTTPException,
             GatewayNotFound,
@@ -101,25 +112,26 @@ class Shard:
         )
 
     @property
-    def id(self):
-        return self.ws.shard_id
+    def id(self) -> int:
+        # DiscordWebSocket.shard_id is set in the from_client classmethod
+        return self.ws.shard_id  # type: ignore
 
-    def launch(self):
+    def launch(self) -> None:
         self._task = self.loop.create_task(self.worker())
 
-    def _cancel_task(self):
+    def _cancel_task(self) -> None:
         if self._task is not None and not self._task.done():
             self._task.cancel()
 
-    async def close(self):
+    async def close(self) -> None:
         self._cancel_task()
         await self.ws.close(code=1000)
 
-    async def disconnect(self):
+    async def disconnect(self) -> None:
         await self.close()
         self._dispatch('shard_disconnect', self.id)
 
-    async def _handle_disconnect(self, e):
+    async def _handle_disconnect(self, e: Exception) -> None:
         self._dispatch('disconnect')
         self._dispatch('shard_disconnect', self.id)
         if not self._reconnect:
@@ -144,11 +156,11 @@ class Shard:
                 return
 
         retry = self._backoff.delay()
-        log.error('Attempting a reconnect for shard ID %s in %.2fs', self.id, retry, exc_info=e)
+        _log.error('Attempting a reconnect for shard ID %s in %.2fs', self.id, retry, exc_info=e)
         await asyncio.sleep(retry)
         self._queue_put(EventItem(EventType.reconnect, self, e))
 
-    async def worker(self):
+    async def worker(self) -> None:
         while not self._client.is_closed():
             try:
                 await self.ws.poll_event()
@@ -165,14 +177,19 @@ class Shard:
                 self._queue_put(EventItem(EventType.terminate, self, e))
                 break
 
-    async def reidentify(self, exc):
+    async def reidentify(self, exc: ReconnectWebSocket) -> None:
         self._cancel_task()
         self._dispatch('disconnect')
         self._dispatch('shard_disconnect', self.id)
-        log.info('Got a request to %s the websocket at Shard ID %s.', exc.op, self.id)
+        _log.info('Got a request to %s the websocket at Shard ID %s.', exc.op, self.id)
         try:
-            coro = DiscordWebSocket.from_client(self._client, resume=exc.resume, shard_id=self.id,
-                                                session=self.ws.session_id, sequence=self.ws.sequence)
+            coro = DiscordWebSocket.from_client(
+                self._client,
+                resume=exc.resume,
+                shard_id=self.id,
+                session=self.ws.session_id,
+                sequence=self.ws.sequence,
+            )
             self.ws = await asyncio.wait_for(coro, timeout=60.0)
         except self._handled_exceptions as e:
             await self._handle_disconnect(e)
@@ -183,7 +200,7 @@ class Shard:
         else:
             self.launch()
 
-    async def reconnect(self):
+    async def reconnect(self) -> None:
         self._cancel_task()
         try:
             coro = DiscordWebSocket.from_client(self._client, shard_id=self.id)
@@ -197,6 +214,7 @@ class Shard:
         else:
             self.launch()
 
+
 class ShardInfo:
     """A class that gives information and control over a specific shard.
 
@@ -215,16 +233,16 @@ class ShardInfo:
 
     __slots__ = ('_parent', 'id', 'shard_count')
 
-    def __init__(self, parent, shard_count):
-        self._parent = parent
-        self.id = parent.id
-        self.shard_count = shard_count
+    def __init__(self, parent: Shard, shard_count: Optional[int]) -> None:
+        self._parent: Shard = parent
+        self.id: int = parent.id
+        self.shard_count: Optional[int] = shard_count
 
-    def is_closed(self):
+    def is_closed(self) -> bool:
         """:class:`bool`: Whether the shard connection is currently closed."""
         return not self._parent.ws.open
 
-    async def disconnect(self):
+    async def disconnect(self) -> None:
         """|coro|
 
         Disconnects a shard. When this is called, the shard connection will no
@@ -237,7 +255,7 @@ class ShardInfo:
 
         await self._parent.disconnect()
 
-    async def reconnect(self):
+    async def reconnect(self) -> None:
         """|coro|
 
         Disconnects and then connects the shard again.
@@ -246,7 +264,7 @@ class ShardInfo:
             await self._parent.disconnect()
         await self._parent.reconnect()
 
-    async def connect(self):
+    async def connect(self) -> None:
         """|coro|
 
         Connects a shard. If the shard is already connected this does nothing.
@@ -257,11 +275,11 @@ class ShardInfo:
         await self._parent.reconnect()
 
     @property
-    def latency(self):
+    def latency(self) -> float:
         """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds for this shard."""
         return self._parent.ws.latency
 
-    def is_ws_ratelimited(self):
+    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
@@ -271,6 +289,7 @@ class ShardInfo:
         """
         return self._parent.ws.is_ratelimited()
 
+
 class AutoShardedClient(Client):
     """A client similar to :class:`Client` except it handles the complications
     of sharding for the user into a more manageable and transparent single
@@ -297,9 +316,13 @@ class AutoShardedClient(Client):
     shard_ids: Optional[List[:class:`int`]]
         An optional list of shard_ids to launch the shards with.
     """
-    def __init__(self, *args, loop=None, **kwargs):
+
+    if TYPE_CHECKING:
+        _connection: AutoShardedConnectionState
+
+    def __init__(self, *args: Any, loop: Optional[asyncio.AbstractEventLoop] = None, **kwargs: Any) -> None:
         kwargs.pop('shard_id', None)
-        self.shard_ids = kwargs.pop('shard_ids', None)
+        self.shard_ids: Optional[List[int]] = kwargs.pop('shard_ids', None)
         super().__init__(*args, loop=loop, **kwargs)
 
         if self.shard_ids is not None:
@@ -315,18 +338,24 @@ class AutoShardedClient(Client):
         self._connection._get_client = lambda: self
         self.__queue = asyncio.PriorityQueue()
 
-    def _get_websocket(self, guild_id=None, *, shard_id=None):
+    def _get_websocket(self, guild_id: Optional[int] = None, *, shard_id: Optional[int] = None) -> DiscordWebSocket:
         if shard_id is None:
-            shard_id = (guild_id >> 22) % self.shard_count
+            # guild_id won't be None if shard_id is None and shard_count won't be None here
+            shard_id = (guild_id >> 22) % self.shard_count  # type: ignore
         return self.__shards[shard_id].ws
 
-    def _get_state(self, **options):
-        return AutoShardedConnectionState(dispatch=self.dispatch,
-                                          handlers=self._handlers,
-                                          hooks=self._hooks, http=self.http, loop=self.loop, **options)
+    def _get_state(self, **options: Any) -> AutoShardedConnectionState:
+        return AutoShardedConnectionState(
+            dispatch=self.dispatch,
+            handlers=self._handlers,
+            hooks=self._hooks,
+            http=self.http,
+            loop=self.loop,
+            **options,
+        )
 
     @property
-    def latency(self):
+    def latency(self) -> float:
         """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
 
         This operates similarly to :meth:`Client.latency` except it uses the average
@@ -338,14 +367,14 @@ class AutoShardedClient(Client):
         return sum(latency for _, latency in self.latencies) / len(self.__shards)
 
     @property
-    def latencies(self):
+    def latencies(self) -> List[Tuple[int, float]]:
         """List[Tuple[:class:`int`, :class:`float`]]: A list of latencies between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
 
         This returns a list of tuples with elements ``(shard_id, latency)``.
         """
         return [(shard_id, shard.ws.latency) for shard_id, shard in self.__shards.items()]
 
-    def get_shard(self, shard_id):
+    def get_shard(self, shard_id: int) -> Optional[ShardInfo]:
         """Optional[:class:`ShardInfo`]: Gets the shard information at a given shard ID or ``None`` if not found."""
         try:
             parent = self.__shards[shard_id]
@@ -355,52 +384,16 @@ class AutoShardedClient(Client):
             return ShardInfo(parent, self.shard_count)
 
     @property
-    def shards(self):
+    def shards(self) -> Dict[int, ShardInfo]:
         """Mapping[int, :class:`ShardInfo`]: Returns a mapping of shard IDs to their respective info object."""
-        return { shard_id: ShardInfo(parent, self.shard_count) for shard_id, parent in self.__shards.items() }
+        return {shard_id: ShardInfo(parent, self.shard_count) for shard_id, parent in self.__shards.items()}
 
-    @utils.deprecated('Guild.chunk')
-    async def request_offline_members(self, *guilds):
-        r"""|coro|
-
-        Requests previously offline members from the guild to be filled up
-        into the :attr:`Guild.members` cache. This function is usually not
-        called. It should only be used if you have the ``fetch_offline_members``
-        parameter set to ``False``.
-
-        When the client logs on and connects to the websocket, Discord does
-        not provide the library with offline members if the number of members
-        in the guild is larger than 250. You can check if a guild is large
-        if :attr:`Guild.large` is ``True``.
-
-        .. warning::
-
-            This method is deprecated. Use :meth:`Guild.chunk` instead.
-
-        Parameters
-        -----------
-        \*guilds: :class:`Guild`
-            An argument list of guilds to request offline members for.
-
-        Raises
-        -------
-        InvalidArgument
-            If any guild is unavailable in the collection.
-        """
-        if any(g.unavailable for g in guilds):
-            raise InvalidArgument('An unavailable or non-large guild was passed.')
-
-        _guilds = sorted(guilds, key=lambda g: g.shard_id)
-        for shard_id, sub_guilds in itertools.groupby(_guilds, key=lambda g: g.shard_id):
-            for guild in sub_guilds:
-                await self._connection.chunk_guild(guild)
-
-    async def launch_shard(self, gateway, shard_id, *, initial=False):
+    async def launch_shard(self, gateway: str, shard_id: int, *, initial: bool = False) -> None:
         try:
             coro = DiscordWebSocket.from_client(self, initial=initial, gateway=gateway, shard_id=shard_id)
             ws = await asyncio.wait_for(coro, timeout=180.0)
         except Exception:
-            log.exception('Failed to connect for shard_id: %s. Retrying...', shard_id)
+            _log.exception('Failed to connect for shard_id: %s. Retrying...', shard_id)
             await asyncio.sleep(5.0)
             return await self.launch_shard(gateway, shard_id)
 
@@ -408,7 +401,7 @@ class AutoShardedClient(Client):
         self.__shards[shard_id] = ret = Shard(ws, self, self.__queue.put_nowait)
         ret.launch()
 
-    async def launch_shards(self):
+    async def launch_shards(self) -> None:
         if self.shard_count is None:
             self.shard_count, gateway = await self.http.get_bot_gateway()
         else:
@@ -425,7 +418,7 @@ class AutoShardedClient(Client):
 
         self._connection.shards_launched.set()
 
-    async def connect(self, *, reconnect=True):
+    async def connect(self, *, reconnect: bool = True) -> None:
         self._reconnect = reconnect
         await self.launch_shards()
 
@@ -449,7 +442,7 @@ class AutoShardedClient(Client):
             elif item.type == EventType.clean_close:
                 return
 
-    async def close(self):
+    async def close(self) -> None:
         """|coro|
 
         Closes the connection to Discord.
@@ -461,7 +454,7 @@ class AutoShardedClient(Client):
 
         for vc in self.voice_clients:
             try:
-                await vc.disconnect()
+                await vc.disconnect(force=True)
             except Exception:
                 pass
 
@@ -472,7 +465,13 @@ class AutoShardedClient(Client):
         await self.http.close()
         self.__queue.put_nowait(EventItem(EventType.clean_close, None, None))
 
-    async def change_presence(self, *, activity=None, status=None, afk=False, shard_id=None):
+    async def change_presence(
+        self,
+        *,
+        activity: Optional[BaseActivity] = None,
+        status: Optional[Status] = None,
+        shard_id: int = None,
+    ) -> None:
         """|coro|
 
         Changes the client's presence.
@@ -482,6 +481,9 @@ class AutoShardedClient(Client):
             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`]
@@ -489,10 +491,6 @@ class AutoShardedClient(Client):
         status: Optional[:class:`Status`]
             Indicates what status to change to. If ``None``, then
             :attr:`Status.online` is used.
-        afk: :class:`bool`
-            Indicates if you are going AFK. This allows the discord
-            client to know how to handle push notifications better
-            for you in case you are actually idle and not lying.
         shard_id: Optional[:class:`int`]
             The shard_id to change the presence to. If not specified
             or ``None``, then it will change the presence of every
@@ -505,23 +503,23 @@ class AutoShardedClient(Client):
         """
 
         if status is None:
-            status = 'online'
+            status_value = 'online'
             status_enum = Status.online
         elif status is Status.offline:
-            status = 'invisible'
+            status_value = 'invisible'
             status_enum = Status.offline
         else:
             status_enum = status
-            status = str(status)
+            status_value = str(status)
 
         if shard_id is None:
             for shard in self.__shards.values():
-                await shard.ws.change_presence(activity=activity, status=status, afk=afk)
+                await shard.ws.change_presence(activity=activity, status=status_value)
 
             guilds = self._connection.guilds
         else:
             shard = self.__shards[shard_id]
-            await shard.ws.change_presence(activity=activity, status=status, afk=afk)
+            await shard.ws.change_presence(activity=activity, status=status_value)
             guilds = [g for g in self._connection.guilds if g.shard_id == shard_id]
 
         activities = () if activity is None else (activity,)
@@ -530,10 +528,11 @@ class AutoShardedClient(Client):
             if me is None:
                 continue
 
-            me.activities = activities
+            # Member.activities is typehinted as Tuple[ActivityType, ...], we may be setting it as Tuple[BaseActivity, ...]
+            me.activities = activities  # type: ignore
             me.status = status_enum
 
-    def is_ws_ratelimited(self):
+    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

discord/stage_instance.py

@@ -0,0 +1,180 @@
+"""
+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
+
+from typing import Optional, TYPE_CHECKING
+
+from .utils import MISSING, cached_slot_property
+from .mixins import Hashable
+from .errors import InvalidArgument
+from .enums import StagePrivacyLevel, try_enum
+
+__all__ = (
+    'StageInstance',
+)
+
+if TYPE_CHECKING:
+    from .types.channel import StageInstance as StageInstancePayload
+    from .state import ConnectionState
+    from .channel import StageChannel
+    from .guild import Guild
+
+
+class StageInstance(Hashable):
+    """Represents a stage instance of a stage channel in a guild.
+
+    .. versionadded:: 2.0
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two stage instances are equal.
+
+        .. describe:: x != y
+
+            Checks if two stage instances are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the stage instance's hash.
+
+        .. describe:: int(x)
+
+            Returns the stage instance's ID.
+
+    Attributes
+    -----------
+    id: :class:`int`
+        The stage instance's ID.
+    guild: :class:`Guild`
+        The guild that the stage instance is running in.
+    channel_id: :class:`int`
+        The ID of the channel that the stage instance is running in.
+    topic: :class:`str`
+        The topic of the stage instance.
+    privacy_level: :class:`StagePrivacyLevel`
+        The privacy level of the stage instance.
+    discoverable_disabled: :class:`bool`
+        Whether discoverability for the stage instance is disabled.
+    """
+
+    __slots__ = (
+        '_state',
+        'id',
+        'guild',
+        'channel_id',
+        'topic',
+        'privacy_level',
+        'discoverable_disabled',
+        '_cs_channel',
+    )
+
+    def __init__(self, *, state: ConnectionState, guild: Guild, data: StageInstancePayload) -> None:
+        self._state = state
+        self.guild = guild
+        self._update(data)
+
+    def _update(self, data: StageInstancePayload):
+        self.id: int = int(data['id'])
+        self.channel_id: int = int(data['channel_id'])
+        self.topic: str = data['topic']
+        self.privacy_level: StagePrivacyLevel = try_enum(StagePrivacyLevel, data['privacy_level'])
+        self.discoverable_disabled: bool = data.get('discoverable_disabled', False)
+
+    def __repr__(self) -> str:
+        return f'<StageInstance id={self.id} guild={self.guild!r} channel_id={self.channel_id} topic={self.topic!r}>'
+
+    @cached_slot_property('_cs_channel')
+    def channel(self) -> Optional[StageChannel]:
+        """Optional[:class:`StageChannel`]: The channel that stage instance is running in."""
+        # the returned channel will always be a StageChannel or None
+        return self._state.get_channel(self.channel_id) # type: ignore
+
+    def is_public(self) -> bool:
+        return self.privacy_level is StagePrivacyLevel.public
+
+    async def edit(self, *, topic: str = MISSING, privacy_level: StagePrivacyLevel = MISSING, reason: Optional[str] = None) -> None:
+        """|coro|
+
+        Edits the stage instance.
+
+        You must have the :attr:`~Permissions.manage_channels` permission to
+        use this.
+
+        Parameters
+        -----------
+        topic: :class:`str`
+            The stage instance's new topic.
+        privacy_level: :class:`StagePrivacyLevel`
+            The stage instance's new privacy level.
+        reason: :class:`str`
+            The reason the stage instance was edited. Shows up on the audit log.
+
+        Raises
+        ------
+        InvalidArgument
+            If the ``privacy_level`` parameter is not the proper type.
+        Forbidden
+            You do not have permissions to edit the stage instance.
+        HTTPException
+            Editing a stage instance failed.
+        """
+
+        payload = {}
+
+        if topic is not MISSING:
+            payload['topic'] = topic
+
+        if privacy_level is not MISSING:
+            if not isinstance(privacy_level, StagePrivacyLevel):
+                raise InvalidArgument('privacy_level field must be of type PrivacyLevel')
+
+            payload['privacy_level'] = privacy_level.value
+
+        if payload:
+            await self._state.http.edit_stage_instance(self.channel_id, **payload, reason=reason)
+
+    async def delete(self, *, reason: Optional[str] = None) -> None:
+        """|coro|
+
+        Deletes the stage instance.
+
+        You must have the :attr:`~Permissions.manage_channels` permission to
+        use this.
+
+        Parameters
+        -----------
+        reason: :class:`str`
+            The reason the stage instance was deleted. Shows up on the audit log.
+
+        Raises
+        ------
+        Forbidden
+            You do not have permissions to delete the stage instance.
+        HTTPException
+            Deleting the stage instance failed.
+        """
+        await self._state.http.delete_stage_instance(self.channel_id, reason=reason)

discord/sticker.py

@@ -22,17 +22,226 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+from typing import Literal, TYPE_CHECKING, List, Optional, Tuple, Type, Union
+import unicodedata
+
 from .mixins import Hashable
-from .asset import Asset
-from .utils import snowflake_time
-from .enums import StickerType, try_enum
+from .asset import Asset, AssetMixin
+from .utils import cached_slot_property, find, snowflake_time, get, MISSING
+from .errors import InvalidData
+from .enums import StickerType, StickerFormatType, try_enum
 
 __all__ = (
+    'StickerPack',
+    'StickerItem',
     'Sticker',
+    'StandardSticker',
+    'GuildSticker',
 )
 
-class Sticker(Hashable):
-    """Represents a sticker
+if TYPE_CHECKING:
+    import datetime
+    from .state import ConnectionState
+    from .user import User
+    from .guild import Guild
+    from .types.sticker import (
+        StickerPack as StickerPackPayload,
+        StickerItem as StickerItemPayload,
+        Sticker as StickerPayload,
+        StandardSticker as StandardStickerPayload,
+        GuildSticker as GuildStickerPayload,
+        ListPremiumStickerPacks as ListPremiumStickerPacksPayload,
+        EditGuildSticker,
+    )
+
+
+class StickerPack(Hashable):
+    """Represents a sticker pack.
+
+    .. versionadded:: 2.0
+
+    .. container:: operations
+
+        .. describe:: str(x)
+
+            Returns the name of the sticker pack.
+
+        .. describe:: hash(x)
+
+            Returns the hash of the sticker pack.
+
+        .. describe:: int(x)
+
+            Returns the ID of the sticker pack.
+
+        .. describe:: x == y
+
+           Checks if the sticker pack is equal to another sticker pack.
+
+        .. describe:: x != y
+
+           Checks if the sticker pack is not equal to another sticker pack.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The name of the sticker pack.
+    description: :class:`str`
+        The description of the sticker pack.
+    id: :class:`int`
+        The id of the sticker pack.
+    stickers: List[:class:`StandardSticker`]
+        The stickers of this sticker pack.
+    sku_id: :class:`int`
+        The SKU ID of the sticker pack.
+    cover_sticker_id: :class:`int`
+         The ID of the sticker used for the cover of the sticker pack.
+    cover_sticker: :class:`StandardSticker`
+        The sticker used for the cover of the sticker pack.
+    """
+
+    __slots__ = (
+        '_state',
+        'id',
+        'stickers',
+        'name',
+        'sku_id',
+        'cover_sticker_id',
+        'cover_sticker',
+        'description',
+        '_banner',
+    )
+
+    def __init__(self, *, state: ConnectionState, data: StickerPackPayload) -> None:
+        self._state: ConnectionState = state
+        self._from_data(data)
+
+    def _from_data(self, data: StickerPackPayload) -> None:
+        self.id: int = int(data['id'])
+        stickers = data['stickers']
+        self.stickers: List[StandardSticker] = [StandardSticker(state=self._state, data=sticker) for sticker in stickers]
+        self.name: str = data['name']
+        self.sku_id: int = int(data['sku_id'])
+        self.cover_sticker_id: int = int(data['cover_sticker_id'])
+        self.cover_sticker: StandardSticker = get(self.stickers, id=self.cover_sticker_id) # type: ignore
+        self.description: str = data['description']
+        self._banner: int = int(data['banner_asset_id'])
+
+    @property
+    def banner(self) -> Asset:
+        """:class:`Asset`: The banner asset of the sticker pack."""
+        return Asset._from_sticker_banner(self._state, self._banner)
+
+    def __repr__(self) -> str:
+        return f'<StickerPack id={self.id} name={self.name!r} description={self.description!r}>'
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class _StickerTag(Hashable, AssetMixin):
+    __slots__ = ()
+
+    id: int
+    format: StickerFormatType
+
+    async def read(self) -> bytes:
+        """|coro|
+
+        Retrieves the content of this sticker as a :class:`bytes` object.
+
+        .. note::
+
+            Stickers that use the :attr:`StickerFormatType.lottie` format cannot be read.
+
+        Raises
+        ------
+        HTTPException
+            Downloading the asset failed.
+        NotFound
+            The asset was deleted.
+        TypeError
+            The sticker is a lottie type.
+
+        Returns
+        -------
+        :class:`bytes`
+            The content of the asset.
+        """
+        if self.format is StickerFormatType.lottie:
+            raise TypeError('Cannot read stickers of format "lottie".')
+        return await super().read()
+
+
+class StickerItem(_StickerTag):
+    """Represents a sticker item.
+
+    .. versionadded:: 2.0
+
+    .. container:: operations
+
+        .. describe:: str(x)
+
+            Returns the name of the sticker item.
+
+        .. describe:: x == y
+
+           Checks if the sticker item is equal to another sticker item.
+
+        .. describe:: x != y
+
+           Checks if the sticker item is not equal to another sticker item.
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The sticker's name.
+    id: :class:`int`
+        The id of the sticker.
+    format: :class:`StickerFormatType`
+        The format for the sticker's image.
+    url: :class:`str`
+        The URL for the sticker's image.
+    """
+
+    __slots__ = ('_state', 'name', 'id', 'format', 'url')
+
+    def __init__(self, *, state: ConnectionState, data: StickerItemPayload):
+        self._state: ConnectionState = state
+        self.name: str = data['name']
+        self.id: int = int(data['id'])
+        self.format: StickerFormatType = try_enum(StickerFormatType, data['format_type'])
+        self.url: str = f'{Asset.BASE}/stickers/{self.id}.{self.format.file_extension}'
+
+    def __repr__(self) -> str:
+        return f'<StickerItem id={self.id} name={self.name!r} format={self.format}>'
+
+    def __str__(self) -> str:
+        return self.name
+
+    async def fetch(self) -> Union[Sticker, StandardSticker, GuildSticker]:
+        """|coro|
+
+        Attempts to retrieve the full sticker data of the sticker item.
+
+        Raises
+        --------
+        HTTPException
+            Retrieving the sticker failed.
+
+        Returns
+        --------
+        Union[:class:`StandardSticker`, :class:`GuildSticker`]
+            The retrieved sticker.
+        """
+        data: StickerPayload = await self._state.http.get_sticker(self.id)
+        cls, _ = _sticker_factory(data['type'])  # type: ignore
+        return cls(state=self._state, data=data)
+
+
+class Sticker(_StickerTag):
+    """Represents a sticker.
 
     .. versionadded:: 1.6
 
@@ -40,102 +249,283 @@ class Sticker(Hashable):
 
         .. describe:: str(x)
 
-            Returns the name of the sticker
+            Returns the name of the sticker.
 
         .. describe:: x == y
 
-           Checks if the sticker is equal to another sticker
+           Checks if the sticker is equal to another sticker.
 
         .. describe:: x != y
 
-           Checks if the sticker is not equal to another sticker
+           Checks if the sticker is not equal to another sticker.
 
     Attributes
     ----------
     name: :class:`str`
-        The sticker's name
+        The sticker's name.
     id: :class:`int`
-        The id of the sticker
+        The id of the sticker.
     description: :class:`str`
-        The description of the sticker
+        The description of the sticker.
     pack_id: :class:`int`
-        The id of the sticker's pack
-    format: :class:`StickerType`
-        The format for the sticker's image
-    image: :class:`str`
-        The sticker's image
-    tags: List[:class:`str`]
-        A list of tags for the sticker
-    preview_image: Optional[:class:`str`]
-        The sticker's preview asset hash
+        The id of the sticker's pack.
+    format: :class:`StickerFormatType`
+        The format for the sticker's image.
+    url: :class:`str`
+        The URL for the sticker's image.
     """
-    __slots__ = ('_state', 'id', 'name', 'description', 'pack_id', 'format', 'image', 'tags', 'preview_image')
 
-    def __init__(self, *, state, data):
-        self._state = state
-        self.id = int(data['id'])
-        self.name = data['name']
-        self.description = data['description']
-        self.pack_id = int(data['pack_id'])
-        self.format = try_enum(StickerType, data['format_type'])
-        self.image = data['asset']
+    __slots__ = ('_state', 'id', 'name', 'description', 'format', 'url')
 
-        try:
-            self.tags = [tag.strip() for tag in data['tags'].split(',')]
-        except KeyError:
-            self.tags = []
+    def __init__(self, *, state: ConnectionState, data: StickerPayload) -> None:
+        self._state: ConnectionState = state
+        self._from_data(data)
 
-        self.preview_image = data.get('preview_asset')
+    def _from_data(self, data: StickerPayload) -> None:
+        self.id: int = int(data['id'])
+        self.name: str = data['name']
+        self.description: str = data['description']
+        self.format: StickerFormatType = try_enum(StickerFormatType, data['format_type'])
+        self.url: str = f'{Asset.BASE}/stickers/{self.id}.{self.format.file_extension}'
 
-    def __repr__(self):
-        return '<{0.__class__.__name__} id={0.id} name={0.name!r}>'.format(self)
+    def __repr__(self) -> str:
+        return f'<Sticker id={self.id} name={self.name!r}>'
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name
 
     @property
-    def created_at(self):
+    def created_at(self) -> datetime.datetime:
         """:class:`datetime.datetime`: Returns the sticker's creation time in UTC."""
         return snowflake_time(self.id)
 
-    @property
-    def image_url(self):
-        """Returns an :class:`Asset` for the sticker's image.
 
-        .. note::
-            This will return ``None`` if the format is ``StickerType.lottie``
+class StandardSticker(Sticker):
+    """Represents a sticker that is found in a standard sticker pack.
+
+    .. versionadded:: 2.0
+
+    .. container:: operations
+
+        .. describe:: str(x)
+
+            Returns the name of the sticker.
+
+        .. describe:: x == y
+
+           Checks if the sticker is equal to another sticker.
+
+        .. describe:: x != y
+
+           Checks if the sticker is not equal to another sticker.
+
+    Attributes
+    ----------
+    name: :class:`str`
+        The sticker's name.
+    id: :class:`int`
+        The id of the sticker.
+    description: :class:`str`
+        The description of the sticker.
+    pack_id: :class:`int`
+        The id of the sticker's pack.
+    format: :class:`StickerFormatType`
+        The format for the sticker's image.
+    tags: List[:class:`str`]
+        A list of tags for the sticker.
+    sort_value: :class:`int`
+        The sticker's sort order within its pack.
+    """
+
+    __slots__ = ('sort_value', 'pack_id', 'type', 'tags')
+
+    def _from_data(self, data: StandardStickerPayload) -> None:
+        super()._from_data(data)
+        self.sort_value: int = data['sort_value']
+        self.pack_id: int = int(data['pack_id'])
+        self.type: StickerType = StickerType.standard
+
+        try:
+            self.tags: List[str] = [tag.strip() for tag in data['tags'].split(',')]
+        except KeyError:
+            self.tags = []
+
+    def __repr__(self) -> str:
+        return f'<StandardSticker id={self.id} name={self.name!r} pack_id={self.pack_id}>'
+
+    async def pack(self) -> StickerPack:
+        """|coro|
+
+        Retrieves the sticker pack that this sticker belongs to.
+
+        Raises
+        --------
+        InvalidData
+            The corresponding sticker pack was not found.
+        HTTPException
+            Retrieving the sticker pack failed.
 
         Returns
-        -------
-        Optional[:class:`Asset`]
-            The resulting CDN asset.
+        --------
+        :class:`StickerPack`
+            The retrieved sticker pack.
         """
-        return self.image_url_as()
+        data: ListPremiumStickerPacksPayload = await self._state.http.list_premium_sticker_packs()
+        packs = data['sticker_packs']
+        pack = find(lambda d: int(d['id']) == self.pack_id, packs)
 
-    def image_url_as(self, *, size=1024):
-        """Optionally returns an :class:`Asset` for the sticker's image.
+        if pack:
+            return StickerPack(state=self._state, data=pack)
+        raise InvalidData(f'Could not find corresponding sticker pack for {self!r}')
 
-        The size must be a power of 2 between 16 and 4096.
 
-        .. note::
-            This will return ``None`` if the format is ``StickerType.lottie``.
+class GuildSticker(Sticker):
+    """Represents a sticker that belongs to a guild.
+
+    .. versionadded:: 2.0
+
+    .. container:: operations
+
+        .. describe:: str(x)
+
+            Returns the name of the sticker.
+
+        .. describe:: x == y
+
+           Checks if the sticker is equal to another sticker.
+
+        .. describe:: x != y
+
+           Checks if the sticker is not equal to another sticker.
+
+    Attributes
+    ----------
+    name: :class:`str`
+        The sticker's name.
+    id: :class:`int`
+        The id of the sticker.
+    description: :class:`str`
+        The description of the sticker.
+    format: :class:`StickerFormatType`
+        The format for the sticker's image.
+    available: :class:`bool`
+        Whether this sticker is available for use.
+    guild_id: :class:`int`
+        The ID of the guild that this sticker is from.
+    user: Optional[:class:`User`]
+        The user that created this sticker. This can only be retrieved using :meth:`Guild.fetch_sticker` and
+        having the :attr:`~Permissions.manage_emojis_and_stickers` permission.
+    emoji: :class:`str`
+        The name of a unicode emoji that represents this sticker.
+    """
+
+    __slots__ = ('available', 'guild_id', 'user', 'emoji', 'type', '_cs_guild')
+
+    def _from_data(self, data: GuildStickerPayload) -> None:
+        super()._from_data(data)
+        self.available: bool = data['available']
+        self.guild_id: int = int(data['guild_id'])
+        user = data.get('user')
+        self.user: Optional[User] = self._state.store_user(user) if user else None
+        self.emoji: str = data['tags']
+        self.type: StickerType = StickerType.guild
+
+    def __repr__(self) -> str:
+        return f'<GuildSticker name={self.name!r} id={self.id} guild_id={self.guild_id} user={self.user!r}>'
+
+    @cached_slot_property('_cs_guild')
+    def guild(self) -> Optional[Guild]:
+        """Optional[:class:`Guild`]: The guild that this sticker is from.
+        Could be ``None`` if the bot is not in the guild.
+
+        .. versionadded:: 2.0
+        """
+        return self._state._get_guild(self.guild_id)
+
+    async def edit(
+        self,
+        *,
+        name: str = MISSING,
+        description: str = MISSING,
+        emoji: str = MISSING,
+        reason: Optional[str] = None,
+    ) -> GuildSticker:
+        """|coro|
+
+        Edits a :class:`GuildSticker` for the guild.
 
         Parameters
         -----------
-        size: :class:`int`
-            The size of the image to display.
+        name: :class:`str`
+            The sticker's new name. Must be at least 2 characters.
+        description: Optional[:class:`str`]
+            The sticker's new description. Can be ``None``.
+        emoji: :class:`str`
+            The name of a unicode emoji that represents the sticker's expression.
+        reason: :class:`str`
+            The reason for editing this sticker. Shows up on the audit log.
 
         Raises
-        ------
-        InvalidArgument
-            Invalid ``size``.
+        -------
+        Forbidden
+            You are not allowed to edit stickers.
+        HTTPException
+            An error occurred editing the sticker.
 
         Returns
-        -------
-        Optional[:class:`Asset`]
-            The resulting CDN asset or ``None``.
+        --------
+        :class:`GuildSticker`
+            The newly modified sticker.
         """
-        if self.format is StickerType.lottie:
-            return None
+        payload: EditGuildSticker = {}
 
-        return Asset._from_sticker_url(self._state, self, size=size)
+        if name is not MISSING:
+            payload['name'] = name
+
+        if description is not MISSING:
+            payload['description'] = description
+
+        if emoji is not MISSING:
+            try:
+                emoji = unicodedata.name(emoji)
+            except TypeError:
+                pass
+            else:
+                emoji = emoji.replace(' ', '_')
+
+            payload['tags'] = emoji
+
+        data: GuildStickerPayload = await self._state.http.modify_guild_sticker(self.guild_id, self.id, payload, reason)
+        return GuildSticker(state=self._state, data=data)
+
+    async def delete(self, *, reason: Optional[str] = None) -> None:
+        """|coro|
+
+        Deletes the custom :class:`Sticker` from the guild.
+
+        You must have :attr:`~Permissions.manage_emojis_and_stickers` permission to
+        do this.
+
+        Parameters
+        -----------
+        reason: Optional[:class:`str`]
+            The reason for deleting this sticker. Shows up on the audit log.
+
+        Raises
+        -------
+        Forbidden
+            You are not allowed to delete stickers.
+        HTTPException
+            An error occurred deleting the sticker.
+        """
+        await self._state.http.delete_guild_sticker(self.guild_id, self.id, reason)
+
+
+def _sticker_factory(sticker_type: Literal[1, 2]) -> Tuple[Type[Union[StandardSticker, GuildSticker, Sticker]], StickerType]:
+    value = try_enum(StickerType, sticker_type)
+    if value == StickerType.standard:
+        return StandardSticker, value
+    elif value == StickerType.guild:
+        return GuildSticker, value
+    else:
+        return Sticker, value

discord/team.py

@@ -22,16 +22,29 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
 from . import utils
 from .user import BaseUser
 from .asset import Asset
 from .enums import TeamMembershipState, try_enum
 
+from typing import TYPE_CHECKING, Optional, List
+
+if TYPE_CHECKING:
+    from .state import ConnectionState
+
+    from .types.team import (
+        Team as TeamPayload,
+        TeamMember as TeamMemberPayload,
+    )
+
 __all__ = (
     'Team',
     'TeamMember',
 )
 
+
 class Team:
     """Represents an application team for a bot provided by Discord.
 
@@ -41,8 +54,6 @@ class Team:
         The team ID.
     name: :class:`str`
         The team name
-    icon: Optional[:class:`str`]
-        The icon hash, if it exists.
     owner_id: :class:`int`
         The team's owner ID.
     members: List[:class:`TeamMember`]
@@ -50,61 +61,34 @@ class Team:
 
         .. versionadded:: 1.3
     """
-    __slots__ = ('_state', 'id', 'name', 'icon', 'owner_id', 'members')
 
-    def __init__(self, state, data):
-        self._state = state
+    __slots__ = ('_state', 'id', 'name', '_icon', 'owner_id', 'members')
 
-        self.id = utils._get_as_snowflake(data, 'id')
-        self.name = data['name']
-        self.icon = data['icon']
-        self.owner_id = utils._get_as_snowflake(data, 'owner_user_id')
-        self.members = [TeamMember(self, self._state, member) for member in data['members']]
+    def __init__(self, state: ConnectionState, data: TeamPayload):
+        self._state: ConnectionState = state
 
-    def __repr__(self):
-        return '<{0.__class__.__name__} id={0.id} name={0.name}>'.format(self)
+        self.id: int = int(data['id'])
+        self.name: str = data['name']
+        self._icon: Optional[str] = data['icon']
+        self.owner_id: Optional[int] = utils._get_as_snowflake(data, 'owner_user_id')
+        self.members: List[TeamMember] = [TeamMember(self, self._state, member) for member in data['members']]
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__} id={self.id} name={self.name}>'
 
     @property
-    def icon_url(self):
-        """:class:`.Asset`: Retrieves the team's icon asset.
-
-        This is equivalent to calling :meth:`icon_url_as` with
-        the default parameters ('webp' format and a size of 1024).
-        """
-        return self.icon_url_as()
-
-    def icon_url_as(self, *, format='webp', size=1024):
-        """Returns an :class:`Asset` for the icon the team has.
-
-        The format must be one of 'webp', 'jpeg', 'jpg' or 'png'.
-        The size must be a power of 2 between 16 and 4096.
-
-        .. versionadded:: 2.0
-
-        Parameters
-        -----------
-        format: :class:`str`
-            The format to attempt to convert the icon to. Defaults to 'webp'.
-        size: :class:`int`
-            The size of the image to display.
-
-        Raises
-        ------
-        InvalidArgument
-            Bad image format passed to ``format`` or invalid ``size``.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
-        """
-        return Asset._from_icon(self._state, self, 'team', format=format, size=size)
+    def icon(self) -> Optional[Asset]:
+        """Optional[:class:`.Asset`]: Retrieves the team's icon asset, if any."""
+        if self._icon is None:
+            return None
+        return Asset._from_icon(self._state, self.id, self._icon, path='team')
 
     @property
-    def owner(self):
+    def owner(self) -> Optional[TeamMember]:
         """Optional[:class:`TeamMember`]: The team's owner."""
         return utils.get(self.members, id=self.owner_id)
 
+
 class TeamMember(BaseUser):
     """Represents a team member in a team.
 
@@ -145,14 +129,17 @@ class TeamMember(BaseUser):
     membership_state: :class:`TeamMembershipState`
         The membership state of the member (e.g. invited or accepted)
     """
-    __slots__ = BaseUser.__slots__ + ('team', 'membership_state', 'permissions')
 
-    def __init__(self, team, state, data):
-        self.team = team
-        self.membership_state = try_enum(TeamMembershipState, data['membership_state'])
-        self.permissions = data['permissions']
+    __slots__ = ('team', 'membership_state', 'permissions')
+
+    def __init__(self, team: Team, state: ConnectionState, data: TeamMemberPayload):
+        self.team: Team = team
+        self.membership_state: TeamMembershipState = try_enum(TeamMembershipState, data['membership_state'])
+        self.permissions: List[str] = data['permissions']
         super().__init__(state=state, data=data['user'])
 
-    def __repr__(self):
-        return '<{0.__class__.__name__} id={0.id} name={0.name!r} ' \
-               'discriminator={0.discriminator!r} membership_state={0.membership_state!r}>'.format(self)
+    def __repr__(self) -> str:
+        return (
+            f'<{self.__class__.__name__} id={self.id} name={self.name!r} '
+            f'discriminator={self.discriminator!r} membership_state={self.membership_state!r}>'
+        )

discord/template.py

@@ -22,7 +22,10 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
-from .utils import parse_time, _get_as_snowflake, _bytes_to_base64_data
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+from .utils import parse_time, _get_as_snowflake, _bytes_to_base64_data, MISSING
 from .enums import VoiceRegion
 from .guild import Guild
 
@@ -30,12 +33,20 @@ __all__ = (
     'Template',
 )
 
+if TYPE_CHECKING:
+    import datetime
+    from .types.template import Template as TemplatePayload
+    from .state import ConnectionState
+    from .user import User
+
+
 class _FriendlyHttpAttributeErrorHelper:
     __slots__ = ()
 
     def __getattr__(self, attr):
         raise AttributeError('PartialTemplateState does not support http methods.')
 
+
 class _PartialTemplateState:
     def __init__(self, *, state):
         self.__state = state
@@ -66,12 +77,16 @@ class _PartialTemplateState:
     def _get_message(self, id):
         return None
 
-    async def query_members(self, **kwargs):
+    def _get_guild(self, id):
+        return self.__state._get_guild(id)
+
+    async def query_members(self, **kwargs: Any):
         return []
 
     def __getattr__(self, attr):
         raise AttributeError(f'PartialTemplateState does not support {attr!r}.')
 
+
 class Template:
     """Represents a Discord template.
 
@@ -96,40 +111,62 @@ class Template:
         This is referred to as "last synced" in the official Discord client.
     source_guild: :class:`Guild`
         The source guild.
+    is_dirty: Optional[:class:`bool`]
+        Whether the template has unsynced changes.
+
+        .. versionadded:: 2.0
     """
 
-    def __init__(self, *, state, data):
+    __slots__ = (
+        'code',
+        'uses',
+        'name',
+        'description',
+        'creator',
+        'created_at',
+        'updated_at',
+        'source_guild',
+        'is_dirty',
+        '_state',
+    )
+
+    def __init__(self, *, state: ConnectionState, data: TemplatePayload) -> None:
         self._state = state
         self._store(data)
 
-    def _store(self, data):
-        self.code = data['code']
-        self.uses = data['usage_count']
-        self.name =  data['name']
-        self.description = data['description']
+    def _store(self, data: TemplatePayload) -> None:
+        self.code: str = data['code']
+        self.uses: int = data['usage_count']
+        self.name: str = data['name']
+        self.description: Optional[str] = data['description']
         creator_data = data.get('creator')
-        self.creator = None if creator_data is None else self._state.store_user(creator_data)
+        self.creator: Optional[User] = None if creator_data is None else self._state.create_user(creator_data)
 
-        self.created_at = parse_time(data.get('created_at'))
-        self.updated_at = parse_time(data.get('updated_at'))
+        self.created_at: Optional[datetime.datetime] = parse_time(data.get('created_at'))
+        self.updated_at: Optional[datetime.datetime] = parse_time(data.get('updated_at'))
 
-        id = _get_as_snowflake(data, 'source_guild_id')
-
-        guild = self._state._get_guild(id)
+        guild_id = int(data['source_guild_id'])
+        guild: Optional[Guild] = self._state._get_guild(guild_id)
 
+        self.source_guild: Guild
         if guild is None:
             source_serialised = data['serialized_source_guild']
-            source_serialised['id'] = id
+            source_serialised['id'] = guild_id
             state = _PartialTemplateState(state=self._state)
-            guild = Guild(data=source_serialised, state=state)
+            # Guild expects a ConnectionState, we're passing a _PartialTemplateState
+            self.source_guild = Guild(data=source_serialised, state=state)  # type: ignore
+        else:
+            self.source_guild = guild
 
-        self.source_guild = guild
+        self.is_dirty: Optional[bool] = data.get('is_dirty', None)
 
-    def __repr__(self):
-        return '<Template code={0.code!r} uses={0.uses} name={0.name!r}' \
-               ' creator={0.creator!r} source_guild={0.source_guild!r}>'.format(self)
+    def __repr__(self) -> str:
+        return (
+            f'<Template code={self.code!r} uses={self.uses} name={self.name!r}'
+            f' creator={self.creator!r} source_guild={self.source_guild!r} is_dirty={self.is_dirty}>'
+        )
 
-    async def create_guild(self, name, region=None, icon=None):
+    async def create_guild(self, name: str, region: Optional[VoiceRegion] = None, icon: Any = None) -> Guild:
         """|coro|
 
         Creates a :class:`.Guild` using the template.
@@ -169,7 +206,7 @@ class Template:
         data = await self._state.http.create_from_template(self.code, name, region_value, icon)
         return Guild(data=data, state=self._state)
 
-    async def sync(self):
+    async def sync(self) -> Template:
         """|coro|
 
         Sync the template to the guild's current state.
@@ -179,6 +216,9 @@ class Template:
 
         .. versionadded:: 1.7
 
+        .. versionchanged:: 2.0
+            The template is no longer edited in-place, instead it is returned.
+
         Raises
         -------
         HTTPException
@@ -187,12 +227,22 @@ class Template:
             You don't have permissions to edit the template.
         NotFound
             This template does not exist.
+
+        Returns
+        --------
+        :class:`Template`
+            The newly edited template.
         """
 
         data = await self._state.http.sync_template(self.source_guild.id, self.code)
-        self._store(data)
+        return Template(state=self._state, data=data)
 
-    async def edit(self, **kwargs):
+    async def edit(
+        self,
+        *,
+        name: str = MISSING,
+        description: Optional[str] = MISSING,
+    ) -> Template:
         """|coro|
 
         Edit the template metadata.
@@ -202,12 +252,15 @@ class Template:
 
         .. versionadded:: 1.7
 
+        .. versionchanged:: 2.0
+            The template is no longer edited in-place, instead it is returned.
+
         Parameters
         ------------
-        name: Optional[:class:`str`]
+        name: :class:`str`
             The template's new name.
         description: Optional[:class:`str`]
-            The template's description.
+            The template's new description.
 
         Raises
         -------
@@ -217,11 +270,23 @@ class Template:
             You don't have permissions to edit the template.
         NotFound
             This template does not exist.
-        """
-        data = await self._state.http.edit_template(self.source_guild.id, self.code, kwargs)
-        self._store(data)
 
-    async def delete(self):
+        Returns
+        --------
+        :class:`Template`
+            The newly edited template.
+        """
+        payload = {}
+
+        if name is not MISSING:
+            payload['name'] = name
+        if description is not MISSING:
+            payload['description'] = description
+
+        data = await self._state.http.edit_template(self.source_guild.id, self.code, payload)
+        return Template(state=self._state, data=data)
+
+    async def delete(self) -> None:
         """|coro|
 
         Delete the template.
@@ -241,3 +306,11 @@ class Template:
             This template does not exist.
         """
         await self._state.http.delete_template(self.source_guild.id, self.code)
+
+    @property
+    def url(self) -> str:
+        """:class:`str`: The template url.
+        
+        .. versionadded:: 2.0
+        """
+        return f'https://discord.new/{self.code}'

discord/threads.py

@@ -0,0 +1,810 @@
+"""
+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
+
+from typing import Callable, Dict, Iterable, List, Optional, Union, TYPE_CHECKING
+import time
+import asyncio
+
+from .mixins import Hashable
+from .abc import Messageable
+from .enums import ChannelType, try_enum
+from .errors import ClientException
+from .utils import MISSING, parse_time, _get_as_snowflake
+
+__all__ = (
+    'Thread',
+    'ThreadMember',
+)
+
+if TYPE_CHECKING:
+    from .types.threads import (
+        Thread as ThreadPayload,
+        ThreadMember as ThreadMemberPayload,
+        ThreadMetadata,
+        ThreadArchiveDuration,
+    )
+    from .types.snowflake import SnowflakeList
+    from .guild import Guild
+    from .channel import TextChannel, CategoryChannel
+    from .member import Member
+    from .message import Message, PartialMessage
+    from .abc import Snowflake, SnowflakeTime
+    from .role import Role
+    from .permissions import Permissions
+    from .state import ConnectionState
+
+
+class Thread(Messageable, Hashable):
+    """Represents a Discord thread.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two threads are equal.
+
+        .. describe:: x != y
+
+            Checks if two threads are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the thread's hash.
+
+        .. describe:: int(x)
+
+            Returns the thread's ID.
+
+        .. describe:: str(x)
+
+            Returns the thread's name.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    name: :class:`str`
+        The thread name.
+    guild: :class:`Guild`
+        The guild the thread belongs to.
+    id: :class:`int`
+        The thread ID.
+    parent_id: :class:`int`
+        The parent :class:`TextChannel` ID this thread belongs to.
+    owner_id: :class:`int`
+        The user's ID that created this thread.
+    last_message_id: Optional[:class:`int`]
+        The last message ID of the message sent to this thread. It may
+        *not* point to an existing or valid message.
+    slowmode_delay: :class:`int`
+        The number of seconds a member must wait between sending messages
+        in this thread. A value of `0` denotes that it is disabled.
+        Bots and users with :attr:`~Permissions.manage_channels` or
+        :attr:`~Permissions.manage_messages` bypass slowmode.
+    message_count: :class:`int`
+        An approximate number of messages in this thread. This caps at 50.
+    member_count: :class:`int`
+        An approximate number of members in this thread. This caps at 50.
+    me: Optional[:class:`ThreadMember`]
+        A thread member representing yourself, if you've joined the thread.
+        This could not be available.
+    archived: :class:`bool`
+        Whether the thread is archived.
+    locked: :class:`bool`
+        Whether the thread is locked.
+    invitable: :class:`bool`
+        Whether non-moderators can add other non-moderators to this thread.
+        This is always ``True`` for public threads.
+    archiver_id: Optional[:class:`int`]
+        The user's ID that archived this thread.
+    auto_archive_duration: :class:`int`
+        The duration in minutes until the thread is automatically archived due to inactivity.
+        Usually a value of 60, 1440, 4320 and 10080.
+    archive_timestamp: :class:`datetime.datetime`
+        An aware timestamp of when the thread's archived status was last updated in UTC.
+    """
+
+    __slots__ = (
+        'name',
+        'id',
+        'guild',
+        '_type',
+        '_state',
+        '_members',
+        'owner_id',
+        'parent_id',
+        'last_message_id',
+        'message_count',
+        'member_count',
+        'slowmode_delay',
+        'me',
+        'locked',
+        'archived',
+        'invitable',
+        'archiver_id',
+        'auto_archive_duration',
+        'archive_timestamp',
+    )
+
+    def __init__(self, *, guild: Guild, state: ConnectionState, data: ThreadPayload):
+        self._state: ConnectionState = state
+        self.guild = guild
+        self._members: Dict[int, ThreadMember] = {}
+        self._from_data(data)
+
+    async def _get_channel(self):
+        return self
+
+    def __repr__(self) -> str:
+        return (
+            f'<Thread id={self.id!r} name={self.name!r} parent={self.parent}'
+            f' owner_id={self.owner_id!r} locked={self.locked} archived={self.archived}>'
+        )
+
+    def __str__(self) -> str:
+        return self.name
+
+    def _from_data(self, data: ThreadPayload):
+        self.id = int(data['id'])
+        self.parent_id = int(data['parent_id'])
+        self.owner_id = int(data['owner_id'])
+        self.name = data['name']
+        self._type = try_enum(ChannelType, data['type'])
+        self.last_message_id = _get_as_snowflake(data, 'last_message_id')
+        self.slowmode_delay = data.get('rate_limit_per_user', 0)
+        self.message_count = data['message_count']
+        self.member_count = data['member_count']
+        self._unroll_metadata(data['thread_metadata'])
+
+        try:
+            member = data['member']
+        except KeyError:
+            self.me = None
+        else:
+            self.me = ThreadMember(self, member)
+
+    def _unroll_metadata(self, data: ThreadMetadata):
+        self.archived = data['archived']
+        self.archiver_id = _get_as_snowflake(data, 'archiver_id')
+        self.auto_archive_duration = data['auto_archive_duration']
+        self.archive_timestamp = parse_time(data['archive_timestamp'])
+        self.locked = data.get('locked', False)
+        self.invitable = data.get('invitable', True)
+
+    def _update(self, data):
+        try:
+            self.name = data['name']
+        except KeyError:
+            pass
+
+        self.slowmode_delay = data.get('rate_limit_per_user', 0)
+
+        try:
+            self._unroll_metadata(data['thread_metadata'])
+        except KeyError:
+            pass
+
+    @property
+    def type(self) -> ChannelType:
+        """:class:`ChannelType`: The channel's Discord type."""
+        return self._type
+
+    @property
+    def parent(self) -> Optional[TextChannel]:
+        """Optional[:class:`TextChannel`]: The parent channel this thread belongs to."""
+        return self.guild.get_channel(self.parent_id)  # type: ignore
+
+    @property
+    def owner(self) -> Optional[Member]:
+        """Optional[:class:`Member`]: The member this thread belongs to."""
+        return self.guild.get_member(self.owner_id)
+
+    @property
+    def mention(self) -> str:
+        """:class:`str`: The string that allows you to mention the thread."""
+        return f'<#{self.id}>'
+
+    @property
+    def members(self) -> List[ThreadMember]:
+        """List[:class:`ThreadMember`]: A list of thread members in this thread.
+
+        This requires :attr:`Intents.members` to be properly filled. Most of the time however,
+        this data is not provided by the gateway and a call to :meth:`fetch_members` is
+        needed.
+        """
+        return list(self._members.values())
+
+    @property
+    def last_message(self) -> Optional[Message]:
+        """Fetches the last message from this channel in cache.
+
+        The message might not be valid or point to an existing message.
+
+        .. admonition:: Reliable Fetching
+            :class: helpful
+
+            For a slightly more reliable method of fetching the
+            last message, consider using either :meth:`history`
+            or :meth:`fetch_message` with the :attr:`last_message_id`
+            attribute.
+
+        Returns
+        ---------
+        Optional[:class:`Message`]
+            The last message in this channel or ``None`` if not found.
+        """
+        return self._state._get_message(self.last_message_id) if self.last_message_id else None
+
+    @property
+    def category(self) -> Optional[CategoryChannel]:
+        """The category channel the parent channel belongs to, if applicable.
+
+        Raises
+        -------
+        ClientException
+            The parent channel was not cached and returned ``None``.
+
+        Returns
+        -------
+        Optional[:class:`CategoryChannel`]
+            The parent channel's category.
+        """
+
+        parent = self.parent
+        if parent is None:
+            raise ClientException('Parent channel not found')
+        return parent.category
+    
+    @property
+    def category_id(self) -> Optional[int]:
+        """The category channel ID the parent channel belongs to, if applicable.
+
+        Raises
+        -------
+        ClientException
+            The parent channel was not cached and returned ``None``.
+
+        Returns
+        -------
+        Optional[:class:`int`]
+            The parent channel's category ID.
+        """
+
+        parent = self.parent
+        if parent is None:
+            raise ClientException('Parent channel not found')
+        return parent.category_id
+
+    def is_private(self) -> bool:
+        """:class:`bool`: Whether the thread is a private thread.
+
+        A private thread is only viewable by those that have been explicitly
+        invited or have :attr:`~.Permissions.manage_threads`.
+        """
+        return self._type is ChannelType.private_thread
+
+    def is_news(self) -> bool:
+        """:class:`bool`: Whether the thread is a news thread.
+
+        A news thread is a thread that has a parent that is a news channel,
+        i.e. :meth:`.TextChannel.is_news` is ``True``.
+        """
+        return self._type is ChannelType.news_thread
+
+    def is_nsfw(self) -> bool:
+        """:class:`bool`: Whether the thread is NSFW or not.
+
+        An NSFW thread is a thread that has a parent that is an NSFW channel,
+        i.e. :meth:`.TextChannel.is_nsfw` is ``True``.
+        """
+        parent = self.parent
+        return parent is not None and parent.is_nsfw()
+
+    def permissions_for(self, obj: Union[Member, Role], /) -> Permissions:
+        """Handles permission resolution for the :class:`~discord.Member`
+        or :class:`~discord.Role`.
+
+        Since threads do not have their own permissions, they inherit them
+        from the parent channel. This is a convenience method for
+        calling :meth:`~discord.TextChannel.permissions_for` on the
+        parent channel.
+
+        Parameters
+        ----------
+        obj: Union[:class:`~discord.Member`, :class:`~discord.Role`]
+            The object to resolve permissions for. This could be either
+            a member or a role. If it's a role then member overwrites
+            are not computed.
+
+        Raises
+        -------
+        ClientException
+            The parent channel was not cached and returned ``None``
+
+        Returns
+        -------
+        :class:`~discord.Permissions`
+            The resolved permissions for the member or role.
+        """
+
+        parent = self.parent
+        if parent is None:
+            raise ClientException('Parent channel not found')
+        return parent.permissions_for(obj)
+
+    async def delete_messages(self, messages: Iterable[Snowflake]) -> None:
+        """|coro|
+
+        Deletes a list of messages. This is similar to :meth:`Message.delete`
+        except it bulk deletes multiple messages.
+
+        As a special case, if the number of messages is 0, then nothing
+        is done. If the number of messages is 1 then single message
+        delete is done. If it's more than two, then bulk delete is used.
+
+        You cannot bulk delete more than 100 messages or messages that
+        are older than 14 days old.
+
+        You must have the :attr:`~Permissions.manage_messages` permission to
+        use this.
+
+        Usable only by bot accounts.
+
+        Parameters
+        -----------
+        messages: Iterable[:class:`abc.Snowflake`]
+            An iterable of messages denoting which ones to bulk delete.
+
+        Raises
+        ------
+        ClientException
+            The number of messages to delete was more than 100.
+        Forbidden
+            You do not have proper permissions to delete the messages or
+            you're not using a bot account.
+        NotFound
+            If single delete, then the message was already deleted.
+        HTTPException
+            Deleting the messages failed.
+        """
+        if not isinstance(messages, (list, tuple)):
+            messages = list(messages)
+
+        if len(messages) == 0:
+            return  # do nothing
+
+        if len(messages) == 1:
+            message_id = messages[0].id
+            await self._state.http.delete_message(self.id, message_id)
+            return
+
+        if len(messages) > 100:
+            raise ClientException('Can only bulk delete messages up to 100 messages')
+
+        message_ids: SnowflakeList = [m.id for m in messages]
+        await self._state.http.delete_messages(self.id, message_ids)
+
+    async def purge(
+        self,
+        *,
+        limit: Optional[int] = 100,
+        check: Callable[[Message], bool] = MISSING,
+        before: Optional[SnowflakeTime] = None,
+        after: Optional[SnowflakeTime] = None,
+        around: Optional[SnowflakeTime] = None,
+        oldest_first: Optional[bool] = False,
+        bulk: bool = True,
+    ) -> List[Message]:
+        """|coro|
+
+        Purges a list of messages that meet the criteria given by the predicate
+        ``check``. If a ``check`` is not provided then all messages are deleted
+        without discrimination.
+
+        You must have the :attr:`~Permissions.manage_messages` permission to
+        delete messages even if they are your own (unless you are a user
+        account). The :attr:`~Permissions.read_message_history` permission is
+        also needed to retrieve message history.
+
+        Examples
+        ---------
+
+        Deleting bot's messages ::
+
+            def is_me(m):
+                return m.author == client.user
+
+            deleted = await thread.purge(limit=100, check=is_me)
+            await thread.send(f'Deleted {len(deleted)} message(s)')
+
+        Parameters
+        -----------
+        limit: Optional[:class:`int`]
+            The number of messages to search through. This is not the number
+            of messages that will be deleted, though it can be.
+        check: Callable[[:class:`Message`], :class:`bool`]
+            The function used to check if a message should be deleted.
+            It must take a :class:`Message` as its sole parameter.
+        before: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
+            Same as ``before`` in :meth:`history`.
+        after: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
+            Same as ``after`` in :meth:`history`.
+        around: Optional[Union[:class:`abc.Snowflake`, :class:`datetime.datetime`]]
+            Same as ``around`` in :meth:`history`.
+        oldest_first: Optional[:class:`bool`]
+            Same as ``oldest_first`` in :meth:`history`.
+        bulk: :class:`bool`
+            If ``True``, use bulk delete. Setting this to ``False`` is useful for mass-deleting
+            a bot's own messages without :attr:`Permissions.manage_messages`. When ``True``, will
+            fall back to single delete if messages are older than two weeks.
+
+        Raises
+        -------
+        Forbidden
+            You do not have proper permissions to do the actions required.
+        HTTPException
+            Purging the messages failed.
+
+        Returns
+        --------
+        List[:class:`.Message`]
+            The list of messages that were deleted.
+        """
+
+        if check is MISSING:
+            check = lambda m: True
+
+        iterator = self.history(limit=limit, before=before, after=after, oldest_first=oldest_first, around=around)
+        ret: List[Message] = []
+        count = 0
+
+        minimum_time = int((time.time() - 14 * 24 * 60 * 60) * 1000.0 - 1420070400000) << 22
+
+        async def _single_delete_strategy(messages: Iterable[Message]):
+            for m in messages:
+                await m.delete()
+
+        strategy = self.delete_messages if bulk else _single_delete_strategy
+
+        async for message in iterator:
+            if count == 100:
+                to_delete = ret[-100:]
+                await strategy(to_delete)
+                count = 0
+                await asyncio.sleep(1)
+
+            if not check(message):
+                continue
+
+            if message.id < minimum_time:
+                # older than 14 days old
+                if count == 1:
+                    await ret[-1].delete()
+                elif count >= 2:
+                    to_delete = ret[-count:]
+                    await strategy(to_delete)
+
+                count = 0
+                strategy = _single_delete_strategy
+
+            count += 1
+            ret.append(message)
+
+        # SOme messages remaining to poll
+        if count >= 2:
+            # more than 2 messages -> bulk delete
+            to_delete = ret[-count:]
+            await strategy(to_delete)
+        elif count == 1:
+            # delete a single message
+            await ret[-1].delete()
+
+        return ret
+
+    async def edit(
+        self,
+        *,
+        name: str = MISSING,
+        archived: bool = MISSING,
+        locked: bool = MISSING,
+        invitable: bool = MISSING,
+        slowmode_delay: int = MISSING,
+        auto_archive_duration: ThreadArchiveDuration = MISSING,
+    ) -> Thread:
+        """|coro|
+
+        Edits the thread.
+
+        Editing the thread requires :attr:`.Permissions.manage_threads`. The thread
+        creator can also edit ``name``, ``archived`` or ``auto_archive_duration``.
+        Note that if the thread is locked then only those with :attr:`.Permissions.manage_threads`
+        can unarchive a thread.
+
+        The thread must be unarchived to be edited.
+
+        Parameters
+        ------------
+        name: :class:`str`
+            The new name of the thread.
+        archived: :class:`bool`
+            Whether to archive the thread or not.
+        locked: :class:`bool`
+            Whether to lock the thread or not.
+        invitable: :class:`bool`
+            Whether non-moderators can add other non-moderators to this thread.
+            Only available for private threads.
+        auto_archive_duration: :class:`int`
+            The new duration in minutes before a thread is automatically archived for inactivity.
+            Must be one of ``60``, ``1440``, ``4320``, or ``10080``.
+        slowmode_delay: :class:`int`
+            Specifies the slowmode rate limit for user in this thread, in seconds.
+            A value of ``0`` disables slowmode. The maximum value possible is ``21600``.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to edit the thread.
+        HTTPException
+            Editing the thread failed.
+
+        Returns
+        --------
+        :class:`Thread`
+            The newly edited thread.
+        """
+        payload = {}
+        if name is not MISSING:
+            payload['name'] = str(name)
+        if archived is not MISSING:
+            payload['archived'] = archived
+        if auto_archive_duration is not MISSING:
+            payload['auto_archive_duration'] = auto_archive_duration
+        if locked is not MISSING:
+            payload['locked'] = locked
+        if invitable is not MISSING:
+            payload['invitable'] = invitable
+        if slowmode_delay is not MISSING:
+            payload['rate_limit_per_user'] = slowmode_delay
+
+        data = await self._state.http.edit_channel(self.id, **payload)
+        # The data payload will always be a Thread payload
+        return Thread(data=data, state=self._state, guild=self.guild)  # type: ignore
+
+    async def join(self):
+        """|coro|
+
+        Joins this thread.
+
+        You must have :attr:`~Permissions.send_messages_in_threads` to join a thread.
+        If the thread is private, :attr:`~Permissions.manage_threads` is also needed.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to join the thread.
+        HTTPException
+            Joining the thread failed.
+        """
+        await self._state.http.join_thread(self.id)
+
+    async def leave(self):
+        """|coro|
+
+        Leaves this thread.
+
+        Raises
+        -------
+        HTTPException
+            Leaving the thread failed.
+        """
+        await self._state.http.leave_thread(self.id)
+
+    async def add_user(self, user: Snowflake):
+        """|coro|
+
+        Adds a user to this thread.
+
+        You must have :attr:`~Permissions.send_messages` and :attr:`~Permissions.use_threads`
+        to add a user to a public thread. If the thread is private then :attr:`~Permissions.send_messages`
+        and either :attr:`~Permissions.use_private_threads` or :attr:`~Permissions.manage_messages`
+        is required to add a user to the thread.
+
+        Parameters
+        -----------
+        user: :class:`abc.Snowflake`
+            The user to add to the thread.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to add the user to the thread.
+        HTTPException
+            Adding the user to the thread failed.
+        """
+        await self._state.http.add_user_to_thread(self.id, user.id)
+
+    async def remove_user(self, user: Snowflake):
+        """|coro|
+
+        Removes a user from this thread.
+
+        You must have :attr:`~Permissions.manage_threads` or be the creator of the thread to remove a user.
+
+        Parameters
+        -----------
+        user: :class:`abc.Snowflake`
+            The user to add to the thread.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to remove the user from the thread.
+        HTTPException
+            Removing the user from the thread failed.
+        """
+        await self._state.http.remove_user_from_thread(self.id, user.id)
+
+    async def fetch_members(self) -> List[ThreadMember]:
+        """|coro|
+
+        Retrieves all :class:`ThreadMember` that are in this thread.
+
+        This requires :attr:`Intents.members` to get information about members
+        other than yourself.
+
+        Raises
+        -------
+        HTTPException
+            Retrieving the members failed.
+
+        Returns
+        --------
+        List[:class:`ThreadMember`]
+            All thread members in the thread.
+        """
+
+        members = await self._state.http.get_thread_members(self.id)
+        return [ThreadMember(parent=self, data=data) for data in members]
+
+    async def delete(self):
+        """|coro|
+
+        Deletes this thread.
+
+        You must have :attr:`~Permissions.manage_threads` to delete threads.
+
+        Raises
+        -------
+        Forbidden
+            You do not have permissions to delete this thread.
+        HTTPException
+            Deleting the thread failed.
+        """
+        await self._state.http.delete_channel(self.id)
+
+    def get_partial_message(self, message_id: int, /) -> PartialMessage:
+        """Creates a :class:`PartialMessage` from the message ID.
+
+        This is useful if you want to work with a message and only have its ID without
+        doing an unnecessary API call.
+
+        .. versionadded:: 2.0
+
+        Parameters
+        ------------
+        message_id: :class:`int`
+            The message ID to create a partial message for.
+
+        Returns
+        ---------
+        :class:`PartialMessage`
+            The partial message.
+        """
+
+        from .message import PartialMessage
+
+        return PartialMessage(channel=self, id=message_id)
+
+    def _add_member(self, member: ThreadMember) -> None:
+        self._members[member.id] = member
+
+    def _pop_member(self, member_id: int) -> Optional[ThreadMember]:
+        return self._members.pop(member_id, None)
+
+
+class ThreadMember(Hashable):
+    """Represents a Discord thread member.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two thread members are equal.
+
+        .. describe:: x != y
+
+            Checks if two thread members are not equal.
+
+        .. describe:: hash(x)
+
+            Returns the thread member's hash.
+
+        .. describe:: int(x)
+
+            Returns the thread member's ID.
+
+        .. describe:: str(x)
+
+            Returns the thread member's name.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    id: :class:`int`
+        The thread member's ID.
+    thread_id: :class:`int`
+        The thread's ID.
+    joined_at: :class:`datetime.datetime`
+        The time the member joined the thread in UTC.
+    """
+
+    __slots__ = (
+        'id',
+        'thread_id',
+        'joined_at',
+        'flags',
+        '_state',
+        'parent',
+    )
+
+    def __init__(self, parent: Thread, data: ThreadMemberPayload):
+        self.parent = parent
+        self._state = parent._state
+        self._from_data(data)
+
+    def __repr__(self) -> str:
+        return f'<ThreadMember id={self.id} thread_id={self.thread_id} joined_at={self.joined_at!r}>'
+
+    def _from_data(self, data: ThreadMemberPayload):
+        try:
+            self.id = int(data['user_id'])
+        except KeyError:
+            assert self._state.self_id is not None
+            self.id = self._state.self_id
+
+        try:
+            self.thread_id = int(data['id'])
+        except KeyError:
+            self.thread_id = self.parent.id
+
+        self.joined_at = parse_time(data['join_timestamp'])
+        self.flags = data['flags']
+
+    @property
+    def thread(self) -> Thread:
+        """:class:`Thread`: The thread this member belongs to."""
+        return self.parent

discord/types/activity.py

@@ -0,0 +1,114 @@
+"""
+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
+
+from typing import List, Literal, Optional, TypedDict
+from .user import PartialUser
+from .snowflake import Snowflake
+
+
+StatusType = Literal['idle', 'dnd', 'online', 'offline']
+
+
+class PartialPresenceUpdate(TypedDict):
+    user: PartialUser
+    guild_id: Snowflake
+    status: StatusType
+    activities: List[Activity]
+    client_status: ClientStatus
+
+
+class ClientStatus(TypedDict, total=False):
+    desktop: str
+    mobile: str
+    web: str
+
+
+class ActivityTimestamps(TypedDict, total=False):
+    start: int
+    end: int
+
+
+class ActivityParty(TypedDict, total=False):
+    id: str
+    size: List[int]
+
+
+class ActivityAssets(TypedDict, total=False):
+    large_image: str
+    large_text: str
+    small_image: str
+    small_text: str
+
+
+class ActivitySecrets(TypedDict, total=False):
+    join: str
+    spectate: str
+    match: str
+
+
+class _ActivityEmojiOptional(TypedDict, total=False):
+    id: Snowflake
+    animated: bool
+
+
+class ActivityEmoji(_ActivityEmojiOptional):
+    name: str
+
+
+class ActivityButton(TypedDict):
+    label: str
+    url: str
+
+
+class _SendableActivityOptional(TypedDict, total=False):
+    url: Optional[str]
+
+
+ActivityType = Literal[0, 1, 2, 4, 5]
+
+
+class SendableActivity(_SendableActivityOptional):
+    name: str
+    type: ActivityType
+
+
+class _BaseActivity(SendableActivity):
+    created_at: int
+
+
+class Activity(_BaseActivity, total=False):
+    state: Optional[str]
+    details: Optional[str]
+    timestamps: ActivityTimestamps
+    assets: ActivityAssets
+    party: ActivityParty
+    application_id: Snowflake
+    flags: int
+    emoji: Optional[ActivityEmoji]
+    secrets: ActivitySecrets
+    session_id: Optional[str]
+    instance: bool
+    buttons: List[ActivityButton]

discord/types/appinfo.py

@@ -0,0 +1,67 @@
+"""
+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
+
+from typing import TypedDict, List, Optional
+
+from .user import User
+from .team import Team
+from .snowflake import Snowflake
+
+class BaseAppInfo(TypedDict):
+    id: Snowflake
+    name: str
+    verify_key: str
+    icon: Optional[str]
+    summary: str
+    description: str
+
+class _AppInfoOptional(TypedDict, total=False):
+    team: Team
+    guild_id: Snowflake
+    primary_sku_id: Snowflake
+    slug: str
+    terms_of_service_url: str
+    privacy_policy_url: str
+    hook: bool
+    max_participants: int
+
+class AppInfo(BaseAppInfo, _AppInfoOptional):
+    rpc_origins: List[str]
+    owner: User
+    bot_public: bool
+    bot_require_code_grant: bool
+
+class _PartialAppInfoOptional(TypedDict, total=False):
+    rpc_origins: List[str]
+    cover_image: str
+    hook: bool
+    terms_of_service_url: str
+    privacy_policy_url: str
+    max_participants: int
+    flags: int
+
+class PartialAppInfo(_PartialAppInfoOptional, BaseAppInfo):
+    pass

discord/types/audit_log.py

@@ -0,0 +1,257 @@
+"""
+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
+
+from typing import List, Literal, Optional, TypedDict, Union
+from .webhook import Webhook
+from .guild import MFALevel, VerificationLevel, ExplicitContentFilterLevel, DefaultMessageNotificationLevel
+from .integration import IntegrationExpireBehavior, PartialIntegration
+from .user import User
+from .snowflake import Snowflake
+from .role import Role
+from .channel import ChannelType, VideoQualityMode, PermissionOverwrite
+from .threads import Thread
+
+AuditLogEvent = Literal[
+    1,
+    10,
+    11,
+    12,
+    13,
+    14,
+    15,
+    20,
+    21,
+    22,
+    23,
+    24,
+    25,
+    26,
+    27,
+    28,
+    30,
+    31,
+    32,
+    40,
+    41,
+    42,
+    50,
+    51,
+    52,
+    60,
+    61,
+    62,
+    72,
+    73,
+    74,
+    75,
+    80,
+    81,
+    82,
+    83,
+    84,
+    85,
+    90,
+    91,
+    92,
+    110,
+    111,
+    112,
+]
+
+
+class _AuditLogChange_Str(TypedDict):
+    key: Literal[
+        'name', 'description', 'preferred_locale', 'vanity_url_code', 'topic', 'code', 'allow', 'deny', 'permissions', 'tags'
+    ]
+    new_value: str
+    old_value: str
+
+
+class _AuditLogChange_AssetHash(TypedDict):
+    key: Literal['icon_hash', 'splash_hash', 'discovery_splash_hash', 'banner_hash', 'avatar_hash', 'asset']
+    new_value: str
+    old_value: str
+
+
+class _AuditLogChange_Snowflake(TypedDict):
+    key: Literal[
+        'id',
+        'owner_id',
+        'afk_channel_id',
+        'rules_channel_id',
+        'public_updates_channel_id',
+        'widget_channel_id',
+        'system_channel_id',
+        'application_id',
+        'channel_id',
+        'inviter_id',
+        'guild_id',
+    ]
+    new_value: Snowflake
+    old_value: Snowflake
+
+
+class _AuditLogChange_Bool(TypedDict):
+    key: Literal[
+        'widget_enabled',
+        'nsfw',
+        'hoist',
+        'mentionable',
+        'temporary',
+        'deaf',
+        'mute',
+        'nick',
+        'enabled_emoticons',
+        'region',
+        'rtc_region',
+        'available',
+        'archived',
+        'locked',
+    ]
+    new_value: bool
+    old_value: bool
+
+
+class _AuditLogChange_Int(TypedDict):
+    key: Literal[
+        'afk_timeout',
+        'prune_delete_days',
+        'position',
+        'bitrate',
+        'rate_limit_per_user',
+        'color',
+        'max_uses',
+        'max_age',
+        'user_limit',
+        'auto_archive_duration',
+        'default_auto_archive_duration',
+    ]
+    new_value: int
+    old_value: int
+
+
+class _AuditLogChange_ListRole(TypedDict):
+    key: Literal['$add', '$remove']
+    new_value: List[Role]
+    old_value: List[Role]
+
+
+class _AuditLogChange_MFALevel(TypedDict):
+    key: Literal['mfa_level']
+    new_value: MFALevel
+    old_value: MFALevel
+
+
+class _AuditLogChange_VerificationLevel(TypedDict):
+    key: Literal['verification_level']
+    new_value: VerificationLevel
+    old_value: VerificationLevel
+
+
+class _AuditLogChange_ExplicitContentFilter(TypedDict):
+    key: Literal['explicit_content_filter']
+    new_value: ExplicitContentFilterLevel
+    old_value: ExplicitContentFilterLevel
+
+
+class _AuditLogChange_DefaultMessageNotificationLevel(TypedDict):
+    key: Literal['default_message_notifications']
+    new_value: DefaultMessageNotificationLevel
+    old_value: DefaultMessageNotificationLevel
+
+
+class _AuditLogChange_ChannelType(TypedDict):
+    key: Literal['type']
+    new_value: ChannelType
+    old_value: ChannelType
+
+
+class _AuditLogChange_IntegrationExpireBehaviour(TypedDict):
+    key: Literal['expire_behavior']
+    new_value: IntegrationExpireBehavior
+    old_value: IntegrationExpireBehavior
+
+
+class _AuditLogChange_VideoQualityMode(TypedDict):
+    key: Literal['video_quality_mode']
+    new_value: VideoQualityMode
+    old_value: VideoQualityMode
+
+
+class _AuditLogChange_Overwrites(TypedDict):
+    key: Literal['permission_overwrites']
+    new_value: List[PermissionOverwrite]
+    old_value: List[PermissionOverwrite]
+
+
+AuditLogChange = Union[
+    _AuditLogChange_Str,
+    _AuditLogChange_AssetHash,
+    _AuditLogChange_Snowflake,
+    _AuditLogChange_Int,
+    _AuditLogChange_Bool,
+    _AuditLogChange_ListRole,
+    _AuditLogChange_MFALevel,
+    _AuditLogChange_VerificationLevel,
+    _AuditLogChange_ExplicitContentFilter,
+    _AuditLogChange_DefaultMessageNotificationLevel,
+    _AuditLogChange_ChannelType,
+    _AuditLogChange_IntegrationExpireBehaviour,
+    _AuditLogChange_VideoQualityMode,
+    _AuditLogChange_Overwrites,
+]
+
+
+class AuditEntryInfo(TypedDict):
+    delete_member_days: str
+    members_removed: str
+    channel_id: Snowflake
+    message_id: Snowflake
+    count: str
+    id: Snowflake
+    type: Literal['0', '1']
+    role_name: str
+
+
+class _AuditLogEntryOptional(TypedDict, total=False):
+    changes: List[AuditLogChange]
+    options: AuditEntryInfo
+    reason: str
+
+
+class AuditLogEntry(_AuditLogEntryOptional):
+    target_id: Optional[str]
+    user_id: Optional[Snowflake]
+    id: Snowflake
+    action_type: AuditLogEvent
+
+
+class AuditLog(TypedDict):
+    webhooks: List[Webhook]
+    users: List[User]
+    audit_log_entries: List[AuditLogEntry]
+    integrations: List[PartialIntegration]
+    threads: List[Thread]

discord/types/channel.py

@@ -22,58 +22,31 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from typing import List, Literal, Optional, TypedDict, Union
 from .user import PartialUser
 from .snowflake import Snowflake
-from typing import List, Literal, Optional, TypedDict
+from .threads import ThreadMetadata, ThreadMember, ThreadArchiveDuration
+
+
+OverwriteType = Literal[0, 1]
 
 
 class PermissionOverwrite(TypedDict):
     id: Snowflake
-    type: Literal[0, 1]
+    type: OverwriteType
     allow: str
     deny: str
 
 
-ChannelType = Literal[0, 1, 2, 3, 4, 5, 6, 13]
+ChannelType = Literal[0, 1, 2, 3, 4, 5, 6, 10, 11, 12, 13]
 
 
-class PartialChannel(TypedDict):
-    id: str
-    type: ChannelType
+class _BaseChannel(TypedDict):
+    id: Snowflake
     name: str
 
 
-class _TextChannelOptional(PartialChannel, total=False):
-    topic: str
-    last_message_id: Optional[Snowflake]
-    last_pin_timestamp: int
-    rate_limit_per_user: int
-
-
-class _VoiceChannelOptional(PartialChannel, total=False):
-    rtc_region: Optional[str]
-    bitrate: int
-    user_limit: int
-
-
-class _CategoryChannelOptional(PartialChannel, total=False):
-    ...
-
-
-class _StoreChannelOptional(PartialChannel, total=False):
-    ...
-
-
-class _StageChannelOptional(PartialChannel, total=False):
-    rtc_region: Optional[str]
-    bitrate: int
-    user_limit: int
-    topic: str
-
-
-class GuildChannel(
-    _TextChannelOptional, _VoiceChannelOptional, _CategoryChannelOptional, _StoreChannelOptional, _StageChannelOptional
-):
+class _BaseGuildChannel(_BaseChannel):
     guild_id: Snowflake
     position: int
     permission_overwrites: List[PermissionOverwrite]
@@ -81,11 +54,104 @@ class GuildChannel(
     parent_id: Optional[Snowflake]
 
 
-class DMChannel(PartialChannel):
+class PartialChannel(_BaseChannel):
+    type: ChannelType
+
+
+class _TextChannelOptional(TypedDict, total=False):
+    topic: str
+    last_message_id: Optional[Snowflake]
+    last_pin_timestamp: str
+    rate_limit_per_user: int
+    default_auto_archive_duration: ThreadArchiveDuration
+
+
+class TextChannel(_BaseGuildChannel, _TextChannelOptional):
+    type: Literal[0]
+
+
+class NewsChannel(_BaseGuildChannel, _TextChannelOptional):
+    type: Literal[5]
+
+
+VideoQualityMode = Literal[1, 2]
+
+
+class _VoiceChannelOptional(TypedDict, total=False):
+    rtc_region: Optional[str]
+    video_quality_mode: VideoQualityMode
+
+
+class VoiceChannel(_BaseGuildChannel, _VoiceChannelOptional):
+    type: Literal[2]
+    bitrate: int
+    user_limit: int
+
+
+class CategoryChannel(_BaseGuildChannel):
+    type: Literal[4]
+
+
+class StoreChannel(_BaseGuildChannel):
+    type: Literal[6]
+
+
+class _StageChannelOptional(TypedDict, total=False):
+    rtc_region: Optional[str]
+    topic: str
+
+
+class StageChannel(_BaseGuildChannel, _StageChannelOptional):
+    type: Literal[13]
+    bitrate: int
+    user_limit: int
+
+
+class _ThreadChannelOptional(TypedDict, total=False):
+    member: ThreadMember
+    owner_id: Snowflake
+    rate_limit_per_user: int
+    last_message_id: Optional[Snowflake]
+    last_pin_timestamp: str
+
+
+class ThreadChannel(_BaseChannel, _ThreadChannelOptional):
+    type: Literal[10, 11, 12]
+    guild_id: Snowflake
+    parent_id: Snowflake
+    owner_id: Snowflake
+    nsfw: bool
+    last_message_id: Optional[Snowflake]
+    rate_limit_per_user: int
+    message_count: int
+    member_count: int
+    thread_metadata: ThreadMetadata
+
+
+GuildChannel = Union[TextChannel, NewsChannel, VoiceChannel, CategoryChannel, StoreChannel, StageChannel, ThreadChannel]
+
+
+class DMChannel(_BaseChannel):
+    type: Literal[1]
     last_message_id: Optional[Snowflake]
     recipients: List[PartialUser]
 
 
-class GroupDMChannel(DMChannel):
+class GroupDMChannel(_BaseChannel):
+    type: Literal[3]
     icon: Optional[str]
     owner_id: Snowflake
+
+
+Channel = Union[GuildChannel, DMChannel, GroupDMChannel]
+
+PrivacyLevel = Literal[1, 2]
+
+
+class StageInstance(TypedDict):
+    id: Snowflake
+    guild_id: Snowflake
+    channel_id: Snowflake
+    topic: str
+    privacy_level: PrivacyLevel
+    discoverable_disabled: bool

discord/types/components.py

@@ -0,0 +1,76 @@
+"""
+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
+
+from typing import List, Literal, TypedDict, Union
+from .emoji import PartialEmoji
+
+ComponentType = Literal[1, 2, 3]
+ButtonStyle = Literal[1, 2, 3, 4, 5]
+
+
+class ActionRow(TypedDict):
+    type: Literal[1]
+    components: List[Component]
+
+
+class _ButtonComponentOptional(TypedDict, total=False):
+    custom_id: str
+    url: str
+    disabled: bool
+    emoji: PartialEmoji
+    label: str
+
+
+class ButtonComponent(_ButtonComponentOptional):
+    type: Literal[2]
+    style: ButtonStyle
+
+
+class _SelectMenuOptional(TypedDict, total=False):
+    placeholder: str
+    min_values: int
+    max_values: int
+    disabled: bool
+
+
+class _SelectOptionsOptional(TypedDict, total=False):
+    description: str
+    emoji: PartialEmoji
+
+
+class SelectOption(_SelectOptionsOptional):
+    label: str
+    value: str
+    default: bool
+
+
+class SelectMenu(_SelectMenuOptional):
+    type: Literal[3]
+    custom_id: str
+    options: List[SelectOption]
+
+
+Component = Union[ActionRow, ButtonComponent, SelectMenu]

discord/types/emoji.py

@@ -0,0 +1,46 @@
+"""
+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 typing import Optional, TypedDict
+from .snowflake import Snowflake, SnowflakeList
+from .user import User
+
+
+class PartialEmoji(TypedDict):
+    id: Optional[Snowflake]
+    name: Optional[str]
+
+
+class Emoji(PartialEmoji, total=False):
+    roles: SnowflakeList
+    user: User
+    require_colons: bool
+    managed: bool
+    animated: bool
+    available: bool
+
+
+class EditEmoji(TypedDict):
+    name: str
+    roles: Optional[SnowflakeList]

discord/types/gateway.py

@@ -0,0 +1,41 @@
+"""
+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 typing import TypedDict
+
+
+class SessionStartLimit(TypedDict):
+    total: int
+    remaining: int
+    reset_after: int
+    max_concurrency: int
+
+
+class Gateway(TypedDict):
+    url: str
+
+
+class GatewayBot(Gateway):
+    shards: int
+    session_start_limit: SessionStartLimit

discord/types/guild.py

@@ -0,0 +1,168 @@
+"""
+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 typing import List, Literal, Optional, TypedDict
+from .snowflake import Snowflake
+from .channel import GuildChannel
+from .voice import GuildVoiceState
+from .welcome_screen import WelcomeScreen
+from .activity import PartialPresenceUpdate
+from .role import Role
+from .member import Member
+from .emoji import Emoji
+from .user import User
+from .threads import Thread
+
+
+class Ban(TypedDict):
+    reason: Optional[str]
+    user: User
+
+
+class _UnavailableGuildOptional(TypedDict, total=False):
+    unavailable: bool
+
+
+class UnavailableGuild(_UnavailableGuildOptional):
+    id: Snowflake
+
+
+class _GuildOptional(TypedDict, total=False):
+    icon_hash: Optional[str]
+    owner: bool
+    permissions: str
+    widget_enabled: bool
+    widget_channel_id: Optional[Snowflake]
+    joined_at: Optional[str]
+    large: bool
+    member_count: int
+    voice_states: List[GuildVoiceState]
+    members: List[Member]
+    channels: List[GuildChannel]
+    presences: List[PartialPresenceUpdate]
+    threads: List[Thread]
+    max_presences: Optional[int]
+    max_members: int
+    premium_subscription_count: int
+    max_video_channel_users: int
+
+
+DefaultMessageNotificationLevel = Literal[0, 1]
+ExplicitContentFilterLevel = Literal[0, 1, 2]
+MFALevel = Literal[0, 1]
+VerificationLevel = Literal[0, 1, 2, 3, 4]
+NSFWLevel = Literal[0, 1, 2, 3]
+PremiumTier = Literal[0, 1, 2, 3]
+GuildFeature = Literal[
+    'ANIMATED_ICON',
+    'BANNER',
+    'COMMERCE',
+    'COMMUNITY',
+    'DISCOVERABLE',
+    'FEATURABLE',
+    'INVITE_SPLASH',
+    'MEMBER_VERIFICATION_GATE_ENABLED',
+    'MONETIZATION_ENABLED',
+    'MORE_EMOJI',
+    'MORE_STICKERS',
+    'NEWS',
+    'PARTNERED',
+    'PREVIEW_ENABLED',
+    'PRIVATE_THREADS',
+    'SEVEN_DAY_THREAD_ARCHIVE',
+    'THREE_DAY_THREAD_ARCHIVE',
+    'TICKETED_EVENTS_ENABLED',
+    'VANITY_URL',
+    'VERIFIED',
+    'VIP_REGIONS',
+    'WELCOME_SCREEN_ENABLED',
+]
+
+
+class _BaseGuildPreview(UnavailableGuild):
+    name: str
+    icon: Optional[str]
+    splash: Optional[str]
+    discovery_splash: Optional[str]
+    emojis: List[Emoji]
+    features: List[GuildFeature]
+    description: Optional[str]
+
+
+class _GuildPreviewUnique(TypedDict):
+    approximate_member_count: int
+    approximate_presence_count: int
+
+
+class GuildPreview(_BaseGuildPreview, _GuildPreviewUnique):
+    ...
+
+
+class Guild(_BaseGuildPreview, _GuildOptional):
+    owner_id: Snowflake
+    region: str
+    afk_channel_id: Optional[Snowflake]
+    afk_timeout: int
+    verification_level: VerificationLevel
+    default_message_notifications: DefaultMessageNotificationLevel
+    explicit_content_filter: ExplicitContentFilterLevel
+    roles: List[Role]
+    mfa_level: MFALevel
+    nsfw_level: NSFWLevel
+    application_id: Optional[Snowflake]
+    system_channel_id: Optional[Snowflake]
+    system_channel_flags: int
+    rules_channel_id: Optional[Snowflake]
+    vanity_url_code: Optional[str]
+    banner: Optional[str]
+    premium_tier: PremiumTier
+    preferred_locale: str
+    public_updates_channel_id: Optional[Snowflake]
+
+
+class InviteGuild(Guild, total=False):
+    welcome_screen: WelcomeScreen
+
+
+class GuildWithCounts(Guild, _GuildPreviewUnique):
+    ...
+
+
+class GuildPrune(TypedDict):
+    pruned: Optional[int]
+
+
+class ChannelPositionUpdate(TypedDict):
+    id: Snowflake
+    position: Optional[int]
+    lock_permissions: Optional[bool]
+    parent_id: Optional[Snowflake]
+
+
+class _RolePositionRequired(TypedDict):
+    id: Snowflake
+
+
+class RolePositionUpdate(_RolePositionRequired, total=False):
+    position: Optional[Snowflake]

discord/types/integration.py

@@ -0,0 +1,82 @@
+"""
+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
+
+from typing import Literal, Optional, TypedDict, Union
+from .snowflake import Snowflake
+from .user import User
+
+
+class _IntegrationApplicationOptional(TypedDict, total=False):
+    bot: User
+
+
+class IntegrationApplication(_IntegrationApplicationOptional):
+    id: Snowflake
+    name: str
+    icon: Optional[str]
+    description: str
+    summary: str
+
+
+class IntegrationAccount(TypedDict):
+    id: str
+    name: str
+
+
+IntegrationExpireBehavior = Literal[0, 1]
+
+
+class PartialIntegration(TypedDict):
+    id: Snowflake
+    name: str
+    type: IntegrationType
+    account: IntegrationAccount
+
+
+IntegrationType = Literal['twitch', 'youtube', 'discord']
+
+
+class BaseIntegration(PartialIntegration):
+    enabled: bool
+    syncing: bool
+    synced_at: str
+    user: User
+    expire_behavior: IntegrationExpireBehavior
+    expire_grace_period: int
+
+
+class StreamIntegration(BaseIntegration):
+    role_id: Optional[Snowflake]
+    enable_emoticons: bool
+    subscriber_count: int
+    revoked: bool
+
+
+class BotIntegration(BaseIntegration):
+    application: IntegrationApplication
+
+
+Integration = Union[BaseIntegration, StreamIntegration, BotIntegration]

discord/types/interactions.py

@@ -0,0 +1,236 @@
+"""
+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
+
+from typing import Optional, TYPE_CHECKING, Dict, TypedDict, Union, List, Literal
+from .snowflake import Snowflake
+from .components import Component, ComponentType
+from .embed import Embed
+from .channel import ChannelType
+from .member import Member
+from .role import Role
+from .user import User
+
+if TYPE_CHECKING:
+    from .message import AllowedMentions, Message
+
+
+ApplicationCommandType = Literal[1, 2, 3]
+
+class _ApplicationCommandOptional(TypedDict, total=False):
+    options: List[ApplicationCommandOption]
+    type: ApplicationCommandType
+
+
+class ApplicationCommand(_ApplicationCommandOptional):
+    id: Snowflake
+    application_id: Snowflake
+    name: str
+    description: str
+
+
+class _ApplicationCommandOptionOptional(TypedDict, total=False):
+    choices: List[ApplicationCommandOptionChoice]
+    options: List[ApplicationCommandOption]
+
+
+ApplicationCommandOptionType = Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+
+
+class ApplicationCommandOption(_ApplicationCommandOptionOptional):
+    type: ApplicationCommandOptionType
+    name: str
+    description: str
+    required: bool
+
+
+class ApplicationCommandOptionChoice(TypedDict):
+    name: str
+    value: Union[str, int]
+
+
+ApplicationCommandPermissionType = Literal[1, 2]
+
+
+class ApplicationCommandPermissions(TypedDict):
+    id: Snowflake
+    type: ApplicationCommandPermissionType
+    permission: bool
+
+
+class BaseGuildApplicationCommandPermissions(TypedDict):
+    permissions: List[ApplicationCommandPermissions]
+
+
+class PartialGuildApplicationCommandPermissions(BaseGuildApplicationCommandPermissions):
+    id: Snowflake
+
+
+class GuildApplicationCommandPermissions(PartialGuildApplicationCommandPermissions):
+    application_id: Snowflake
+    guild_id: Snowflake
+
+
+InteractionType = Literal[1, 2, 3]
+
+
+class _ApplicationCommandInteractionDataOption(TypedDict):
+    name: str
+
+
+class _ApplicationCommandInteractionDataOptionSubcommand(_ApplicationCommandInteractionDataOption):
+    type: Literal[1, 2]
+    options: List[ApplicationCommandInteractionDataOption]
+
+
+class _ApplicationCommandInteractionDataOptionString(_ApplicationCommandInteractionDataOption):
+    type: Literal[3]
+    value: str
+
+
+class _ApplicationCommandInteractionDataOptionInteger(_ApplicationCommandInteractionDataOption):
+    type: Literal[4]
+    value: int
+
+
+class _ApplicationCommandInteractionDataOptionBoolean(_ApplicationCommandInteractionDataOption):
+    type: Literal[5]
+    value: bool
+
+
+class _ApplicationCommandInteractionDataOptionSnowflake(_ApplicationCommandInteractionDataOption):
+    type: Literal[6, 7, 8, 9]
+    value: Snowflake
+
+
+class _ApplicationCommandInteractionDataOptionNumber(_ApplicationCommandInteractionDataOption):
+    type: Literal[10]
+    value: float
+
+
+ApplicationCommandInteractionDataOption = Union[
+    _ApplicationCommandInteractionDataOptionString,
+    _ApplicationCommandInteractionDataOptionInteger,
+    _ApplicationCommandInteractionDataOptionSubcommand,
+    _ApplicationCommandInteractionDataOptionBoolean,
+    _ApplicationCommandInteractionDataOptionSnowflake,
+    _ApplicationCommandInteractionDataOptionNumber,
+]
+
+
+class ApplicationCommandResolvedPartialChannel(TypedDict):
+    id: Snowflake
+    type: ChannelType
+    permissions: str
+    name: str
+
+
+class ApplicationCommandInteractionDataResolved(TypedDict, total=False):
+    users: Dict[Snowflake, User]
+    members: Dict[Snowflake, Member]
+    roles: Dict[Snowflake, Role]
+    channels: Dict[Snowflake, ApplicationCommandResolvedPartialChannel]
+
+
+class _ApplicationCommandInteractionDataOptional(TypedDict, total=False):
+    options: List[ApplicationCommandInteractionDataOption]
+    resolved: ApplicationCommandInteractionDataResolved
+    target_id: Snowflake
+    type: ApplicationCommandType
+
+
+class ApplicationCommandInteractionData(_ApplicationCommandInteractionDataOptional):
+    id: Snowflake
+    name: str
+
+
+class _ComponentInteractionDataOptional(TypedDict, total=False):
+    values: List[str]
+
+
+class ComponentInteractionData(_ComponentInteractionDataOptional):
+    custom_id: str
+    component_type: ComponentType
+
+
+InteractionData = Union[ApplicationCommandInteractionData, ComponentInteractionData]
+
+
+class _InteractionOptional(TypedDict, total=False):
+    data: InteractionData
+    guild_id: Snowflake
+    channel_id: Snowflake
+    member: Member
+    user: User
+    message: Message
+
+
+class Interaction(_InteractionOptional):
+    id: Snowflake
+    application_id: Snowflake
+    type: InteractionType
+    token: str
+    version: int
+
+
+class InteractionApplicationCommandCallbackData(TypedDict, total=False):
+    tts: bool
+    content: str
+    embeds: List[Embed]
+    allowed_mentions: AllowedMentions
+    flags: int
+    components: List[Component]
+
+
+InteractionResponseType = Literal[1, 4, 5, 6, 7]
+
+
+class _InteractionResponseOptional(TypedDict, total=False):
+    data: InteractionApplicationCommandCallbackData
+
+
+class InteractionResponse(_InteractionResponseOptional):
+    type: InteractionResponseType
+
+
+class MessageInteraction(TypedDict):
+    id: Snowflake
+    type: InteractionType
+    name: str
+    user: User
+
+
+
+
+
+class _EditApplicationCommandOptional(TypedDict, total=False):
+    description: str
+    options: Optional[List[ApplicationCommandOption]]
+    type: ApplicationCommandType
+
+
+class EditApplicationCommand(_EditApplicationCommandOptional):
+    name: str
+    default_permission: bool

discord/types/invite.py

@@ -0,0 +1,99 @@
+"""
+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
+
+from typing import Literal, Optional, TypedDict, Union
+
+from .snowflake import Snowflake
+from .guild import InviteGuild, _GuildPreviewUnique
+from .channel import PartialChannel
+from .user import PartialUser
+from .appinfo import PartialAppInfo
+
+InviteTargetType = Literal[1, 2]
+
+
+class _InviteOptional(TypedDict, total=False):
+    guild: InviteGuild
+    inviter: PartialUser
+    target_user: PartialUser
+    target_type: InviteTargetType
+    target_application: PartialAppInfo
+
+
+class _InviteMetadata(TypedDict, total=False):
+    uses: int
+    max_uses: int
+    max_age: int
+    temporary: bool
+    created_at: str
+    expires_at: Optional[str]
+
+
+class VanityInvite(_InviteMetadata):
+    code: Optional[str]
+
+
+class IncompleteInvite(_InviteMetadata):
+    code: str
+    channel: PartialChannel
+
+
+class Invite(IncompleteInvite, _InviteOptional):
+    ...
+
+
+class InviteWithCounts(Invite, _GuildPreviewUnique):
+    ...
+
+
+class _GatewayInviteCreateOptional(TypedDict, total=False):
+    guild_id: Snowflake
+    inviter: PartialUser
+    target_type: InviteTargetType
+    target_user: PartialUser
+    target_application: PartialAppInfo
+
+
+class GatewayInviteCreate(_GatewayInviteCreateOptional):
+    channel_id: Snowflake
+    code: str
+    created_at: str
+    max_age: int
+    max_uses: int
+    temporary: bool
+    uses: bool
+
+
+class _GatewayInviteDeleteOptional(TypedDict, total=False):
+    guild_id: Snowflake
+
+
+class GatewayInviteDelete(_GatewayInviteDeleteOptional):
+    channel_id: Snowflake
+    code: str
+
+
+GatewayInvite = Union[GatewayInviteCreate, GatewayInviteDelete]

discord/types/member.py

@@ -0,0 +1,63 @@
+"""
+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 typing import TypedDict
+from .snowflake import SnowflakeList
+from .user import User
+
+
+class Nickname(TypedDict):
+    nick: str
+
+
+class PartialMember(TypedDict):
+    roles: SnowflakeList
+    joined_at: str
+    deaf: str
+    mute: str
+
+
+class Member(PartialMember, total=False):
+    avatar: str
+    user: User
+    nick: str
+    premium_since: str
+    pending: bool
+    permissions: str
+
+
+class _OptionalMemberWithUser(PartialMember, total=False):
+    avatar: str
+    nick: str
+    premium_since: str
+    pending: bool
+    permissions: str
+
+
+class MemberWithUser(_OptionalMemberWithUser):
+    user: User
+
+
+class UserWithMember(User, total=False):
+    member: _OptionalMemberWithUser

discord/types/message.py

@@ -0,0 +1,138 @@
+"""
+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
+
+from typing import List, Literal, Optional, TypedDict, Union
+from .snowflake import Snowflake, SnowflakeList
+from .member import Member, UserWithMember
+from .user import User
+from .emoji import PartialEmoji
+from .embed import Embed
+from .channel import ChannelType
+from .components import Component
+from .interactions import MessageInteraction
+from .sticker import StickerItem
+
+
+class ChannelMention(TypedDict):
+    id: Snowflake
+    guild_id: Snowflake
+    type: ChannelType
+    name: str
+
+
+class Reaction(TypedDict):
+    count: int
+    me: bool
+    emoji: PartialEmoji
+
+
+class _AttachmentOptional(TypedDict, total=False):
+    height: Optional[int]
+    width: Optional[int]
+    content_type: str
+    spoiler: bool
+
+
+class Attachment(_AttachmentOptional):
+    id: Snowflake
+    filename: str
+    size: int
+    url: str
+    proxy_url: str
+
+
+MessageActivityType = Literal[1, 2, 3, 5]
+
+
+class MessageActivity(TypedDict):
+    type: MessageActivityType
+    party_id: str
+
+
+class _MessageApplicationOptional(TypedDict, total=False):
+    cover_image: str
+
+
+class MessageApplication(_MessageApplicationOptional):
+    id: Snowflake
+    description: str
+    icon: Optional[str]
+    name: str
+
+
+class MessageReference(TypedDict, total=False):
+    message_id: Snowflake
+    channel_id: Snowflake
+    guild_id: Snowflake
+    fail_if_not_exists: bool
+
+
+class _MessageOptional(TypedDict, total=False):
+    guild_id: Snowflake
+    member: Member
+    mention_channels: List[ChannelMention]
+    reactions: List[Reaction]
+    nonce: Union[int, str]
+    webhook_id: Snowflake
+    activity: MessageActivity
+    application: MessageApplication
+    application_id: Snowflake
+    message_reference: MessageReference
+    flags: int
+    sticker_items: List[StickerItem]
+    referenced_message: Optional[Message]
+    interaction: MessageInteraction
+    components: List[Component]
+
+
+MessageType = Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 18, 19, 20, 21]
+
+
+class Message(_MessageOptional):
+    id: Snowflake
+    channel_id: Snowflake
+    author: User
+    content: str
+    timestamp: str
+    edited_timestamp: Optional[str]
+    tts: bool
+    mention_everyone: bool
+    mentions: List[UserWithMember]
+    mention_roles: SnowflakeList
+    attachments: List[Attachment]
+    embeds: List[Embed]
+    pinned: bool
+    type: MessageType
+
+
+AllowedMentionType = Literal['roles', 'users', 'everyone']
+
+
+class AllowedMentions(TypedDict):
+    parse: List[AllowedMentionType]
+    roles: SnowflakeList
+    users: SnowflakeList
+    replied_user: bool

discord/types/raw_models.py

@@ -0,0 +1,87 @@
+"""
+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 typing import TypedDict, List
+from .snowflake import Snowflake
+from .member import Member
+from .emoji import PartialEmoji
+
+
+class _MessageEventOptional(TypedDict, total=False):
+    guild_id: Snowflake
+
+
+class MessageDeleteEvent(_MessageEventOptional):
+    id: Snowflake
+    channel_id: Snowflake
+
+
+class BulkMessageDeleteEvent(_MessageEventOptional):
+    ids: List[Snowflake]
+    channel_id: Snowflake
+
+
+class _ReactionActionEventOptional(TypedDict, total=False):
+    guild_id: Snowflake
+    member: Member
+
+
+class MessageUpdateEvent(_MessageEventOptional):
+    id: Snowflake
+    channel_id: Snowflake
+
+
+class ReactionActionEvent(_ReactionActionEventOptional):
+    user_id: Snowflake
+    channel_id: Snowflake
+    message_id: Snowflake
+    emoji: PartialEmoji
+
+
+class _ReactionClearEventOptional(TypedDict, total=False):
+    guild_id: Snowflake
+
+
+class ReactionClearEvent(_ReactionClearEventOptional):
+    channel_id: Snowflake
+    message_id: Snowflake
+
+
+class _ReactionClearEmojiEventOptional(TypedDict, total=False):
+    guild_id: Snowflake
+
+
+class ReactionClearEmojiEvent(_ReactionClearEmojiEventOptional):
+    channel_id: int
+    message_id: int
+    emoji: PartialEmoji
+
+
+class _IntegrationDeleteEventOptional(TypedDict, total=False):
+    application_id: Snowflake
+
+
+class IntegrationDeleteEvent(_IntegrationDeleteEventOptional):
+    id: Snowflake
+    guild_id: Snowflake

discord/types/role.py

@@ -0,0 +1,49 @@
+"""
+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
+
+from typing import TypedDict
+from .snowflake import Snowflake
+
+
+class _RoleOptional(TypedDict, total=False):
+    tags: RoleTags
+
+
+class Role(_RoleOptional):
+    id: Snowflake
+    name: str
+    color: int
+    hoist: bool
+    position: int
+    permissions: str
+    managed: bool
+    mentionable: bool
+
+
+class RoleTags(TypedDict, total=False):
+    bot_id: Snowflake
+    integration_id: Snowflake
+    premium_subscriber: None

discord/types/snowflake.py

@@ -22,7 +22,7 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
-from typing import List
+from typing import List, Union
 
-Snowflake = str
+Snowflake = Union[str, int]
 SnowflakeList = List[Snowflake]

discord/types/sticker.py

@@ -0,0 +1,93 @@
+"""
+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
+
+from typing import List, Literal, TypedDict, Union
+from .snowflake import Snowflake
+from .user import User
+
+StickerFormatType = Literal[1, 2, 3]
+
+
+class StickerItem(TypedDict):
+    id: Snowflake
+    name: str
+    format_type: StickerFormatType
+
+
+class BaseSticker(TypedDict):
+    id: Snowflake
+    name: str
+    description: str
+    tags: str
+    format_type: StickerFormatType
+
+
+class StandardSticker(BaseSticker):
+    type: Literal[1]
+    sort_value: int
+    pack_id: Snowflake
+
+
+class _GuildStickerOptional(TypedDict, total=False):
+    user: User
+
+
+class GuildSticker(BaseSticker, _GuildStickerOptional):
+    type: Literal[2]
+    available: bool
+    guild_id: Snowflake
+
+
+Sticker = Union[BaseSticker, StandardSticker, GuildSticker]
+
+
+class StickerPack(TypedDict):
+    id: Snowflake
+    stickers: List[StandardSticker]
+    name: str
+    sku_id: Snowflake
+    cover_sticker_id: Snowflake
+    description: str
+    banner_asset_id: Snowflake
+
+
+class _CreateGuildStickerOptional(TypedDict, total=False):
+    description: str
+
+
+class CreateGuildSticker(_CreateGuildStickerOptional):
+    name: str
+    tags: str
+
+
+class EditGuildSticker(TypedDict, total=False):
+    name: str
+    tags: str
+    description: str
+
+
+class ListPremiumStickerPacks(TypedDict):
+    sticker_packs: List[StickerPack]

discord/types/team.py

@@ -0,0 +1,43 @@
+"""
+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
+
+from typing import TypedDict, List, Optional
+
+from .user import PartialUser
+from .snowflake import Snowflake
+
+class TeamMember(TypedDict):
+    user: PartialUser
+    membership_state: int
+    permissions: List[str]
+    team_id: Snowflake
+
+class Team(TypedDict):
+    id: Snowflake
+    name: str
+    owner_id: Snowflake
+    members: List[TeamMember]
+    icon: Optional[str]

discord/types/template.py

@@ -0,0 +1,49 @@
+"""
+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
+
+from typing import Optional, TypedDict
+from .snowflake import Snowflake
+from .user import User
+from .guild import Guild
+
+
+class CreateTemplate(TypedDict):
+    name: str
+    icon: Optional[bytes]
+
+
+class Template(TypedDict):
+    code: str
+    name: str
+    description: Optional[str]
+    usage_count: int
+    creator_id: Snowflake
+    creator: User
+    created_at: str
+    updated_at: str
+    source_guild_id: Snowflake
+    serialized_source_guild: Guild
+    is_dirty: Optional[bool]

discord/types/threads.py

@@ -0,0 +1,75 @@
+"""
+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
+from typing import List, Literal, Optional, TypedDict
+
+from .snowflake import Snowflake
+
+ThreadType = Literal[10, 11, 12]
+ThreadArchiveDuration = Literal[60, 1440, 4320, 10080]
+
+
+class ThreadMember(TypedDict):
+    id: Snowflake
+    user_id: Snowflake
+    join_timestamp: str
+    flags: int
+
+
+class _ThreadMetadataOptional(TypedDict, total=False):
+    archiver_id: Snowflake
+    locked: bool
+    invitable: bool
+
+
+class ThreadMetadata(_ThreadMetadataOptional):
+    archived: bool
+    auto_archive_duration: ThreadArchiveDuration
+    archive_timestamp: str
+
+
+class _ThreadOptional(TypedDict, total=False):
+    member: ThreadMember
+    last_message_id: Optional[Snowflake]
+    last_pin_timestamp: Optional[Snowflake]
+
+
+class Thread(_ThreadOptional):
+    id: Snowflake
+    guild_id: Snowflake
+    parent_id: Snowflake
+    owner_id: Snowflake
+    name: str
+    type: ThreadType
+    member_count: int
+    message_count: int
+    rate_limit_per_user: int
+    thread_metadata: ThreadMetadata
+
+
+class ThreadPaginationPayload(TypedDict):
+    threads: List[Thread]
+    members: List[ThreadMember]
+    has_more: bool

discord/types/user.py

@@ -23,7 +23,7 @@ DEALINGS IN THE SOFTWARE.
 """
 
 from .snowflake import Snowflake
-from typing import Optional, TypedDict
+from typing import Literal, Optional, TypedDict
 
 
 class PartialUser(TypedDict):
@@ -31,3 +31,18 @@ class PartialUser(TypedDict):
     username: str
     discriminator: str
     avatar: Optional[str]
+
+
+PremiumType = Literal[0, 1, 2]
+
+
+class User(PartialUser, total=False):
+    bot: bool
+    system: bool
+    mfa_enabled: bool
+    local: str
+    verified: bool
+    email: Optional[str]
+    flags: int
+    premium_type: PremiumType
+    public_flags: int

discord/types/voice.py

@@ -0,0 +1,85 @@
+"""
+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 typing import Optional, TypedDict, List, Literal
+from .snowflake import Snowflake
+from .member import MemberWithUser
+
+
+SupportedModes = Literal['xsalsa20_poly1305_lite', 'xsalsa20_poly1305_suffix', 'xsalsa20_poly1305']
+
+
+class _PartialVoiceStateOptional(TypedDict, total=False):
+    member: MemberWithUser
+    self_stream: bool
+
+
+class _VoiceState(_PartialVoiceStateOptional):
+    user_id: Snowflake
+    session_id: str
+    deaf: bool
+    mute: bool
+    self_deaf: bool
+    self_mute: bool
+    self_video: bool
+    suppress: bool
+
+
+class GuildVoiceState(_VoiceState):
+    channel_id: Snowflake
+
+
+class VoiceState(_VoiceState, total=False):
+    channel_id: Optional[Snowflake]
+    guild_id: Snowflake
+
+
+class VoiceRegion(TypedDict):
+    id: str
+    name: str
+    vip: bool
+    optimal: bool
+    deprecated: bool
+    custom: bool
+
+
+class VoiceServerUpdate(TypedDict):
+    token: str
+    guild_id: Snowflake
+    endpoint: Optional[str]
+
+
+class VoiceIdentify(TypedDict):
+    server_id: Snowflake
+    user_id: Snowflake
+    session_id: str
+    token: str
+
+
+class VoiceReady(TypedDict):
+    ssrc: int
+    ip: str
+    port: int
+    modes: List[SupportedModes]
+    heartbeat_interval: int

discord/types/webhook.py

@@ -0,0 +1,70 @@
+"""
+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
+from typing import Literal, Optional, TypedDict
+from .snowflake import Snowflake
+from .user import User
+from .channel import PartialChannel
+
+
+class SourceGuild(TypedDict):
+    id: int
+    name: str
+    icon: str
+
+
+class _WebhookOptional(TypedDict, total=False):
+    guild_id: Snowflake
+    user: User
+    token: str
+
+
+WebhookType = Literal[1, 2, 3]
+
+
+class _FollowerWebhookOptional(TypedDict, total=False):
+    source_channel: PartialChannel
+    source_guild: SourceGuild
+
+
+class FollowerWebhook(_FollowerWebhookOptional):
+    channel_id: Snowflake
+    webhook_id: Snowflake
+
+
+class PartialWebhook(_WebhookOptional):
+    id: Snowflake
+    type: WebhookType
+
+
+class _FullWebhook(TypedDict, total=False):
+    name: Optional[str]
+    avatar: Optional[str]
+    channel_id: Snowflake
+    application_id: Optional[Snowflake]
+
+
+class Webhook(PartialWebhook, _FullWebhook):
+    ...

discord/types/welcome_screen.py

@@ -0,0 +1,40 @@
+"""
+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
+
+from typing import List, Optional, TypedDict
+from .snowflake import Snowflake
+
+
+class WelcomeScreen(TypedDict):
+    description: str
+    welcome_channels: List[WelcomeScreenChannel]
+
+
+class WelcomeScreenChannel(TypedDict):
+    channel_id: Snowflake
+    description: str
+    emoji_id: Optional[Snowflake]
+    emoji_name: Optional[str]

discord/types/widget.py

@@ -0,0 +1,63 @@
+"""
+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 typing import List, Optional, TypedDict
+from .activity import Activity
+from .snowflake import Snowflake
+from .user import User
+
+
+class WidgetChannel(TypedDict):
+    id: Snowflake
+    name: str
+    position: int
+
+
+class WidgetMember(User, total=False):
+    nick: str
+    game: Activity
+    status: str
+    avatar_url: str
+    deaf: bool
+    self_deaf: bool
+    mute: bool
+    self_mute: bool
+    suppress: bool
+
+
+class _WidgetOptional(TypedDict, total=False):
+    channels: List[WidgetChannel]
+    members: List[WidgetMember]
+    presence_count: int
+
+
+class Widget(_WidgetOptional):
+    id: Snowflake
+    name: str
+    instant_invite: str
+
+
+class WidgetSettings(TypedDict):
+    enabled: bool
+    channel_id: Optional[Snowflake]

discord/ui/__init__.py

@@ -0,0 +1,15 @@
+"""
+discord.ui
+~~~~~~~~~~~
+
+Bot UI Kit helper for the Discord API
+
+:copyright: (c) 2015-present Rapptz
+:license: MIT, see LICENSE for more details.
+
+"""
+
+from .view import *
+from .item import *
+from .button import *
+from .select import *

discord/ui/button.py

@@ -0,0 +1,290 @@
+"""
+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
+
+from typing import Callable, Optional, TYPE_CHECKING, Tuple, Type, TypeVar, Union
+import inspect
+import os
+
+
+from .item import Item, ItemCallbackType
+from ..enums import ButtonStyle, ComponentType
+from ..partial_emoji import PartialEmoji, _EmojiTag
+from ..components import Button as ButtonComponent
+
+__all__ = (
+    'Button',
+    'button',
+)
+
+if TYPE_CHECKING:
+    from .view import View
+    from ..emoji import Emoji
+
+B = TypeVar('B', bound='Button')
+V = TypeVar('V', bound='View', covariant=True)
+
+
+class Button(Item[V]):
+    """Represents a UI button.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    ------------
+    style: :class:`discord.ButtonStyle`
+        The style of the button.
+    custom_id: Optional[:class:`str`]
+        The ID of the button that gets received during an interaction.
+        If this button is for a URL, it does not have a custom ID.
+    url: Optional[:class:`str`]
+        The URL this button sends you to.
+    disabled: :class:`bool`
+        Whether the button is disabled or not.
+    label: Optional[:class:`str`]
+        The label of the button, if any.
+    emoji: Optional[Union[:class:`.PartialEmoji`, :class:`.Emoji`, :class:`str`]]
+        The emoji of the button, if available.
+    row: Optional[:class:`int`]
+        The relative row this button belongs to. A Discord component can only have 5
+        rows. By default, items are arranged automatically into those 5 rows. If you'd
+        like to control the relative positioning of the row then passing an index is advised.
+        For example, row=1 will show up before row=2. Defaults to ``None``, which is automatic
+        ordering. The row number must be between 0 and 4 (i.e. zero indexed).
+    """
+
+    __item_repr_attributes__: Tuple[str, ...] = (
+        'style',
+        'url',
+        'disabled',
+        'label',
+        'emoji',
+        'row',
+    )
+
+    def __init__(
+        self,
+        *,
+        style: ButtonStyle = ButtonStyle.secondary,
+        label: Optional[str] = None,
+        disabled: bool = False,
+        custom_id: Optional[str] = None,
+        url: Optional[str] = None,
+        emoji: Optional[Union[str, Emoji, PartialEmoji]] = None,
+        row: Optional[int] = None,
+    ):
+        super().__init__()
+        if custom_id is not None and url is not None:
+            raise TypeError('cannot mix both url and custom_id with Button')
+
+        self._provided_custom_id = custom_id is not None
+        if url is None and custom_id is None:
+            custom_id = os.urandom(16).hex()
+
+        if url is not None:
+            style = ButtonStyle.link
+
+        if emoji is not None:
+            if isinstance(emoji, str):
+                emoji = PartialEmoji.from_str(emoji)
+            elif isinstance(emoji, _EmojiTag):
+                emoji = emoji._to_partial()
+            else:
+                raise TypeError(f'expected emoji to be str, Emoji, or PartialEmoji not {emoji.__class__}')
+
+        self._underlying = ButtonComponent._raw_construct(
+            type=ComponentType.button,
+            custom_id=custom_id,
+            url=url,
+            disabled=disabled,
+            label=label,
+            style=style,
+            emoji=emoji,
+        )
+        self.row = row
+
+    @property
+    def style(self) -> ButtonStyle:
+        """:class:`discord.ButtonStyle`: The style of the button."""
+        return self._underlying.style
+
+    @style.setter
+    def style(self, value: ButtonStyle):
+        self._underlying.style = value
+
+    @property
+    def custom_id(self) -> Optional[str]:
+        """Optional[:class:`str`]: The ID of the button that gets received during an interaction.
+
+        If this button is for a URL, it does not have a custom ID.
+        """
+        return self._underlying.custom_id
+
+    @custom_id.setter
+    def custom_id(self, value: Optional[str]):
+        if value is not None and not isinstance(value, str):
+            raise TypeError('custom_id must be None or str')
+
+        self._underlying.custom_id = value
+
+    @property
+    def url(self) -> Optional[str]:
+        """Optional[:class:`str`]: The URL this button sends you to."""
+        return self._underlying.url
+
+    @url.setter
+    def url(self, value: Optional[str]):
+        if value is not None and not isinstance(value, str):
+            raise TypeError('url must be None or str')
+        self._underlying.url = value
+
+    @property
+    def disabled(self) -> bool:
+        """:class:`bool`: Whether the button is disabled or not."""
+        return self._underlying.disabled
+
+    @disabled.setter
+    def disabled(self, value: bool):
+        self._underlying.disabled = bool(value)
+
+    @property
+    def label(self) -> Optional[str]:
+        """Optional[:class:`str`]: The label of the button, if available."""
+        return self._underlying.label
+
+    @label.setter
+    def label(self, value: Optional[str]):
+        self._underlying.label = str(value) if value is not None else value
+
+    @property
+    def emoji(self) -> Optional[PartialEmoji]:
+        """Optional[:class:`.PartialEmoji`]: The emoji of the button, if available."""
+        return self._underlying.emoji
+
+    @emoji.setter
+    def emoji(self, value: Optional[Union[str, Emoji, PartialEmoji]]):  # type: ignore
+        if value is not None:
+            if isinstance(value, str):
+                self._underlying.emoji = PartialEmoji.from_str(value)
+            elif isinstance(value, _EmojiTag):
+                self._underlying.emoji = value._to_partial()
+            else:
+                raise TypeError(f'expected str, Emoji, or PartialEmoji, received {value.__class__} instead')
+        else:
+            self._underlying.emoji = None
+
+    @classmethod
+    def from_component(cls: Type[B], button: ButtonComponent) -> B:
+        return cls(
+            style=button.style,
+            label=button.label,
+            disabled=button.disabled,
+            custom_id=button.custom_id,
+            url=button.url,
+            emoji=button.emoji,
+            row=None,
+        )
+
+    @property
+    def type(self) -> ComponentType:
+        return self._underlying.type
+
+    def to_component_dict(self):
+        return self._underlying.to_dict()
+
+    def is_dispatchable(self) -> bool:
+        return self.custom_id is not None
+
+    def is_persistent(self) -> bool:
+        if self.style is ButtonStyle.link:
+            return self.url is not None
+        return super().is_persistent()
+
+    def refresh_component(self, button: ButtonComponent) -> None:
+        self._underlying = button
+
+
+def button(
+    *,
+    label: Optional[str] = None,
+    custom_id: Optional[str] = None,
+    disabled: bool = False,
+    style: ButtonStyle = ButtonStyle.secondary,
+    emoji: Optional[Union[str, Emoji, PartialEmoji]] = None,
+    row: Optional[int] = None,
+) -> Callable[[ItemCallbackType], ItemCallbackType]:
+    """A decorator that attaches a button to a component.
+
+    The function being decorated should have three parameters, ``self`` representing
+    the :class:`discord.ui.View`, the :class:`discord.ui.Button` being pressed and
+    the :class:`discord.Interaction` you receive.
+
+    .. note::
+
+        Buttons with a URL cannot be created with this function.
+        Consider creating a :class:`Button` manually instead.
+        This is because buttons with a URL do not have a callback
+        associated with them since Discord does not do any processing
+        with it.
+
+    Parameters
+    ------------
+    label: Optional[:class:`str`]
+        The label of the button, if any.
+    custom_id: Optional[:class:`str`]
+        The ID of the button that gets received during an interaction.
+        It is recommended not to set this parameter to prevent conflicts.
+    style: :class:`.ButtonStyle`
+        The style of the button. Defaults to :attr:`.ButtonStyle.grey`.
+    disabled: :class:`bool`
+        Whether the button is disabled or not. Defaults to ``False``.
+    emoji: Optional[Union[:class:`str`, :class:`.Emoji`, :class:`.PartialEmoji`]]
+        The emoji of the button. This can be in string form or a :class:`.PartialEmoji`
+        or a full :class:`.Emoji`.
+    row: Optional[:class:`int`]
+        The relative row this button belongs to. A Discord component can only have 5
+        rows. By default, items are arranged automatically into those 5 rows. If you'd
+        like to control the relative positioning of the row then passing an index is advised.
+        For example, row=1 will show up before row=2. Defaults to ``None``, which is automatic
+        ordering. The row number must be between 0 and 4 (i.e. zero indexed).
+    """
+
+    def decorator(func: ItemCallbackType) -> ItemCallbackType:
+        if not inspect.iscoroutinefunction(func):
+            raise TypeError('button function must be a coroutine function')
+
+        func.__discord_ui_model_type__ = Button
+        func.__discord_ui_model_kwargs__ = {
+            'style': style,
+            'custom_id': custom_id,
+            'url': None,
+            'disabled': disabled,
+            'label': label,
+            'emoji': emoji,
+            'row': row,
+        }
+        return func
+
+    return decorator

discord/ui/item.py

@@ -0,0 +1,131 @@
+"""
+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
+
+from typing import Any, Callable, Coroutine, Dict, Generic, Optional, TYPE_CHECKING, Tuple, Type, TypeVar
+
+from ..interactions import Interaction
+
+__all__ = (
+    'Item',
+)
+
+if TYPE_CHECKING:
+    from ..enums import ComponentType
+    from .view import View
+    from ..components import Component
+
+I = TypeVar('I', bound='Item')
+V = TypeVar('V', bound='View', covariant=True)
+ItemCallbackType = Callable[[Any, I, Interaction], Coroutine[Any, Any, Any]]
+
+
+class Item(Generic[V]):
+    """Represents the base UI item that all UI components inherit from.
+
+    The current UI items supported are:
+
+    - :class:`discord.ui.Button`
+    - :class:`discord.ui.Select`
+
+    .. versionadded:: 2.0
+    """
+
+    __item_repr_attributes__: Tuple[str, ...] = ('row',)
+
+    def __init__(self):
+        self._view: Optional[V] = None
+        self._row: Optional[int] = None
+        self._rendered_row: Optional[int] = None
+        # This works mostly well but there is a gotcha with
+        # the interaction with from_component, since that technically provides
+        # a custom_id most dispatchable items would get this set to True even though
+        # it might not be provided by the library user. However, this edge case doesn't
+        # actually affect the intended purpose of this check because from_component is
+        # only called upon edit and we're mainly interested during initial creation time.
+        self._provided_custom_id: bool = False
+
+    def to_component_dict(self) -> Dict[str, Any]:
+        raise NotImplementedError
+
+    def refresh_component(self, component: Component) -> None:
+        return None
+
+    def refresh_state(self, interaction: Interaction) -> None:
+        return None
+
+    @classmethod
+    def from_component(cls: Type[I], component: Component) -> I:
+        return cls()
+
+    @property
+    def type(self) -> ComponentType:
+        raise NotImplementedError
+
+    def is_dispatchable(self) -> bool:
+        return False
+
+    def is_persistent(self) -> bool:
+        return self._provided_custom_id
+
+    def __repr__(self) -> str:
+        attrs = ' '.join(f'{key}={getattr(self, key)!r}' for key in self.__item_repr_attributes__)
+        return f'<{self.__class__.__name__} {attrs}>'
+
+    @property
+    def row(self) -> Optional[int]:
+        return self._row
+
+    @row.setter
+    def row(self, value: Optional[int]):
+        if value is None:
+            self._row = None
+        elif 5 > value >= 0:
+            self._row = value
+        else:
+            raise ValueError('row cannot be negative or greater than or equal to 5')
+
+    @property
+    def width(self) -> int:
+        return 1
+
+    @property
+    def view(self) -> Optional[V]:
+        """Optional[:class:`View`]: The underlying view for this item."""
+        return self._view
+
+    async def callback(self, interaction: Interaction):
+        """|coro|
+
+        The callback associated with this UI item.
+
+        This can be overriden by subclasses.
+
+        Parameters
+        -----------
+        interaction: :class:`.Interaction`
+            The interaction that triggered this UI item.
+        """
+        pass

discord/ui/select.py

@@ -0,0 +1,357 @@
+"""
+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
+from typing import List, Optional, TYPE_CHECKING, Tuple, TypeVar, Type, Callable, Union
+import inspect
+import os
+
+from .item import Item, ItemCallbackType
+from ..enums import ComponentType
+from ..partial_emoji import PartialEmoji
+from ..emoji import Emoji
+from ..interactions import Interaction
+from ..utils import MISSING
+from ..components import (
+    SelectOption,
+    SelectMenu,
+)
+
+__all__ = (
+    'Select',
+    'select',
+)
+
+if TYPE_CHECKING:
+    from .view import View
+    from ..types.components import SelectMenu as SelectMenuPayload
+    from ..types.interactions import (
+        ComponentInteractionData,
+    )
+
+S = TypeVar('S', bound='Select')
+V = TypeVar('V', bound='View', covariant=True)
+
+
+class Select(Item[V]):
+    """Represents a UI select menu.
+
+    This is usually represented as a drop down menu.
+
+    In order to get the selected items that the user has chosen, use :attr:`Select.values`.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    ------------
+    custom_id: :class:`str`
+        The ID of the select menu that gets received during an interaction.
+        If not given then one is generated for you.
+    placeholder: Optional[:class:`str`]
+        The placeholder text that is shown if nothing is selected, if any.
+    min_values: :class:`int`
+        The minimum number of items that must be chosen for this select menu.
+        Defaults to 1 and must be between 1 and 25.
+    max_values: :class:`int`
+        The maximum number of items that must be chosen for this select menu.
+        Defaults to 1 and must be between 1 and 25.
+    options: List[:class:`discord.SelectOption`]
+        A list of options that can be selected in this menu.
+    disabled: :class:`bool`
+        Whether the select is disabled or not.
+    row: Optional[:class:`int`]
+        The relative row this select menu belongs to. A Discord component can only have 5
+        rows. By default, items are arranged automatically into those 5 rows. If you'd
+        like to control the relative positioning of the row then passing an index is advised.
+        For example, row=1 will show up before row=2. Defaults to ``None``, which is automatic
+        ordering. The row number must be between 0 and 4 (i.e. zero indexed).
+    """
+
+    __item_repr_attributes__: Tuple[str, ...] = (
+        'placeholder',
+        'min_values',
+        'max_values',
+        'options',
+        'disabled',
+    )
+
+    def __init__(
+        self,
+        *,
+        custom_id: str = MISSING,
+        placeholder: Optional[str] = None,
+        min_values: int = 1,
+        max_values: int = 1,
+        options: List[SelectOption] = MISSING,
+        disabled: bool = False,
+        row: Optional[int] = None,
+    ) -> None:
+        super().__init__()
+        self._selected_values: List[str] = []
+        self._provided_custom_id = custom_id is not MISSING
+        custom_id = os.urandom(16).hex() if custom_id is MISSING else custom_id
+        options = [] if options is MISSING else options
+        self._underlying = SelectMenu._raw_construct(
+            custom_id=custom_id,
+            type=ComponentType.select,
+            placeholder=placeholder,
+            min_values=min_values,
+            max_values=max_values,
+            options=options,
+            disabled=disabled,
+        )
+        self.row = row
+
+    @property
+    def custom_id(self) -> str:
+        """:class:`str`: The ID of the select menu that gets received during an interaction."""
+        return self._underlying.custom_id
+
+    @custom_id.setter
+    def custom_id(self, value: str):
+        if not isinstance(value, str):
+            raise TypeError('custom_id must be None or str')
+
+        self._underlying.custom_id = value
+
+    @property
+    def placeholder(self) -> Optional[str]:
+        """Optional[:class:`str`]: The placeholder text that is shown if nothing is selected, if any."""
+        return self._underlying.placeholder
+
+    @placeholder.setter
+    def placeholder(self, value: Optional[str]):
+        if value is not None and not isinstance(value, str):
+            raise TypeError('placeholder must be None or str')
+
+        self._underlying.placeholder = value
+
+    @property
+    def min_values(self) -> int:
+        """:class:`int`: The minimum number of items that must be chosen for this select menu."""
+        return self._underlying.min_values
+
+    @min_values.setter
+    def min_values(self, value: int):
+        self._underlying.min_values = int(value)
+
+    @property
+    def max_values(self) -> int:
+        """:class:`int`: The maximum number of items that must be chosen for this select menu."""
+        return self._underlying.max_values
+
+    @max_values.setter
+    def max_values(self, value: int):
+        self._underlying.max_values = int(value)
+
+    @property
+    def options(self) -> List[SelectOption]:
+        """List[:class:`discord.SelectOption`]: A list of options that can be selected in this menu."""
+        return self._underlying.options
+
+    @options.setter
+    def options(self, value: List[SelectOption]):
+        if not isinstance(value, list):
+            raise TypeError('options must be a list of SelectOption')
+        if not all(isinstance(obj, SelectOption) for obj in value):
+            raise TypeError('all list items must subclass SelectOption')
+
+        self._underlying.options = value
+
+    def add_option(
+        self,
+        *,
+        label: str,
+        value: str = MISSING,
+        description: Optional[str] = None,
+        emoji: Optional[Union[str, Emoji, PartialEmoji]] = None,
+        default: bool = False,
+    ):
+        """Adds an option to the select menu.
+
+        To append a pre-existing :class:`discord.SelectOption` use the
+        :meth:`append_option` method instead.
+
+        Parameters
+        -----------
+        label: :class:`str`
+            The label of the option. This is displayed to users.
+            Can only be up to 100 characters.
+        value: :class:`str`
+            The value of the option. This is not displayed to users.
+            If not given, defaults to the label. Can only be up to 100 characters.
+        description: Optional[:class:`str`]
+            An additional description of the option, if any.
+            Can only be up to 100 characters.
+        emoji: Optional[Union[:class:`str`, :class:`.Emoji`, :class:`.PartialEmoji`]]
+            The emoji of the option, if available. This can either be a string representing
+            the custom or unicode emoji or an instance of :class:`.PartialEmoji` or :class:`.Emoji`.
+        default: :class:`bool`
+            Whether this option is selected by default.
+
+        Raises
+        -------
+        ValueError
+            The number of options exceeds 25.
+        """
+
+        option = SelectOption(
+            label=label,
+            value=value,
+            description=description,
+            emoji=emoji,
+            default=default,
+        )
+
+
+        self.append_option(option)
+
+    def append_option(self, option: SelectOption):
+        """Appends an option to the select menu.
+
+        Parameters
+        -----------
+        option: :class:`discord.SelectOption`
+            The option to append to the select menu.
+
+        Raises
+        -------
+        ValueError
+            The number of options exceeds 25.
+        """
+
+        if len(self._underlying.options) > 25:
+            raise ValueError('maximum number of options already provided')
+
+        self._underlying.options.append(option)
+
+    @property
+    def disabled(self) -> bool:
+        """:class:`bool`: Whether the select is disabled or not."""
+        return self._underlying.disabled
+
+    @disabled.setter
+    def disabled(self, value: bool):
+        self._underlying.disabled = bool(value)
+
+    @property
+    def values(self) -> List[str]:
+        """List[:class:`str`]: A list of values that have been selected by the user."""
+        return self._selected_values
+
+    @property
+    def width(self) -> int:
+        return 5
+
+    def to_component_dict(self) -> SelectMenuPayload:
+        return self._underlying.to_dict()
+
+    def refresh_component(self, component: SelectMenu) -> None:
+        self._underlying = component
+
+    def refresh_state(self, interaction: Interaction) -> None:
+        data: ComponentInteractionData = interaction.data  # type: ignore
+        self._selected_values = data.get('values', [])
+
+    @classmethod
+    def from_component(cls: Type[S], component: SelectMenu) -> S:
+        return cls(
+            custom_id=component.custom_id,
+            placeholder=component.placeholder,
+            min_values=component.min_values,
+            max_values=component.max_values,
+            options=component.options,
+            disabled=component.disabled,
+            row=None,
+        )
+
+    @property
+    def type(self) -> ComponentType:
+        return self._underlying.type
+
+    def is_dispatchable(self) -> bool:
+        return True
+
+
+def select(
+    *,
+    placeholder: Optional[str] = None,
+    custom_id: str = MISSING,
+    min_values: int = 1,
+    max_values: int = 1,
+    options: List[SelectOption] = MISSING,
+    disabled: bool = False,
+    row: Optional[int] = None,
+) -> Callable[[ItemCallbackType], ItemCallbackType]:
+    """A decorator that attaches a select menu to a component.
+
+    The function being decorated should have three parameters, ``self`` representing
+    the :class:`discord.ui.View`, the :class:`discord.ui.Select` being pressed and
+    the :class:`discord.Interaction` you receive.
+
+    In order to get the selected items that the user has chosen within the callback
+    use :attr:`Select.values`.
+
+    Parameters
+    ------------
+    placeholder: Optional[:class:`str`]
+        The placeholder text that is shown if nothing is selected, if any.
+    custom_id: :class:`str`
+        The ID of the select menu that gets received during an interaction.
+        It is recommended not to set this parameter to prevent conflicts.
+    row: Optional[:class:`int`]
+        The relative row this select menu belongs to. A Discord component can only have 5
+        rows. By default, items are arranged automatically into those 5 rows. If you'd
+        like to control the relative positioning of the row then passing an index is advised.
+        For example, row=1 will show up before row=2. Defaults to ``None``, which is automatic
+        ordering. The row number must be between 0 and 4 (i.e. zero indexed).
+    min_values: :class:`int`
+        The minimum number of items that must be chosen for this select menu.
+        Defaults to 1 and must be between 1 and 25.
+    max_values: :class:`int`
+        The maximum number of items that must be chosen for this select menu.
+        Defaults to 1 and must be between 1 and 25.
+    options: List[:class:`discord.SelectOption`]
+        A list of options that can be selected in this menu.
+    disabled: :class:`bool`
+        Whether the select is disabled or not. Defaults to ``False``.
+    """
+
+    def decorator(func: ItemCallbackType) -> ItemCallbackType:
+        if not inspect.iscoroutinefunction(func):
+            raise TypeError('select function must be a coroutine function')
+
+        func.__discord_ui_model_type__ = Select
+        func.__discord_ui_model_kwargs__ = {
+            'placeholder': placeholder,
+            'custom_id': custom_id,
+            'row': row,
+            'min_values': min_values,
+            'max_values': max_values,
+            'options': options,
+            'disabled': disabled,
+        }
+        return func
+
+    return decorator

discord/ui/view.py

@@ -0,0 +1,529 @@
+"""
+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
+from typing import Any, Callable, ClassVar, Dict, Iterator, List, Optional, Sequence, TYPE_CHECKING, Tuple
+from functools import partial
+from itertools import groupby
+
+import traceback
+import asyncio
+import sys
+import time
+import os
+from .item import Item, ItemCallbackType
+from ..components import (
+    Component,
+    ActionRow as ActionRowComponent,
+    _component_factory,
+    Button as ButtonComponent,
+    SelectMenu as SelectComponent,
+)
+
+__all__ = (
+    'View',
+)
+
+
+if TYPE_CHECKING:
+    from ..interactions import Interaction
+    from ..message import Message
+    from ..types.components import Component as ComponentPayload
+    from ..state import ConnectionState
+
+
+def _walk_all_components(components: List[Component]) -> Iterator[Component]:
+    for item in components:
+        if isinstance(item, ActionRowComponent):
+            yield from item.children
+        else:
+            yield item
+
+
+def _component_to_item(component: Component) -> Item:
+    if isinstance(component, ButtonComponent):
+        from .button import Button
+
+        return Button.from_component(component)
+    if isinstance(component, SelectComponent):
+        from .select import Select
+
+        return Select.from_component(component)
+    return Item.from_component(component)
+
+
+class _ViewWeights:
+    __slots__ = (
+        'weights',
+    )
+
+    def __init__(self, children: List[Item]):
+        self.weights: List[int] = [0, 0, 0, 0, 0]
+
+        key = lambda i: sys.maxsize if i.row is None else i.row
+        children = sorted(children, key=key)
+        for row, group in groupby(children, key=key):
+            for item in group:
+                self.add_item(item)
+
+    def find_open_space(self, item: Item) -> int:
+        for index, weight in enumerate(self.weights):
+            if weight + item.width <= 5:
+                return index
+
+        raise ValueError('could not find open space for item')
+
+    def add_item(self, item: Item) -> None:
+        if item.row is not None:
+            total = self.weights[item.row] + item.width
+            if total > 5:
+                raise ValueError(f'item would not fit at row {item.row} ({total} > 5 width)')
+            self.weights[item.row] = total
+            item._rendered_row = item.row
+        else:
+            index = self.find_open_space(item)
+            self.weights[index] += item.width
+            item._rendered_row = index
+
+    def remove_item(self, item: Item) -> None:
+        if item._rendered_row is not None:
+            self.weights[item._rendered_row] -= item.width
+            item._rendered_row = None
+
+    def clear(self) -> None:
+        self.weights = [0, 0, 0, 0, 0]
+
+
+class View:
+    """Represents a UI view.
+
+    This object must be inherited to create a UI within Discord.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    -----------
+    timeout: Optional[:class:`float`]
+        Timeout in seconds from last interaction with the UI before no longer accepting input.
+        If ``None`` then there is no timeout.
+
+    Attributes
+    ------------
+    timeout: Optional[:class:`float`]
+        Timeout from last interaction with the UI before no longer accepting input.
+        If ``None`` then there is no timeout.
+    children: List[:class:`Item`]
+        The list of children attached to this view.
+    """
+
+    __discord_ui_view__: ClassVar[bool] = True
+    __view_children_items__: ClassVar[List[ItemCallbackType]] = []
+
+    def __init_subclass__(cls) -> None:
+        children: List[ItemCallbackType] = []
+        for base in reversed(cls.__mro__):
+            for member in base.__dict__.values():
+                if hasattr(member, '__discord_ui_model_type__'):
+                    children.append(member)
+
+        if len(children) > 25:
+            raise TypeError('View cannot have more than 25 children')
+
+        cls.__view_children_items__ = children
+
+    def __init__(self, *, timeout: Optional[float] = 180.0):
+        self.timeout = timeout
+        self.children: List[Item] = []
+        for func in self.__view_children_items__:
+            item: Item = func.__discord_ui_model_type__(**func.__discord_ui_model_kwargs__)
+            item.callback = partial(func, self, item)
+            item._view = self
+            setattr(self, func.__name__, item)
+            self.children.append(item)
+
+        self.__weights = _ViewWeights(self.children)
+        loop = asyncio.get_running_loop()
+        self.id: str = os.urandom(16).hex()
+        self.__cancel_callback: Optional[Callable[[View], None]] = None
+        self.__timeout_expiry: Optional[float] = None
+        self.__timeout_task: Optional[asyncio.Task[None]] = None
+        self.__stopped: asyncio.Future[bool] = loop.create_future()
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__} timeout={self.timeout} children={len(self.children)}>'
+
+    async def __timeout_task_impl(self) -> None:
+        while True:
+            # Guard just in case someone changes the value of the timeout at runtime
+            if self.timeout is None:
+                return
+
+            if self.__timeout_expiry is None:
+                return self._dispatch_timeout()
+
+            # Check if we've elapsed our currently set timeout
+            now = time.monotonic()
+            if now >= self.__timeout_expiry:
+                return self._dispatch_timeout()
+
+            # Wait N seconds to see if timeout data has been refreshed
+            await asyncio.sleep(self.__timeout_expiry - now)
+
+    def to_components(self) -> List[Dict[str, Any]]:
+        def key(item: Item) -> int:
+            return item._rendered_row or 0
+
+        children = sorted(self.children, key=key)
+        components: List[Dict[str, Any]] = []
+        for _, group in groupby(children, key=key):
+            children = [item.to_component_dict() for item in group]
+            if not children:
+                continue
+
+            components.append(
+                {
+                    'type': 1,
+                    'components': children,
+                }
+            )
+
+        return components
+
+    @classmethod
+    def from_message(cls, message: Message, /, *, timeout: Optional[float] = 180.0) -> View:
+        """Converts a message's components into a :class:`View`.
+
+        The :attr:`.Message.components` of a message are read-only
+        and separate types from those in the ``discord.ui`` namespace.
+        In order to modify and edit message components they must be
+        converted into a :class:`View` first.
+
+        Parameters
+        -----------
+        message: :class:`discord.Message`
+            The message with components to convert into a view.
+        timeout: Optional[:class:`float`]
+            The timeout of the converted view.
+
+        Returns
+        --------
+        :class:`View`
+            The converted view. This always returns a :class:`View` and not
+            one of its subclasses.
+        """
+        view = View(timeout=timeout)
+        for component in _walk_all_components(message.components):
+            view.add_item(_component_to_item(component))
+        return view
+
+    @property
+    def _expires_at(self) -> Optional[float]:
+        if self.timeout:
+            return time.monotonic() + self.timeout
+        return None
+
+    def add_item(self, item: Item) -> None:
+        """Adds an item to the view.
+
+        Parameters
+        -----------
+        item: :class:`Item`
+            The item to add to the view.
+
+        Raises
+        --------
+        TypeError
+            An :class:`Item` was not passed.
+        ValueError
+            Maximum number of children has been exceeded (25)
+            or the row the item is trying to be added to is full.
+        """
+
+        if len(self.children) > 25:
+            raise ValueError('maximum number of children exceeded')
+
+        if not isinstance(item, Item):
+            raise TypeError(f'expected Item not {item.__class__!r}')
+
+        self.__weights.add_item(item)
+
+        item._view = self
+        self.children.append(item)
+
+    def remove_item(self, item: Item) -> None:
+        """Removes an item from the view.
+
+        Parameters
+        -----------
+        item: :class:`Item`
+            The item to remove from the view.
+        """
+
+        try:
+            self.children.remove(item)
+        except ValueError:
+            pass
+        else:
+            self.__weights.remove_item(item)
+
+    def clear_items(self) -> None:
+        """Removes all items from the view."""
+        self.children.clear()
+        self.__weights.clear()
+
+    async def interaction_check(self, interaction: Interaction) -> bool:
+        """|coro|
+
+        A callback that is called when an interaction happens within the view
+        that checks whether the view should process item callbacks for the interaction.
+
+        This is useful to override if, for example, you want to ensure that the
+        interaction author is a given user.
+
+        The default implementation of this returns ``True``.
+
+        .. note::
+
+            If an exception occurs within the body then the check
+            is considered a failure and :meth:`on_error` is called.
+
+        Parameters
+        -----------
+        interaction: :class:`~discord.Interaction`
+            The interaction that occurred.
+
+        Returns
+        ---------
+        :class:`bool`
+            Whether the view children's callbacks should be called.
+        """
+        return True
+
+    async def on_timeout(self) -> None:
+        """|coro|
+
+        A callback that is called when a view's timeout elapses without being explicitly stopped.
+        """
+        pass
+
+    async def on_error(self, error: Exception, item: Item, interaction: Interaction) -> None:
+        """|coro|
+
+        A callback that is called when an item's callback or :meth:`interaction_check`
+        fails with an error.
+
+        The default implementation prints the traceback to stderr.
+
+        Parameters
+        -----------
+        error: :class:`Exception`
+            The exception that was raised.
+        item: :class:`Item`
+            The item that failed the dispatch.
+        interaction: :class:`~discord.Interaction`
+            The interaction that led to the failure.
+        """
+        print(f'Ignoring exception in view {self} for item {item}:', file=sys.stderr)
+        traceback.print_exception(error.__class__, error, error.__traceback__, file=sys.stderr)
+
+    async def _scheduled_task(self, item: Item, interaction: Interaction):
+        try:
+            if self.timeout:
+                self.__timeout_expiry = time.monotonic() + self.timeout
+
+            allow = await self.interaction_check(interaction)
+            if not allow:
+                return
+
+            await item.callback(interaction)
+            if not interaction.response._responded:
+                await interaction.response.defer()
+        except Exception as e:
+            return await self.on_error(e, item, interaction)
+
+    def _start_listening_from_store(self, store: ViewStore) -> None:
+        self.__cancel_callback = partial(store.remove_view)
+        if self.timeout:
+            loop = asyncio.get_running_loop()
+            if self.__timeout_task is not None:
+                self.__timeout_task.cancel()
+
+            self.__timeout_expiry = time.monotonic() + self.timeout
+            self.__timeout_task = loop.create_task(self.__timeout_task_impl())
+
+    def _dispatch_timeout(self):
+        if self.__stopped.done():
+            return
+
+        self.__stopped.set_result(True)
+        asyncio.create_task(self.on_timeout(), name=f'discord-ui-view-timeout-{self.id}')
+
+    def _dispatch_item(self, item: Item, interaction: Interaction):
+        if self.__stopped.done():
+            return
+
+        asyncio.create_task(self._scheduled_task(item, interaction), name=f'discord-ui-view-dispatch-{self.id}')
+
+    def refresh(self, components: List[Component]):
+        # This is pretty hacky at the moment
+        # fmt: off
+        old_state: Dict[Tuple[int, str], Item] = {
+            (item.type.value, item.custom_id): item  # type: ignore
+            for item in self.children
+            if item.is_dispatchable()
+        }
+        # fmt: on
+        children: List[Item] = []
+        for component in _walk_all_components(components):
+            try:
+                older = old_state[(component.type.value, component.custom_id)]  # type: ignore
+            except (KeyError, AttributeError):
+                children.append(_component_to_item(component))
+            else:
+                older.refresh_component(component)
+                children.append(older)
+
+        self.children = children
+
+    def stop(self) -> None:
+        """Stops listening to interaction events from this view.
+
+        This operation cannot be undone.
+        """
+        if not self.__stopped.done():
+            self.__stopped.set_result(False)
+
+        self.__timeout_expiry = None
+        if self.__timeout_task is not None:
+            self.__timeout_task.cancel()
+            self.__timeout_task = None
+
+        if self.__cancel_callback:
+            self.__cancel_callback(self)
+            self.__cancel_callback = None
+
+    def is_finished(self) -> bool:
+        """:class:`bool`: Whether the view has finished interacting."""
+        return self.__stopped.done()
+
+    def is_dispatching(self) -> bool:
+        """:class:`bool`: Whether the view has been added for dispatching purposes."""
+        return self.__cancel_callback is not None
+
+    def is_persistent(self) -> bool:
+        """:class:`bool`: Whether the view is set up as persistent.
+
+        A persistent view has all their components with a set ``custom_id`` and
+        a :attr:`timeout` set to ``None``.
+        """
+        return self.timeout is None and all(item.is_persistent() for item in self.children)
+
+    async def wait(self) -> bool:
+        """Waits until the view has finished interacting.
+
+        A view is considered finished when :meth:`stop` is called
+        or it times out.
+
+        Returns
+        --------
+        :class:`bool`
+            If ``True``, then the view timed out. If ``False`` then
+            the view finished normally.
+        """
+        return await self.__stopped
+
+
+class ViewStore:
+    def __init__(self, state: ConnectionState):
+        # (component_type, message_id, custom_id): (View, Item)
+        self._views: Dict[Tuple[int, Optional[int], str], Tuple[View, Item]] = {}
+        # message_id: View
+        self._synced_message_views: Dict[int, View] = {}
+        self._state: ConnectionState = state
+
+    @property
+    def persistent_views(self) -> Sequence[View]:
+        # fmt: off
+        views = {
+            view.id: view
+            for (_, (view, _)) in self._views.items()
+            if view.is_persistent()
+        }
+        # fmt: on
+        return list(views.values())
+
+    def __verify_integrity(self):
+        to_remove: List[Tuple[int, Optional[int], str]] = []
+        for (k, (view, _)) in self._views.items():
+            if view.is_finished():
+                to_remove.append(k)
+
+        for k in to_remove:
+            del self._views[k]
+
+    def add_view(self, view: View, message_id: Optional[int] = None):
+        self.__verify_integrity()
+
+        view._start_listening_from_store(self)
+        for item in view.children:
+            if item.is_dispatchable():
+                self._views[(item.type.value, message_id, item.custom_id)] = (view, item)  # type: ignore
+
+        if message_id is not None:
+            self._synced_message_views[message_id] = view
+
+    def remove_view(self, view: View):
+        for item in view.children:
+            if item.is_dispatchable():
+                self._views.pop((item.type.value, item.custom_id), None)  # type: ignore
+
+        for key, value in self._synced_message_views.items():
+            if value.id == view.id:
+                del self._synced_message_views[key]
+                break
+
+    def dispatch(self, component_type: int, custom_id: str, interaction: Interaction):
+        self.__verify_integrity()
+        message_id: Optional[int] = interaction.message and interaction.message.id
+        key = (component_type, message_id, custom_id)
+        # Fallback to None message_id searches in case a persistent view
+        # was added without an associated message_id
+        value = self._views.get(key) or self._views.get((component_type, None, custom_id))
+        if value is None:
+            return
+
+        view, item = value
+        item.refresh_state(interaction)
+        view._dispatch_item(item, interaction)
+
+    def is_message_tracked(self, message_id: int):
+        return message_id in self._synced_message_views
+
+    def remove_message_tracking(self, message_id: int) -> Optional[View]:
+        return self._synced_message_views.pop(message_id, None)
+
+    def update_from_message(self, message_id: int, components: List[ComponentPayload]):
+        # pre-req: is_message_tracked == true
+        view = self._synced_message_views[message_id]
+        view.refresh([_component_factory(d) for d in components])

discord/user.py

@@ -22,140 +22,205 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 """
 
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Type, TypeVar, TYPE_CHECKING
+
 import discord.abc
-from .flags import PublicUserFlags
-from .utils import snowflake_time, _bytes_to_base64_data
-from .enums import DefaultAvatar, try_enum
-from .colour import Colour
 from .asset import Asset
+from .colour import Colour
+from .enums import DefaultAvatar
+from .flags import PublicUserFlags
+from .utils import snowflake_time, _bytes_to_base64_data, MISSING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from .channel import DMChannel
+    from .guild import Guild
+    from .message import Message
+    from .state import ConnectionState
+    from .types.channel import DMChannel as DMChannelPayload
+    from .types.user import User as UserPayload
+
 
 __all__ = (
     'User',
     'ClientUser',
 )
 
-_BaseUser = discord.abc.User
+BU = TypeVar('BU', bound='BaseUser')
 
-class BaseUser(_BaseUser):
-    __slots__ = ('name', 'id', 'discriminator', 'avatar', 'bot', 'system', '_public_flags', '_state')
 
-    def __init__(self, *, state, data):
+class _UserTag:
+    __slots__ = ()
+    id: int
+
+
+class BaseUser(_UserTag):
+    __slots__ = (
+        'name',
+        'id',
+        'discriminator',
+        '_avatar',
+        '_banner',
+        '_accent_colour',
+        'bot',
+        'system',
+        '_public_flags',
+        '_state',
+    )
+
+    if TYPE_CHECKING:
+        name: str
+        id: int
+        discriminator: str
+        bot: bool
+        system: bool
+        _state: ConnectionState
+        _avatar: Optional[str]
+        _banner: Optional[str]
+        _accent_colour: Optional[str]
+        _public_flags: int
+
+    def __init__(self, *, state: ConnectionState, data: UserPayload) -> None:
         self._state = state
         self._update(data)
 
-    def __str__(self):
-        return '{0.name}#{0.discriminator}'.format(self)
+    def __repr__(self) -> str:
+        return (
+            f"<BaseUser id={self.id} name={self.name!r} discriminator={self.discriminator!r}"
+            f" bot={self.bot} system={self.system}>"
+        )
 
-    def __eq__(self, other):
-        return isinstance(other, _BaseUser) and other.id == self.id
+    def __str__(self) -> str:
+        return f'{self.name}#{self.discriminator}'
 
-    def __ne__(self, other):
+    def __int__(self) -> int:
+        return self.id
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, _UserTag) and other.id == self.id
+
+    def __ne__(self, other: Any) -> bool:
         return not self.__eq__(other)
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return self.id >> 22
 
-    def _update(self, data):
+    def _update(self, data: UserPayload) -> None:
         self.name = data['username']
         self.id = int(data['id'])
         self.discriminator = data['discriminator']
-        self.avatar = data['avatar']
+        self._avatar = data['avatar']
+        self._banner = data.get('banner', None)
+        self._accent_colour = data.get('accent_color', None)
         self._public_flags = data.get('public_flags', 0)
         self.bot = data.get('bot', False)
         self.system = data.get('system', False)
 
     @classmethod
-    def _copy(cls, user):
-        self = cls.__new__(cls) # bypass __init__
+    def _copy(cls: Type[BU], user: BU) -> BU:
+        self = cls.__new__(cls)  # bypass __init__
 
         self.name = user.name
         self.id = user.id
         self.discriminator = user.discriminator
-        self.avatar = user.avatar
+        self._avatar = user._avatar
+        self._banner = user._banner
+        self._accent_colour = user._accent_colour
         self.bot = user.bot
         self._state = user._state
         self._public_flags = user._public_flags
 
         return self
 
-    def _to_minimal_user_json(self):
+    def _to_minimal_user_json(self) -> Dict[str, Any]:
         return {
             'username': self.name,
             'id': self.id,
-            'avatar': self.avatar,
+            'avatar': self._avatar,
             'discriminator': self.discriminator,
             'bot': self.bot,
         }
 
     @property
-    def public_flags(self):
+    def public_flags(self) -> PublicUserFlags:
         """:class:`PublicUserFlags`: The publicly available flags the user has."""
         return PublicUserFlags._from_value(self._public_flags)
 
     @property
-    def avatar_url(self):
-        """:class:`Asset`: Returns an :class:`Asset` for the avatar the user has.
+    def avatar(self) -> Optional[Asset]:
+        """Optional[:class:`Asset`]: Returns an :class:`Asset` for the avatar the user has.
 
-        If the user does not have a traditional avatar, an asset for
-        the default avatar is returned instead.
-
-        This is equivalent to calling :meth:`avatar_url_as` with
-        the default parameters (i.e. webp/gif detection and a size of 1024).
+        If the user does not have a traditional avatar, ``None`` is returned.
+        If you want the avatar that a user has displayed, consider :attr:`display_avatar`.
         """
-        return self.avatar_url_as(format=None, size=1024)
+        if self._avatar is not None:
+            return Asset._from_avatar(self._state, self.id, self._avatar)
+        return None
 
-    def is_avatar_animated(self):
-        """:class:`bool`: Indicates if the user has an animated avatar."""
-        return bool(self.avatar and self.avatar.startswith('a_'))
+    @property
+    def default_avatar(self) -> Asset:
+        """:class:`Asset`: Returns the default avatar for a given user. This is calculated by the user's discriminator."""
+        return Asset._from_default_avatar(self._state, int(self.discriminator) % len(DefaultAvatar))
 
-    def avatar_url_as(self, *, format=None, static_format='webp', size=1024):
-        """Returns an :class:`Asset` for the avatar the user has.
+    @property
+    def display_avatar(self) -> Asset:
+        """:class:`Asset`: Returns the user's display avatar.
 
-        If the user does not have a traditional avatar, an asset for
-        the default avatar is returned instead.
+        For regular users this is just their default avatar or uploaded avatar.
 
-        The format must be one of 'webp', 'jpeg', 'jpg', 'png' or 'gif', and
-        'gif' is only valid for animated avatars. The size must be a power of 2
-        between 16 and 4096.
-
-        Parameters
-        -----------
-        format: Optional[:class:`str`]
-            The format to attempt to convert the avatar to.
-            If the format is ``None``, then it is automatically
-            detected into either 'gif' or static_format depending on the
-            avatar being animated or not.
-        static_format: Optional[:class:`str`]
-            Format to attempt to convert only non-animated avatars to.
-            Defaults to 'webp'
-        size: :class:`int`
-            The size of the image to display.
-
-        Raises
-        ------
-        InvalidArgument
-            Bad image format passed to ``format`` or ``static_format``, or
-            invalid ``size``.
-
-        Returns
-        --------
-        :class:`Asset`
-            The resulting CDN asset.
+        .. versionadded:: 2.0
         """
-        return Asset._from_avatar(self._state, self, format=format, static_format=static_format, size=size)
+        return self.avatar or self.default_avatar
 
     @property
-    def default_avatar(self):
-        """:class:`DefaultAvatar`: Returns the default avatar for a given user. This is calculated by the user's discriminator."""
-        return try_enum(DefaultAvatar, int(self.discriminator) % len(DefaultAvatar))
+    def banner(self) -> Optional[Asset]:
+        """Optional[:class:`Asset`]: Returns the user's banner asset, if available.
+
+        .. versionadded:: 2.0
+
+
+        .. note::
+            This information is only available via :meth:`Client.fetch_user`.
+        """
+        if self._banner is None:
+            return None
+        return Asset._from_user_banner(self._state, self.id, self._banner)
 
     @property
-    def default_avatar_url(self):
-        """:class:`Asset`: Returns a URL for a user's default avatar."""
-        return Asset(self._state, f'/embed/avatars/{self.default_avatar.value}.png')
+    def accent_colour(self) -> Optional[Colour]:
+        """Optional[:class:`Colour`]: Returns the user's accent colour, if applicable.
+
+        There is an alias for this named :attr:`accent_color`.
+
+        .. versionadded:: 2.0
+
+        .. note::
+
+            This information is only available via :meth:`Client.fetch_user`.
+        """
+        if self._accent_colour is None:
+            return None
+        return Colour(self._accent_colour)
 
     @property
-    def colour(self):
+    def accent_color(self) -> Optional[Colour]:
+        """Optional[:class:`Colour`]: Returns the user's accent color, if applicable.
+
+        There is an alias for this named :attr:`accent_colour`.
+
+        .. versionadded:: 2.0
+
+        .. note::
+
+            This information is only available via :meth:`Client.fetch_user`.
+        """
+        return self.accent_colour
+
+    @property
+    def colour(self) -> Colour:
         """:class:`Colour`: A property that returns a colour denoting the rendered colour
         for the user. This always returns :meth:`Colour.default`.
 
@@ -164,7 +229,7 @@ class BaseUser(_BaseUser):
         return Colour.default()
 
     @property
-    def color(self):
+    def color(self) -> Colour:
         """:class:`Colour`: A property that returns a color denoting the rendered color
         for the user. This always returns :meth:`Colour.default`.
 
@@ -173,28 +238,12 @@ class BaseUser(_BaseUser):
         return self.colour
 
     @property
-    def mention(self):
+    def mention(self) -> str:
         """:class:`str`: Returns a string that allows you to mention the given user."""
         return f'<@{self.id}>'
 
-    def permissions_in(self, channel):
-        """An alias for :meth:`abc.GuildChannel.permissions_for`.
-
-        Basically equivalent to:
-
-        .. code-block:: python3
-
-            channel.permissions_for(self)
-
-        Parameters
-        -----------
-        channel: :class:`abc.GuildChannel`
-            The channel to check your permissions for.
-        """
-        return channel.permissions_for(self)
-
     @property
-    def created_at(self):
+    def created_at(self) -> datetime:
         """:class:`datetime.datetime`: Returns the user's creation time in UTC.
 
         This is when the user's Discord account was created.
@@ -202,7 +251,7 @@ class BaseUser(_BaseUser):
         return snowflake_time(self.id)
 
     @property
-    def display_name(self):
+    def display_name(self) -> str:
         """:class:`str`: Returns the user's display name.
 
         For regular users this is just their username, but
@@ -211,7 +260,7 @@ class BaseUser(_BaseUser):
         """
         return self.name
 
-    def mentioned_in(self, message):
+    def mentioned_in(self, message: Message) -> bool:
         """Checks if the user is mentioned in the specified message.
 
         Parameters
@@ -230,6 +279,7 @@ class BaseUser(_BaseUser):
 
         return any(user.id == self.id for user in message.mentions)
 
+
 class ClientUser(BaseUser):
     """Represents your Discord user.
 
@@ -259,8 +309,6 @@ class ClientUser(BaseUser):
         The user's unique ID.
     discriminator: :class:`str`
         The user's discriminator. This is given when the username has conflicts.
-    avatar: Optional[:class:`str`]
-        The avatar hash the user has. Could be ``None``.
     bot: :class:`bool`
         Specifies if the user is a bot account.
     system: :class:`bool`
@@ -269,23 +317,31 @@ class ClientUser(BaseUser):
         .. versionadded:: 1.3
 
     verified: :class:`bool`
-        Specifies if the user is a verified account.
+        Specifies if the user's email is verified.
     locale: Optional[:class:`str`]
         The IETF language tag used to identify the language the user is using.
     mfa_enabled: :class:`bool`
         Specifies if the user has MFA turned on and working.
     """
-    __slots__ = BaseUser.__slots__ + \
-                ('locale', '_flags', 'verified', 'mfa_enabled', '__weakref__')
 
-    def __init__(self, *, state, data):
+    __slots__ = ('locale', '_flags', 'verified', 'mfa_enabled', '__weakref__')
+
+    if TYPE_CHECKING:
+        verified: bool
+        locale: Optional[str]
+        mfa_enabled: bool
+        _flags: int
+
+    def __init__(self, *, state: ConnectionState, data: UserPayload) -> None:
         super().__init__(state=state, data=data)
 
-    def __repr__(self):
-        return '<ClientUser id={0.id} name={0.name!r} discriminator={0.discriminator!r}' \
-               ' bot={0.bot} verified={0.verified} mfa_enabled={0.mfa_enabled}>'.format(self)
+    def __repr__(self) -> str:
+        return (
+            f'<ClientUser id={self.id} name={self.name!r} discriminator={self.discriminator!r}'
+            f' bot={self.bot} verified={self.verified} mfa_enabled={self.mfa_enabled}>'
+        )
 
-    def _update(self, data):
+    def _update(self, data: UserPayload) -> None:
         super()._update(data)
         # There's actually an Optional[str] phone field as well but I won't use it
         self.verified = data.get('verified', False)
@@ -293,8 +349,7 @@ class ClientUser(BaseUser):
         self._flags = data.get('flags', 0)
         self.mfa_enabled = data.get('mfa_enabled', False)
 
-
-    async def edit(self, *, username=None, avatar=None):
+    async def edit(self, *, username: str = MISSING, avatar: bytes = MISSING) -> ClientUser:
         """|coro|
 
         Edits the current profile of the client.
@@ -308,6 +363,9 @@ class ClientUser(BaseUser):
 
             The only image formats supported for uploading is JPEG and PNG.
 
+        .. versionchanged:: 2.0
+            The edit is no longer in-place, instead the newly edited client user is returned.
+
         Parameters
         -----------
         username: :class:`str`
@@ -322,13 +380,22 @@ class ClientUser(BaseUser):
             Editing your profile failed.
         InvalidArgument
             Wrong image format passed for ``avatar``.
+
+        Returns
+        ---------
+        :class:`ClientUser`
+            The newly edited client user.
         """
+        payload: Dict[str, Any] = {}
+        if username is not MISSING:
+            payload['username'] = username
 
-        if avatar is not None:
-            avatar = _bytes_to_base64_data(avatar)
+        if avatar is not MISSING:
+            payload['avatar'] = _bytes_to_base64_data(avatar)
+
+        data: UserPayload = await self._state.http.edit_profile(payload)
+        return ClientUser(state=self._state, data=data)
 
-        data = await self._state.http.edit_profile(username=username, avatar=avatar)
-        self._update(data)
 
 class User(BaseUser, discord.abc.Messageable):
     """Represents a Discord user.
@@ -351,6 +418,10 @@ class User(BaseUser, discord.abc.Messageable):
 
             Returns the user's name with discriminator.
 
+        .. describe:: int(x)
+
+            Returns the user's ID.
+
     Attributes
     -----------
     name: :class:`str`
@@ -359,25 +430,40 @@ class User(BaseUser, discord.abc.Messageable):
         The user's unique ID.
     discriminator: :class:`str`
         The user's discriminator. This is given when the username has conflicts.
-    avatar: Optional[:class:`str`]
-        The avatar hash the user has. Could be None.
     bot: :class:`bool`
         Specifies if the user is a bot account.
     system: :class:`bool`
         Specifies if the user is a system user (i.e. represents Discord officially).
     """
 
-    __slots__ = BaseUser.__slots__ + ('__weakref__',)
+    __slots__ = ('_stored',)
 
-    def __repr__(self):
-        return '<User id={0.id} name={0.name!r} discriminator={0.discriminator!r} bot={0.bot}>'.format(self)
+    def __init__(self, *, state: ConnectionState, data: UserPayload) -> None:
+        super().__init__(state=state, data=data)
+        self._stored: bool = False
 
-    async def _get_channel(self):
+    def __repr__(self) -> str:
+        return f'<User id={self.id} name={self.name!r} discriminator={self.discriminator!r} bot={self.bot}>'
+
+    def __del__(self) -> None:
+        try:
+            if self._stored:
+                self._state.deref_user(self.id)
+        except Exception:
+            pass
+
+    @classmethod
+    def _copy(cls, user: User):
+        self = super()._copy(user)
+        self._stored = False
+        return self
+
+    async def _get_channel(self) -> DMChannel:
         ch = await self.create_dm()
         return ch
 
     @property
-    def dm_channel(self):
+    def dm_channel(self) -> Optional[DMChannel]:
         """Optional[:class:`DMChannel`]: Returns the channel associated with this user if it exists.
 
         If this returns ``None``, you can create a DM channel by calling the
@@ -386,7 +472,7 @@ class User(BaseUser, discord.abc.Messageable):
         return self._state._get_private_channel_by_user(self.id)
 
     @property
-    def mutual_guilds(self):
+    def mutual_guilds(self) -> List[Guild]:
         """List[:class:`Guild`]: The guilds that the user shares with the client.
 
         .. note::
@@ -397,7 +483,7 @@ class User(BaseUser, discord.abc.Messageable):
         """
         return [guild for guild in self._state._guilds.values() if guild.get_member(self.id)]
 
-    async def create_dm(self):
+    async def create_dm(self) -> DMChannel:
         """|coro|
 
         Creates a :class:`DMChannel` with this user.
@@ -415,5 +501,5 @@ class User(BaseUser, discord.abc.Messageable):
             return found
 
         state = self._state
-        data = await state.http.start_private_message(self.id)
+        data: DMChannelPayload = await state.http.start_private_message(self.id)
         return state.add_dm_channel(data)

discord/utils.py

@@ -21,11 +21,33 @@ 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 array
 import asyncio
 import collections.abc
-from typing import Optional, overload
+from typing import (
+    Any,
+    AsyncIterator,
+    Callable,
+    Dict,
+    ForwardRef,
+    Generic,
+    Iterable,
+    Iterator,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Protocol,
+    Sequence,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    overload,
+    TYPE_CHECKING,
+)
 import unicodedata
 from base64 import b64encode
 from bisect import bisect_left
@@ -35,12 +57,22 @@ from inspect import isawaitable as _isawaitable, signature as _signature
 from operator import attrgetter
 import json
 import re
+import sys
+import types
 import warnings
 
 from .errors import InvalidArgument
 
+try:
+    import orjson
+except ModuleNotFoundError:
+    HAS_ORJSON = False
+else:
+    HAS_ORJSON = True
+
+
 __all__ = (
-    'oauth_uri',
+    'oauth_url',
     'snowflake_time',
     'time_snowflake',
     'find',
@@ -50,10 +82,28 @@ __all__ = (
     'remove_markdown',
     'escape_markdown',
     'escape_mentions',
+    'as_chunks',
+    'format_dt',
 )
+
 DISCORD_EPOCH = 1420070400000
 
-class cached_property:
+
+class _MissingSentinel:
+    def __eq__(self, other):
+        return False
+
+    def __bool__(self):
+        return False
+
+    def __repr__(self):
+        return '...'
+
+
+MISSING: Any = _MissingSentinel()
+
+
+class _cached_property:
     def __init__(self, function):
         self.function = function
         self.__doc__ = getattr(function, '__doc__')
@@ -67,13 +117,47 @@ class cached_property:
 
         return value
 
-class CachedSlotProperty:
-    def __init__(self, name, function):
+
+if TYPE_CHECKING:
+    from functools import cached_property as cached_property
+
+    from typing_extensions import ParamSpec
+
+    from .permissions import Permissions
+    from .abc import Snowflake
+    from .invite import Invite
+    from .template import Template
+
+    class _RequestLike(Protocol):
+        headers: Mapping[str, Any]
+
+
+    P = ParamSpec('P')
+
+else:
+    cached_property = _cached_property
+
+
+T = TypeVar('T')
+T_co = TypeVar('T_co', covariant=True)
+_Iter = Union[Iterator[T], AsyncIterator[T]]
+
+
+class CachedSlotProperty(Generic[T, T_co]):
+    def __init__(self, name: str, function: Callable[[T], T_co]) -> None:
         self.name = name
         self.function = function
         self.__doc__ = getattr(function, '__doc__')
 
-    def __get__(self, instance, owner):
+    @overload
+    def __get__(self, instance: None, owner: Type[T]) -> CachedSlotProperty[T, T_co]:
+        ...
+
+    @overload
+    def __get__(self, instance: T, owner: Type[T]) -> T_co:
+        ...
+
+    def __get__(self, instance: Optional[T], owner: Type[T]) -> Any:
         if instance is None:
             return self
 
@@ -84,85 +168,122 @@ class CachedSlotProperty:
             setattr(instance, self.name, value)
             return value
 
-def cached_slot_property(name):
-    def decorator(func):
+
+class classproperty(Generic[T_co]):
+    def __init__(self, fget: Callable[[Any], T_co]) -> None:
+        self.fget = fget
+
+    def __get__(self, instance: Optional[Any], owner: Type[Any]) -> T_co:
+        return self.fget(owner)
+
+    def __set__(self, instance, value) -> None:
+        raise AttributeError('cannot set attribute')
+
+
+def cached_slot_property(name: str) -> Callable[[Callable[[T], T_co]], CachedSlotProperty[T, T_co]]:
+    def decorator(func: Callable[[T], T_co]) -> CachedSlotProperty[T, T_co]:
         return CachedSlotProperty(name, func)
+
     return decorator
 
-class SequenceProxy(collections.abc.Sequence):
+
+class SequenceProxy(Generic[T_co], collections.abc.Sequence):
     """Read-only proxy of a Sequence."""
-    def __init__(self, proxied):
+
+    def __init__(self, proxied: Sequence[T_co]):
         self.__proxied = proxied
 
-    def __getitem__(self, idx):
+    def __getitem__(self, idx: int) -> T_co:
         return self.__proxied[idx]
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.__proxied)
 
-    def __contains__(self, item):
+    def __contains__(self, item: Any) -> bool:
         return item in self.__proxied
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[T_co]:
         return iter(self.__proxied)
 
-    def __reversed__(self):
+    def __reversed__(self) -> Iterator[T_co]:
         return reversed(self.__proxied)
 
-    def index(self, value, *args, **kwargs):
+    def index(self, value: Any, *args, **kwargs) -> int:
         return self.__proxied.index(value, *args, **kwargs)
 
-    def count(self, value):
+    def count(self, value: Any) -> int:
         return self.__proxied.count(value)
 
+
 @overload
 def parse_time(timestamp: None) -> None:
     ...
 
+
 @overload
 def parse_time(timestamp: str) -> datetime.datetime:
     ...
 
+
+@overload
+def parse_time(timestamp: Optional[str]) -> Optional[datetime.datetime]:
+    ...
+
+
 def parse_time(timestamp: Optional[str]) -> Optional[datetime.datetime]:
     if timestamp:
         return datetime.datetime.fromisoformat(timestamp)
     return None
 
-def copy_doc(original):
-    def decorator(overriden):
+
+def copy_doc(original: Callable) -> Callable[[T], T]:
+    def decorator(overriden: T) -> T:
         overriden.__doc__ = original.__doc__
-        overriden.__signature__ = _signature(original)
+        overriden.__signature__ = _signature(original)  # type: ignore
         return overriden
+
     return decorator
 
-def deprecated(instead=None):
-    def actual_decorator(func):
+
+def deprecated(instead: Optional[str] = None) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    def actual_decorator(func: Callable[P, T]) -> Callable[P, T]:
         @functools.wraps(func)
-        def decorated(*args, **kwargs):
-            warnings.simplefilter('always', DeprecationWarning) # turn off filter
+        def decorated(*args: P.args, **kwargs: P.kwargs) -> T:
+            warnings.simplefilter('always', DeprecationWarning)  # turn off filter
             if instead:
                 fmt = "{0.__name__} is deprecated, use {1} instead."
             else:
                 fmt = '{0.__name__} is deprecated.'
 
             warnings.warn(fmt.format(func, instead), stacklevel=3, category=DeprecationWarning)
-            warnings.simplefilter('default', DeprecationWarning) # reset filter
+            warnings.simplefilter('default', DeprecationWarning)  # reset filter
             return func(*args, **kwargs)
+
         return decorated
+
     return actual_decorator
 
-def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None, scopes=None):
+
+def oauth_url(
+    client_id: Union[int, str],
+    *,
+    permissions: Permissions = MISSING,
+    guild: Snowflake = MISSING,
+    redirect_uri: str = MISSING,
+    scopes: Iterable[str] = MISSING,
+    disable_guild_select: bool = False,
+) -> str:
     """A helper function that returns the OAuth2 URL for inviting the bot
     into guilds.
 
     Parameters
     -----------
-    client_id: :class:`str`
+    client_id: Union[:class:`int`, :class:`str`]
         The client ID for your bot.
     permissions: :class:`~discord.Permissions`
         The permissions you're requesting. If not given then you won't be requesting any
         permissions.
-    guild: :class:`~discord.Guild`
+    guild: :class:`~discord.abc.Snowflake`
         The guild to pre-select in the authorization screen, if available.
     redirect_uri: :class:`str`
         An optional valid redirect URI.
@@ -170,6 +291,10 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None, scopes
         An optional valid list of scopes. Defaults to ``('bot',)``.
 
         .. versionadded:: 1.7
+    disable_guild_select: :class:`bool`
+        Whether to disallow the user from changing the guild dropdown.
+
+        .. versionadded:: 2.0
 
     Returns
     --------
@@ -177,14 +302,17 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None, scopes
         The OAuth2 URL for inviting the bot into guilds.
     """
     url = f'https://discord.com/oauth2/authorize?client_id={client_id}'
-    url = url + '&scope=' + '+'.join(scopes or ('bot',))
-    if permissions is not None:
-        url = url + '&permissions=' + str(permissions.value)
-    if guild is not None:
-        url = url + "&guild_id=" + str(guild.id)
-    if redirect_uri is not None:
+    url += '&scope=' + '+'.join(scopes or ('bot',))
+    if permissions is not MISSING:
+        url += f'&permissions={permissions.value}'
+    if guild is not MISSING:
+        url += f'&guild_id={guild.id}'
+    if redirect_uri is not MISSING:
         from urllib.parse import urlencode
-        url = url + "&response_type=code&" + urlencode({'redirect_uri': redirect_uri})
+
+        url += '&response_type=code&' + urlencode({'redirect_uri': redirect_uri})
+    if disable_guild_select:
+        url += '&disable_guild_select=true'
     return url
 
 
@@ -201,7 +329,8 @@ def snowflake_time(id: int) -> datetime.datetime:
         An aware datetime in UTC representing the creation time of the snowflake.
     """
     timestamp = ((id >> 22) + DISCORD_EPOCH) / 1000
-    return datetime.datetime.utcfromtimestamp(timestamp).replace(tzinfo=datetime.timezone.utc)
+    return datetime.datetime.fromtimestamp(timestamp, tz=datetime.timezone.utc)
+
 
 def time_snowflake(dt: datetime.datetime, high: bool = False) -> int:
     """Returns a numeric snowflake pretending to be created at the given date.
@@ -226,9 +355,10 @@ def time_snowflake(dt: datetime.datetime, high: bool = False) -> int:
         The snowflake representing the time given.
     """
     discord_millis = int(dt.timestamp() * 1000 - DISCORD_EPOCH)
-    return (discord_millis << 22) + (2**22-1 if high else 0)
+    return (discord_millis << 22) + (2 ** 22 - 1 if high else 0)
 
-def find(predicate, seq):
+
+def find(predicate: Callable[[T], Any], seq: Iterable[T]) -> Optional[T]:
     """A helper to return the first element found in the sequence
     that meets the predicate. For example: ::
 
@@ -244,7 +374,7 @@ def find(predicate, seq):
     -----------
     predicate
         A function that returns a boolean-like result.
-    seq: iterable
+    seq: :class:`collections.abc.Iterable`
         The iterable to search through.
     """
 
@@ -253,7 +383,8 @@ def find(predicate, seq):
             return element
     return None
 
-def get(iterable, **attrs):
+
+def get(iterable: Iterable[T], **attrs: Any) -> Optional[T]:
     r"""A helper that returns the first element in the iterable that meets
     all the traits passed in ``attrs``. This is an alternative for
     :func:`~discord.utils.find`.
@@ -310,22 +441,19 @@ def get(iterable, **attrs):
                 return elem
         return None
 
-    converted = [
-        (attrget(attr.replace('__', '.')), value)
-        for attr, value in attrs.items()
-    ]
+    converted = [(attrget(attr.replace('__', '.')), value) for attr, value in attrs.items()]
 
     for elem in iterable:
         if _all(pred(elem) == value for pred, value in converted):
             return elem
     return None
 
-def _unique(iterable):
-    seen = set()
-    adder = seen.add
-    return [x for x in iterable if not (x in seen or adder(x))]
 
-def _get_as_snowflake(data, key):
+def _unique(iterable: Iterable[T]) -> List[T]:
+    return [x for x in dict.fromkeys(iterable)]
+
+
+def _get_as_snowflake(data: Any, key: str) -> Optional[int]:
     try:
         value = data[key]
     except KeyError:
@@ -333,7 +461,8 @@ def _get_as_snowflake(data, key):
     else:
         return value and int(value)
 
-def _get_mime_type_for_image(data):
+
+def _get_mime_type_for_image(data: bytes):
     if data.startswith(b'\x89\x50\x4E\x47\x0D\x0A\x1A\x0A'):
         return 'image/png'
     elif data[0:3] == b'\xff\xd8\xff' or data[6:10] in (b'JFIF', b'Exif'):
@@ -345,17 +474,31 @@ def _get_mime_type_for_image(data):
     else:
         raise InvalidArgument('Unsupported image type given')
 
-def _bytes_to_base64_data(data):
+
+def _bytes_to_base64_data(data: bytes) -> str:
     fmt = 'data:{mime};base64,{data}'
     mime = _get_mime_type_for_image(data)
     b64 = b64encode(data).decode('ascii')
     return fmt.format(mime=mime, data=b64)
 
-def to_json(obj):
-    return json.dumps(obj, separators=(',', ':'), ensure_ascii=True)
 
-def _parse_ratelimit_header(request, *, use_clock=False):
-    reset_after = request.headers.get('X-Ratelimit-Reset-After')
+if HAS_ORJSON:
+
+    def _to_json(obj: Any) -> str:  # type: ignore
+        return orjson.dumps(obj).decode('utf-8')
+
+    _from_json = orjson.loads  # type: ignore
+
+else:
+
+    def _to_json(obj: Any) -> str:
+        return json.dumps(obj, separators=(',', ':'), ensure_ascii=True)
+
+    _from_json = json.loads
+
+
+def _parse_ratelimit_header(request: Any, *, use_clock: bool = False) -> float:
+    reset_after: Optional[str] = request.headers.get('X-Ratelimit-Reset-After')
     if use_clock or not reset_after:
         utc = datetime.timezone.utc
         now = datetime.datetime.now(utc)
@@ -364,6 +507,7 @@ def _parse_ratelimit_header(request, *, use_clock=False):
     else:
         return float(reset_after)
 
+
 async def maybe_coroutine(f, *args, **kwargs):
     value = f(*args, **kwargs)
     if _isawaitable(value):
@@ -371,6 +515,7 @@ async def maybe_coroutine(f, *args, **kwargs):
     else:
         return value
 
+
 async def async_all(gen, *, check=_isawaitable):
     for elem in gen:
         if check(elem):
@@ -379,10 +524,9 @@ async def async_all(gen, *, check=_isawaitable):
             return False
     return True
 
+
 async def sane_wait_for(futures, *, timeout):
-    ensured = [
-        asyncio.ensure_future(fut) for fut in futures
-    ]
+    ensured = [asyncio.ensure_future(fut) for fut in futures]
     done, pending = await asyncio.wait(ensured, timeout=timeout, return_when=asyncio.ALL_COMPLETED)
 
     if len(pending) != 0:
@@ -390,7 +534,23 @@ async def sane_wait_for(futures, *, timeout):
 
     return done
 
-async def sleep_until(when, result=None):
+
+def get_slots(cls: Type[Any]) -> Iterator[str]:
+    for mro in reversed(cls.__mro__):
+        try:
+            yield from mro.__slots__
+        except AttributeError:
+            continue
+
+
+def compute_timedelta(dt: datetime.datetime):
+    if dt.tzinfo is None:
+        dt = dt.astimezone()
+    now = datetime.datetime.now(datetime.timezone.utc)
+    return max((dt - now).total_seconds(), 0)
+
+
+async def sleep_until(when: datetime.datetime, result: Optional[T] = None) -> Optional[T]:
     """|coro|
 
     Sleep until a specified time.
@@ -407,16 +567,14 @@ async def sleep_until(when, result=None):
     result: Any
         If provided is returned to the caller when the coroutine completes.
     """
-    if when.tzinfo is None:
-        when = when.astimezone()
-    now = datetime.datetime.now(datetime.timezone.utc)
-    delta = (when - now).total_seconds()
-    return await asyncio.sleep(max(delta, 0), result)
+    delta = compute_timedelta(when)
+    return await asyncio.sleep(delta, result)
+
 
 def utcnow() -> datetime.datetime:
     """A helper function to return an aware UTC datetime representing the current time.
 
-    This should be preferred to :func:`datetime.datetime.utcnow` since it is an aware
+    This should be preferred to :meth:`datetime.datetime.utcnow` since it is an aware
     datetime, compared to the naive datetime in the standard library.
 
     .. versionadded:: 2.0
@@ -428,9 +586,11 @@ def utcnow() -> datetime.datetime:
     """
     return datetime.datetime.now(datetime.timezone.utc)
 
-def valid_icon_size(size):
+
+def valid_icon_size(size: int) -> bool:
     """Icons must be power of 2 within [16, 4096]."""
-    return not size & (size - 1) and size in range(16, 4097)
+    return not size & (size - 1) and 4096 >= size >= 16
+
 
 class SnowflakeList(array.array):
     """Internal data storage class to efficiently store a list of snowflakes.
@@ -446,24 +606,31 @@ class SnowflakeList(array.array):
 
     __slots__ = ()
 
-    def __new__(cls, data, *, is_sorted=False):
-        return array.array.__new__(cls, 'Q', data if is_sorted else sorted(data))
+    if TYPE_CHECKING:
 
-    def add(self, element):
+        def __init__(self, data: Iterable[int], *, is_sorted: bool = False):
+            ...
+
+    def __new__(cls, data: Iterable[int], *, is_sorted: bool = False):
+        return array.array.__new__(cls, 'Q', data if is_sorted else sorted(data))  # type: ignore
+
+    def add(self, element: int) -> None:
         i = bisect_left(self, element)
         self.insert(i, element)
 
-    def get(self, element):
+    def get(self, element: int) -> Optional[int]:
         i = bisect_left(self, element)
         return self[i] if i != len(self) and self[i] == element else None
 
-    def has(self, element):
+    def has(self, element: int) -> bool:
         i = bisect_left(self, element)
         return i != len(self) and self[i] == element
 
+
 _IS_ASCII = re.compile(r'^[\x00-\x7f]+$')
 
-def _string_width(string, *, _IS_ASCII=_IS_ASCII):
+
+def _string_width(string: str, *, _IS_ASCII=_IS_ASCII) -> int:
     """Returns string's width."""
     match = _IS_ASCII.match(string)
     if match:
@@ -473,7 +640,8 @@ def _string_width(string, *, _IS_ASCII=_IS_ASCII):
     func = unicodedata.east_asian_width
     return sum(2 if func(char) in UNICODE_WIDE_CHAR_TYPE else 1 for char in string)
 
-def resolve_invite(invite):
+
+def resolve_invite(invite: Union[Invite, str]) -> str:
     """
     Resolves an invite from a :class:`~discord.Invite`, URL or code.
 
@@ -488,6 +656,7 @@ def resolve_invite(invite):
         The invite code.
     """
     from .invite import Invite  # circular import
+
     if isinstance(invite, Invite):
         return invite.code
     else:
@@ -497,7 +666,8 @@ def resolve_invite(invite):
             return m.group(1)
     return invite
 
-def resolve_template(code):
+
+def resolve_template(code: Union[Template, str]) -> str:
     """
     Resolves a template code from a :class:`~discord.Template`, URL or code.
 
@@ -513,7 +683,8 @@ def resolve_template(code):
     :class:`str`
         The template code.
     """
-    from .template import Template # circular import
+    from .template import Template  # circular import
+
     if isinstance(code, Template):
         return code.code
     else:
@@ -523,8 +694,8 @@ def resolve_template(code):
             return m.group(1)
     return code
 
-_MARKDOWN_ESCAPE_SUBREGEX = '|'.join(r'\{0}(?=([\s\S]*((?<!\{0})\{0})))'.format(c)
-                                     for c in ('*', '`', '_', '~', '|'))
+
+_MARKDOWN_ESCAPE_SUBREGEX = '|'.join(r'\{0}(?=([\s\S]*((?<!\{0})\{0})))'.format(c) for c in ('*', '`', '_', '~', '|'))
 
 _MARKDOWN_ESCAPE_COMMON = r'^>(?:>>)?\s|\[.+\]\(.+\)'
 
@@ -534,7 +705,8 @@ _URL_REGEX = r'(?P<url><[^: >]+:\/[^ >]+>|(?:https?|steam):\/\/[^\s<]+[^<.,:;\"\
 
 _MARKDOWN_STOCK_REGEX = fr'(?P<markdown>[_\\~|\*`]|{_MARKDOWN_ESCAPE_COMMON})'
 
-def remove_markdown(text, *, ignore_links=True):
+
+def remove_markdown(text: str, *, ignore_links: bool = True) -> str:
     """A helper function that removes markdown characters.
 
     .. versionadded:: 1.7
@@ -567,7 +739,8 @@ def remove_markdown(text, *, ignore_links=True):
         regex = f'(?:{_URL_REGEX}|{regex})'
     return re.sub(regex, replacement, text, 0, re.MULTILINE)
 
-def escape_markdown(text, *, as_needed=False, ignore_links=True):
+
+def escape_markdown(text: str, *, as_needed: bool = False, ignore_links: bool = True) -> str:
     r"""A helper function that escapes Discord's markdown.
 
     Parameters
@@ -593,6 +766,7 @@ def escape_markdown(text, *, as_needed=False, ignore_links=True):
     """
 
     if not as_needed:
+
         def replacement(match):
             groupdict = match.groupdict()
             is_url = groupdict.get('url')
@@ -608,7 +782,8 @@ def escape_markdown(text, *, as_needed=False, ignore_links=True):
         text = re.sub(r'\\', r'\\\\', text)
         return _MARKDOWN_ESCAPE_REGEX.sub(r'\\\1', text)
 
-def escape_mentions(text):
+
+def escape_mentions(text: str) -> str:
     """A helper function that escapes everyone, here, role, and user mentions.
 
     .. note::
@@ -632,3 +807,213 @@ def escape_mentions(text):
         The text with the mentions removed.
     """
     return re.sub(r'@(everyone|here|[!&]?[0-9]{17,20})', '@\u200b\\1', text)
+
+
+def _chunk(iterator: Iterator[T], max_size: int) -> Iterator[List[T]]:
+    ret = []
+    n = 0
+    for item in iterator:
+        ret.append(item)
+        n += 1
+        if n == max_size:
+            yield ret
+            ret = []
+            n = 0
+    if ret:
+        yield ret
+
+
+async def _achunk(iterator: AsyncIterator[T], max_size: int) -> AsyncIterator[List[T]]:
+    ret = []
+    n = 0
+    async for item in iterator:
+        ret.append(item)
+        n += 1
+        if n == max_size:
+            yield ret
+            ret = []
+            n = 0
+    if ret:
+        yield ret
+
+
+@overload
+def as_chunks(iterator: Iterator[T], max_size: int) -> Iterator[List[T]]:
+    ...
+
+
+@overload
+def as_chunks(iterator: AsyncIterator[T], max_size: int) -> AsyncIterator[List[T]]:
+    ...
+
+
+def as_chunks(iterator: _Iter[T], max_size: int) -> _Iter[List[T]]:
+    """A helper function that collects an iterator into chunks of a given size.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    ----------
+    iterator: Union[:class:`collections.abc.Iterator`, :class:`collections.abc.AsyncIterator`]
+        The iterator to chunk, can be sync or async.
+    max_size: :class:`int`
+        The maximum chunk size.
+
+
+    .. warning::
+
+        The last chunk collected may not be as large as ``max_size``.
+
+    Returns
+    --------
+    Union[:class:`Iterator`, :class:`AsyncIterator`]
+        A new iterator which yields chunks of a given size.
+    """
+    if max_size <= 0:
+        raise ValueError('Chunk sizes must be greater than 0.')
+
+    if isinstance(iterator, AsyncIterator):
+        return _achunk(iterator, max_size)
+    return _chunk(iterator, max_size)
+
+
+PY_310 = sys.version_info >= (3, 10)
+
+
+def flatten_literal_params(parameters: Iterable[Any]) -> Tuple[Any, ...]:
+    params = []
+    literal_cls = type(Literal[0])
+    for p in parameters:
+        if isinstance(p, literal_cls):
+            params.extend(p.__args__)
+        else:
+            params.append(p)
+    return tuple(params)
+
+
+def normalise_optional_params(parameters: Iterable[Any]) -> Tuple[Any, ...]:
+    none_cls = type(None)
+    return tuple(p for p in parameters if p is not none_cls) + (none_cls,)
+
+
+def evaluate_annotation(
+    tp: Any,
+    globals: Dict[str, Any],
+    locals: Dict[str, Any],
+    cache: Dict[str, Any],
+    *,
+    implicit_str: bool = True,
+):
+    if isinstance(tp, ForwardRef):
+        tp = tp.__forward_arg__
+        # ForwardRefs always evaluate their internals
+        implicit_str = True
+
+    if implicit_str and isinstance(tp, str):
+        if tp in cache:
+            return cache[tp]
+        evaluated = eval(tp, globals, locals)
+        cache[tp] = evaluated
+        return evaluate_annotation(evaluated, globals, locals, cache)
+
+    if hasattr(tp, '__args__'):
+        implicit_str = True
+        is_literal = False
+        args = tp.__args__
+        if not hasattr(tp, '__origin__'):
+            if PY_310 and tp.__class__ is types.UnionType:  # type: ignore
+                converted = Union[args]  # type: ignore
+                return evaluate_annotation(converted, globals, locals, cache)
+
+            return tp
+        if tp.__origin__ is Union:
+            try:
+                if args.index(type(None)) != len(args) - 1:
+                    args = normalise_optional_params(tp.__args__)
+            except ValueError:
+                pass
+        if tp.__origin__ is Literal:
+            if not PY_310:
+                args = flatten_literal_params(tp.__args__)
+            implicit_str = False
+            is_literal = True
+
+        evaluated_args = tuple(evaluate_annotation(arg, globals, locals, cache, implicit_str=implicit_str) for arg in args)
+
+        if is_literal and not all(isinstance(x, (str, int, bool, type(None))) for x in evaluated_args):
+            raise TypeError('Literal arguments must be of type str, int, bool, or NoneType.')
+
+        if evaluated_args == args:
+            return tp
+
+        try:
+            return tp.copy_with(evaluated_args)
+        except AttributeError:
+            return tp.__origin__[evaluated_args]
+
+    return tp
+
+
+def resolve_annotation(
+    annotation: Any,
+    globalns: Dict[str, Any],
+    localns: Optional[Dict[str, Any]],
+    cache: Optional[Dict[str, Any]],
+) -> Any:
+    if annotation is None:
+        return type(None)
+    if isinstance(annotation, str):
+        annotation = ForwardRef(annotation)
+
+    locals = globalns if localns is None else localns
+    if cache is None:
+        cache = {}
+    return evaluate_annotation(annotation, globalns, locals, cache)
+
+
+TimestampStyle = Literal['f', 'F', 'd', 'D', 't', 'T', 'R']
+
+
+def format_dt(dt: datetime.datetime, /, style: Optional[TimestampStyle] = None) -> str:
+    """A helper function to format a :class:`datetime.datetime` for presentation within Discord.
+
+    This allows for a locale-independent way of presenting data using Discord specific Markdown.
+
+    +-------------+----------------------------+-----------------+
+    |    Style    |       Example Output       |   Description   |
+    +=============+============================+=================+
+    | t           | 22:57                      | Short Time      |
+    +-------------+----------------------------+-----------------+
+    | T           | 22:57:58                   | Long Time       |
+    +-------------+----------------------------+-----------------+
+    | d           | 17/05/2016                 | Short Date      |
+    +-------------+----------------------------+-----------------+
+    | D           | 17 May 2016                | Long Date       |
+    +-------------+----------------------------+-----------------+
+    | f (default) | 17 May 2016 22:57          | Short Date Time |
+    +-------------+----------------------------+-----------------+
+    | F           | Tuesday, 17 May 2016 22:57 | Long Date Time  |
+    +-------------+----------------------------+-----------------+
+    | R           | 5 years ago                | Relative Time   |
+    +-------------+----------------------------+-----------------+
+
+    Note that the exact output depends on the user's locale setting in the client. The example output
+    presented is using the ``en-GB`` locale.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    -----------
+    dt: :class:`datetime.datetime`
+        The datetime to format.
+    style: :class:`str`
+        The style to format the datetime with.
+
+    Returns
+    --------
+    :class:`str`
+        The formatted string.
+    """
+    if style is None:
+        return f'<t:{int(dt.timestamp())}>'
+    return f'<t:{int(dt.timestamp())}:{style}>'

discord/voice_client.py

@@ -20,9 +20,9 @@ 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.
-"""
 
-"""Some documentation to refer to:
+
+Some documentation to refer to:
 
 - Our main web socket (mWS) sends opcode 4 with a guild ID and channel ID.
 - The mWS receives VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE.
@@ -37,20 +37,41 @@ DEALINGS IN THE SOFTWARE.
 - Finally we can transmit data to endpoint:port.
 """
 
+from __future__ import annotations
+
 import asyncio
 import socket
 import logging
 import struct
 import threading
+from typing import Any, Callable, List, Optional, TYPE_CHECKING, Tuple
 
 from . import opus, utils
 from .backoff import ExponentialBackoff
 from .gateway import *
 from .errors import ClientException, ConnectionClosed
 from .player import AudioPlayer, AudioSource
+from .utils import MISSING
+
+if TYPE_CHECKING:
+    from .client import Client
+    from .guild import Guild
+    from .state import ConnectionState
+    from .user import ClientUser
+    from .opus import Encoder
+    from . import abc
+
+    from .types.voice import (
+        GuildVoiceState as GuildVoiceStatePayload,
+        VoiceServerUpdate as VoiceServerUpdatePayload,
+        SupportedModes,
+    )
+    
+
+has_nacl: bool
 
 try:
-    import nacl.secret
+    import nacl.secret  # type: ignore
     has_nacl = True
 except ImportError:
     has_nacl = False
@@ -60,7 +81,10 @@ __all__ = (
     'VoiceClient',
 )
 
-log = logging.getLogger(__name__)
+
+
+
+_log = logging.getLogger(__name__)
 
 class VoiceProtocol:
     """A class that represents the Discord voice protocol.
@@ -71,9 +95,9 @@ class VoiceProtocol:
     This class allows you to implement a protocol to allow for an external
     method of sending voice, such as Lavalink_ or a native library implementation.
 
-    These classes are passed to :meth:`abc.Connectable.connect`.
+    These classes are passed to :meth:`abc.Connectable.connect <VoiceChannel.connect>`.
 
-    .. _Lavalink: https://github.com/Frederikam/Lavalink
+    .. _Lavalink: https://github.com/freyacodes/Lavalink
 
     Parameters
     ------------
@@ -83,11 +107,11 @@ class VoiceProtocol:
         The voice channel that is being connected to.
     """
 
-    def __init__(self, client, channel):
-        self.client = client
-        self.channel = channel
+    def __init__(self, client: Client, channel: abc.Connectable) -> None:
+        self.client: Client = client
+        self.channel: abc.Connectable = channel
 
-    async def on_voice_state_update(self, data):
+    async def on_voice_state_update(self, data: GuildVoiceStatePayload) -> None:
         """|coro|
 
         An abstract method that is called when the client's voice state
@@ -104,7 +128,7 @@ class VoiceProtocol:
         """
         raise NotImplementedError
 
-    async def on_voice_server_update(self, data):
+    async def on_voice_server_update(self, data: VoiceServerUpdatePayload) -> None:
         """|coro|
 
         An abstract method that is called when initially connecting to voice.
@@ -121,7 +145,7 @@ class VoiceProtocol:
         """
         raise NotImplementedError
 
-    async def connect(self, *, timeout, reconnect):
+    async def connect(self, *, timeout: float, reconnect: bool) -> None:
         """|coro|
 
         An abstract method called when the client initiates the connection request.
@@ -144,7 +168,7 @@ class VoiceProtocol:
         """
         raise NotImplementedError
 
-    async def disconnect(self, *, force):
+    async def disconnect(self, *, force: bool) -> None:
         """|coro|
 
         An abstract method called when the client terminates the connection.
@@ -158,7 +182,7 @@ class VoiceProtocol:
         """
         raise NotImplementedError
 
-    def cleanup(self):
+    def cleanup(self) -> None:
         """This method *must* be called to ensure proper clean-up during a disconnect.
 
         It is advisable to call this from within :meth:`disconnect` when you are
@@ -197,48 +221,55 @@ class VoiceClient(VoiceProtocol):
     loop: :class:`asyncio.AbstractEventLoop`
         The event loop that the voice client is running on.
     """
-    def __init__(self, client, channel):
+    endpoint_ip: str
+    voice_port: int
+    secret_key: List[int]
+    ssrc: int
+
+
+    def __init__(self, client: Client, channel: abc.Connectable):
         if not has_nacl:
             raise RuntimeError("PyNaCl library needed in order to use voice")
 
         super().__init__(client, channel)
         state = client._connection
-        self.token = None
-        self.socket = None
-        self.loop = state.loop
-        self._state = state
+        self.token: str = MISSING
+        self.socket = MISSING
+        self.loop: asyncio.AbstractEventLoop = state.loop
+        self._state: ConnectionState = state
         # this will be used in the AudioPlayer thread
-        self._connected = threading.Event()
+        self._connected: threading.Event = threading.Event()
 
-        self._handshaking = False
-        self._potentially_reconnecting = False
-        self._voice_state_complete = asyncio.Event()
-        self._voice_server_complete = asyncio.Event()
+        self._handshaking: bool = False
+        self._potentially_reconnecting: bool = False
+        self._voice_state_complete: asyncio.Event = asyncio.Event()
+        self._voice_server_complete: asyncio.Event = asyncio.Event()
 
-        self.mode = None
-        self._connections = 0
-        self.sequence = 0
-        self.timestamp = 0
-        self._runner = None
-        self._player = None
-        self.encoder = None
-        self._lite_nonce = 0
-        self.ws = None
+        self.mode: str = MISSING
+        self._connections: int = 0
+        self.sequence: int = 0
+        self.timestamp: int = 0
+        self.timeout: float = 0
+        self._runner: asyncio.Task = MISSING
+        self._player: Optional[AudioPlayer] = None
+        self.encoder: Encoder = MISSING
+        self._lite_nonce: int = 0
+        self.ws: DiscordVoiceWebSocket = MISSING
 
     warn_nacl = not has_nacl
-    supported_modes = (
+    supported_modes: Tuple[SupportedModes, ...] = (
         'xsalsa20_poly1305_lite',
         'xsalsa20_poly1305_suffix',
         'xsalsa20_poly1305',
     )
 
     @property
-    def guild(self):
+    def guild(self) -> Optional[Guild]:
         """Optional[:class:`Guild`]: The guild we're connected to, if applicable."""
         return getattr(self.channel, 'guild', None)
 
     @property
-    def user(self):
+    def user(self) -> ClientUser:
         """:class:`ClientUser`: The user connected to voice (i.e. ourselves)."""
         return self._state.user
 
@@ -251,7 +282,7 @@ class VoiceClient(VoiceProtocol):
 
     # connection related
 
-    async def on_voice_state_update(self, data):
+    async def on_voice_state_update(self, data: GuildVoiceStatePayload) -> None:
         self.session_id = data['session_id']
         channel_id = data['channel_id']
 
@@ -264,13 +295,13 @@ class VoiceClient(VoiceProtocol):
                 await self.disconnect()
             else:
                 guild = self.guild
-                self.channel = channel_id and guild and guild.get_channel(int(channel_id))
+                self.channel = channel_id and guild and guild.get_channel(int(channel_id))  # type: ignore
         else:
             self._voice_state_complete.set()
 
-    async def on_voice_server_update(self, data):
+    async def on_voice_server_update(self, data: VoiceServerUpdatePayload) -> None:
         if self._voice_server_complete.is_set():
-            log.info('Ignoring extraneous voice server update.')
+            _log.info('Ignoring extraneous voice server update.')
             return
 
         self.token = data.get('token')
@@ -278,7 +309,7 @@ class VoiceClient(VoiceProtocol):
         endpoint = data.get('endpoint')
 
         if endpoint is None or self.token is None:
-            log.warning('Awaiting endpoint... This requires waiting. ' \
+            _log.warning('Awaiting endpoint... This requires waiting. ' \
                         'If timeout occurred considering raising the timeout and reconnecting.')
             return
 
@@ -288,7 +319,7 @@ class VoiceClient(VoiceProtocol):
             self.endpoint = self.endpoint[6:]
 
         # This gets set later
-        self.endpoint_ip = None
+        self.endpoint_ip = MISSING
 
         self.socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
         self.socket.setblocking(False)
@@ -300,27 +331,27 @@ class VoiceClient(VoiceProtocol):
 
         self._voice_server_complete.set()
 
-    async def voice_connect(self):
+    async def voice_connect(self) -> None:
         await self.channel.guild.change_voice_state(channel=self.channel)
 
-    async def voice_disconnect(self):
-        log.info('The voice handshake is being terminated for Channel ID %s (Guild ID %s)', self.channel.id, self.guild.id)
+    async def voice_disconnect(self) -> None:
+        _log.info('The voice handshake is being terminated for Channel ID %s (Guild ID %s)', self.channel.id, self.guild.id)
         await self.channel.guild.change_voice_state(channel=None)
 
-    def prepare_handshake(self):
+    def prepare_handshake(self) -> None:
         self._voice_state_complete.clear()
         self._voice_server_complete.clear()
         self._handshaking = True
-        log.info('Starting voice handshake... (connection attempt %d)', self._connections + 1)
+        _log.info('Starting voice handshake... (connection attempt %d)', self._connections + 1)
         self._connections += 1
 
-    def finish_handshake(self):
-        log.info('Voice handshake complete. Endpoint found %s', self.endpoint)
+    def finish_handshake(self) -> None:
+        _log.info('Voice handshake complete. Endpoint found %s', self.endpoint)
         self._handshaking = False
         self._voice_server_complete.clear()
         self._voice_state_complete.clear()
 
-    async def connect_websocket(self):
+    async def connect_websocket(self) -> DiscordVoiceWebSocket:
         ws = await DiscordVoiceWebSocket.from_client(self)
         self._connected.clear()
         while ws.secret_key is None:
@@ -328,8 +359,8 @@ class VoiceClient(VoiceProtocol):
         self._connected.set()
         return ws
 
-    async def connect(self, *, reconnect, timeout):
-        log.info('Connecting to voice...')
+    async def connect(self, *, reconnect: bool, timeout: float) ->None:
+        _log.info('Connecting to voice...')
         self.timeout = timeout
 
         for i in range(5):
@@ -357,17 +388,17 @@ class VoiceClient(VoiceProtocol):
                 break
             except (ConnectionClosed, asyncio.TimeoutError):
                 if reconnect:
-                    log.exception('Failed to connect to voice... Retrying...')
+                    _log.exception('Failed to connect to voice... Retrying...')
                     await asyncio.sleep(1 + i * 2.0)
                     await self.voice_disconnect()
                     continue
                 else:
                     raise
 
-        if self._runner is None:
+        if self._runner is MISSING:
             self._runner = self.loop.create_task(self.poll_voice_ws(reconnect))
 
-    async def potential_reconnect(self):
+    async def potential_reconnect(self) -> bool:
         # Attempt to stop the player thread from playing early
         self._connected.clear()
         self.prepare_handshake()
@@ -390,7 +421,7 @@ class VoiceClient(VoiceProtocol):
             return True
 
     @property
-    def latency(self):
+    def latency(self) -> float:
         """:class:`float`: Latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
 
         This could be referred to as the Discord Voice WebSocket latency and is
@@ -402,7 +433,7 @@ class VoiceClient(VoiceProtocol):
         return float("inf") if not ws else ws.latency
 
     @property
-    def average_latency(self):
+    def average_latency(self) -> float:
         """:class:`float`: Average of most recent 20 HEARTBEAT latencies in seconds.
 
         .. versionadded:: 1.4
@@ -410,7 +441,7 @@ class VoiceClient(VoiceProtocol):
         ws = self.ws
         return float("inf") if not ws else ws.average_latency
 
-    async def poll_voice_ws(self, reconnect):
+    async def poll_voice_ws(self, reconnect: bool) -> None:
         backoff = ExponentialBackoff()
         while True:
             try:
@@ -422,14 +453,14 @@ class VoiceClient(VoiceProtocol):
                     # 4014 - voice channel has been deleted.
                     # 4015 - voice server has crashed
                     if exc.code in (1000, 4015):
-                        log.info('Disconnecting from voice normally, close code %d.', exc.code)
+                        _log.info('Disconnecting from voice normally, close code %d.', exc.code)
                         await self.disconnect()
                         break
                     if exc.code == 4014:
-                        log.info('Disconnected from voice by force... potentially reconnecting.')
+                        _log.info('Disconnected from voice by force... potentially reconnecting.')
                         successful = await self.potential_reconnect()
                         if not successful:
-                            log.info('Reconnect was unsuccessful, disconnecting from voice normally...')
+                            _log.info('Reconnect was unsuccessful, disconnecting from voice normally...')
                             await self.disconnect()
                             break
                         else:
@@ -440,7 +471,7 @@ class VoiceClient(VoiceProtocol):
                     raise
 
                 retry = backoff.delay()
-                log.exception('Disconnected from voice... Reconnecting in %.2fs.', retry)
+                _log.exception('Disconnected from voice... Reconnecting in %.2fs.', retry)
                 self._connected.clear()
                 await asyncio.sleep(retry)
                 await self.voice_disconnect()
@@ -448,10 +479,10 @@ class VoiceClient(VoiceProtocol):
                     await self.connect(reconnect=True, timeout=self.timeout)
                 except asyncio.TimeoutError:
                     # at this point we've retried 5 times... let's continue the loop.
-                    log.warning('Could not connect to voice... Retrying...')
+                    _log.warning('Could not connect to voice... Retrying...')
                     continue
 
-    async def disconnect(self, *, force=False):
+    async def disconnect(self, *, force: bool = False) -> None:
         """|coro|
 
         Disconnects this voice client from voice.
@@ -472,7 +503,7 @@ class VoiceClient(VoiceProtocol):
             if self.socket:
                 self.socket.close()
 
-    async def move_to(self, channel):
+    async def move_to(self, channel: abc.Snowflake) -> None:
         """|coro|
 
         Moves you to a different voice channel.
@@ -484,7 +515,7 @@ class VoiceClient(VoiceProtocol):
         """
         await self.channel.guild.change_voice_state(channel=channel)
 
-    def is_connected(self):
+    def is_connected(self) -> bool:
         """Indicates if the voice client is connected to voice."""
         return self._connected.is_set()
 
@@ -503,20 +534,20 @@ class VoiceClient(VoiceProtocol):
         encrypt_packet = getattr(self, '_encrypt_' + self.mode)
         return encrypt_packet(header, data)
 
-    def _encrypt_xsalsa20_poly1305(self, header, data):
+    def _encrypt_xsalsa20_poly1305(self, header: bytes, data) -> bytes:
         box = nacl.secret.SecretBox(bytes(self.secret_key))
         nonce = bytearray(24)
         nonce[:12] = header
 
         return header + box.encrypt(bytes(data), bytes(nonce)).ciphertext
 
-    def _encrypt_xsalsa20_poly1305_suffix(self, header, data):
+    def _encrypt_xsalsa20_poly1305_suffix(self, header: bytes, data) -> bytes:
         box = nacl.secret.SecretBox(bytes(self.secret_key))
         nonce = nacl.utils.random(nacl.secret.SecretBox.NONCE_SIZE)
 
         return header + box.encrypt(bytes(data), nonce).ciphertext + nonce
 
-    def _encrypt_xsalsa20_poly1305_lite(self, header, data):
+    def _encrypt_xsalsa20_poly1305_lite(self, header: bytes, data) -> bytes:
         box = nacl.secret.SecretBox(bytes(self.secret_key))
         nonce = bytearray(24)
 
@@ -525,7 +556,7 @@ class VoiceClient(VoiceProtocol):
 
         return header + box.encrypt(bytes(data), bytes(nonce)).ciphertext + nonce[:4]
 
-    def play(self, source, *, after=None):
+    def play(self, source: AudioSource, *, after: Callable[[Optional[Exception]], Any]=None) -> None:
         """Plays an :class:`AudioSource`.
 
         The finalizer, ``after`` is called after the source has been exhausted
@@ -539,7 +570,7 @@ class VoiceClient(VoiceProtocol):
         -----------
         source: :class:`AudioSource`
             The audio source we're reading from.
-        after: Callable[[:class:`Exception`], Any]
+        after: Callable[[Optional[:class:`Exception`]], Any]
             The finalizer that is called after the stream is exhausted.
             This function must have a single parameter, ``error``, that
             denotes an optional exception that was raised during playing.
@@ -561,7 +592,7 @@ class VoiceClient(VoiceProtocol):
             raise ClientException('Already playing audio.')
 
         if not isinstance(source, AudioSource):
-            raise TypeError(f'source must an AudioSource not {source.__class__.__name__}')
+            raise TypeError(f'source must be an AudioSource not {source.__class__.__name__}')
 
         if not self.encoder and not source.is_opus():
             self.encoder = opus.Encoder()
@@ -569,32 +600,32 @@ class VoiceClient(VoiceProtocol):
         self._player = AudioPlayer(source, self, after=after)
         self._player.start()
 
-    def is_playing(self):
+    def is_playing(self) -> bool:
         """Indicates if we're currently playing audio."""
         return self._player is not None and self._player.is_playing()
 
-    def is_paused(self):
+    def is_paused(self) -> bool:
         """Indicates if we're playing audio, but if we're paused."""
         return self._player is not None and self._player.is_paused()
 
-    def stop(self):
+    def stop(self) -> None:
         """Stops playing audio."""
         if self._player:
             self._player.stop()
             self._player = None
 
-    def pause(self):
+    def pause(self) -> None:
         """Pauses the audio playing."""
         if self._player:
             self._player.pause()
 
-    def resume(self):
+    def resume(self) -> None:
         """Resumes the audio playing."""
         if self._player:
             self._player.resume()
 
     @property
-    def source(self):
+    def source(self) -> Optional[AudioSource]:
         """Optional[:class:`AudioSource`]: The audio source being played, if playing.
 
         This property can also be used to change the audio source currently being played.
@@ -602,7 +633,7 @@ class VoiceClient(VoiceProtocol):
         return self._player.source if self._player else None
 
     @source.setter
-    def source(self, value):
+    def source(self, value: AudioSource) -> None:
         if not isinstance(value, AudioSource):
             raise TypeError(f'expected AudioSource not {value.__class__.__name__}.')
 
@@ -611,7 +642,7 @@ class VoiceClient(VoiceProtocol):
 
         self._player._set_source(value)
 
-    def send_audio_packet(self, data, *, encode=True):
+    def send_audio_packet(self, data: bytes, *, encode: bool = True) -> None:
         """Sends an audio packet composed of the data.
 
         You must be connected to play audio.
@@ -640,6 +671,6 @@ class VoiceClient(VoiceProtocol):
         try:
             self.socket.sendto(packet, (self.endpoint_ip, self.voice_port))
         except BlockingIOError:
-            log.warning('A packet has been dropped (seq: %s, timestamp: %s)', self.sequence, self.timestamp)
+            _log.warning('A packet has been dropped (seq: %s, timestamp: %s)', self.sequence, self.timestamp)
 
         self.checked_add('timestamp', opus.Encoder.SAMPLES_PER_FRAME, 4294967295)

discord/webhook/__init__.py

@@ -0,0 +1,13 @@
+"""
+discord.webhook
+~~~~~~~~~~~~~~
+
+Webhook support
+
+:copyright: (c) 2015-present Rapptz
+:license: MIT, see LICENSE for more details.
+
+"""
+
+from .async_ import *
+from .sync import *