Merge core/typing

.github/workflows/docs.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ 3.8 ]
+        python-version: [ '3.10' ]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}
@@ -17,7 +17,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install -U pip
-        pip install -U sphinx sphinxcontrib-trio aiohttp sphinxcontrib-websupport myst-parser
+        pip install -U sphinx sphinxcontrib-trio aiohttp sphinxcontrib-websupport myst-parser typing-extensions
     - name: Compile to html
       run: |
         cd docs

discord/asset.py

@@ -268,11 +268,11 @@ def __str__(self) -> str:
     def __len__(self) -> int:
         return len(self._url)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         shorten = self._url.replace(self.BASE, '')
         return f'<Asset url={shorten!r}>'
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         return isinstance(other, Asset) and self._url == other._url
 
     def __hash__(self):

discord/bot.py

@@ -40,6 +40,7 @@
     Type,
     TypeVar,
     Union,
+    Type,
 )
 
 from .client import Client

discord/commands/_types.py

@@ -0,0 +1,16 @@
+from typing import Callable, TYPE_CHECKING, Union, Coroutine, Any, TypeVar
+
+if TYPE_CHECKING:
+    from .. import Cog, ApplicationContext
+
+T = TypeVar('T')
+
+Coro = Coroutine[Any, Any, T]
+MaybeCoro = Union[T, Coro[T]]
+CoroFunc = Callable[..., Coro[Any]]
+
+Check = Union[Callable[["Cog", "ApplicationContext[Any]"], MaybeCoro[bool]],
+              Callable[["ApplicationContext[Any]"], MaybeCoro[bool]]]
+Hook = Union[Callable[["Cog", "ApplicationContext[Any]"], Coro[Any]], Callable[["ApplicationContext[Any]"], Coro[Any]]]
+Error = Union[Callable[["Cog", "ApplicationContext[Any]", "CommandError"], Coro[Any]],
+              Callable[["ApplicationContext[Any]", "CommandError"], Coro[Any]]]

discord/commands/context.py

@@ -24,21 +24,26 @@
 """
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Optional, TypeVar, Union
+from typing import TYPE_CHECKING, Optional, Union, TypeVar, Generic, Callable, List, Any, Dict
 
-import discord.abc
+import discord.utils
 
 if TYPE_CHECKING:
-    from typing_extensions import ParamSpec
-
-    import discord
-    from discord import Bot
-    from discord.state import ConnectionState
-
-    from .core import ApplicationCommand, Option
+    from . import ApplicationCommand, Option
     from ..cog import Cog
-    from ..webhook import WebhookMessage
-    from typing import Callable
+    from ..embeds import Embed
+    from ..file import File
+    from ..guild import Guild
+    from ..interactions import Interaction, InteractionChannel, InteractionResponse, InteractionMessage
+    from ..member import Member
+    from ..mentions import AllowedMentions
+    from ..message import Message
+    from ..state import ConnectionState
+    from ..user import User
+    from ..ui import View
+    from ..voice_client import VoiceProtocol
+    from ..webhook import Webhook, WebhookMessage
+    from typing_extensions import ParamSpec
 
 from ..guild import Guild
 from ..interactions import Interaction, InteractionResponse
@@ -58,7 +63,18 @@
 __all__ = ("ApplicationContext", "AutocompleteContext")
 
 
-class ApplicationContext(discord.abc.Messageable):
+MISSING: Any = discord.utils.MISSING
+
+T = TypeVar("T")
+BotT = TypeVar("BotT", bound="Union[discord.Bot, discord.AutoShardedBot]")
+CogT = TypeVar("CogT", bound="Cog")
+
+if TYPE_CHECKING:
+    P = ParamSpec('P')
+else:
+    P = TypeVar('P')
+
+class ApplicationContext(discord.abc.Messageable, Generic[BotT]):
     """Represents a Discord application command interaction context.
 
     This class is not created manually and is instead passed to application
@@ -76,9 +92,9 @@ class ApplicationContext(discord.abc.Messageable):
         The command that this context belongs to.
     """
 
-    def __init__(self, bot: Bot, interaction: Interaction):
-        self.bot = bot
-        self.interaction = interaction
+    def __init__(self, bot: BotT, interaction: Interaction) -> None:
+        self.bot: BotT = bot
+        self.interaction: Interaction = interaction
 
         # below attributes will be set after initialization
         self.command: ApplicationCommand = None  # type: ignore
@@ -88,7 +104,7 @@ def __init__(self, bot: Bot, interaction: Interaction):
 
         self._state: ConnectionState = self.interaction._state
 
-    async def _get_channel(self) -> discord.abc.Messageable:
+    async def _get_channel(self) -> Optional[InteractionChannel]:
         return self.channel
 
     async def invoke(self, command: ApplicationCommand[CogT, P, T], /, *args: P.args, **kwargs: P.kwargs) -> T:
@@ -118,7 +134,7 @@ async def invoke(self, command: ApplicationCommand[CogT, P, T], /, *args: P.args
         return await command(self, *args, **kwargs)
 
     @cached_property
-    def channel(self):
+    def channel(self) -> Optional[InteractionChannel]:
         return self.interaction.channel
 
     @cached_property
@@ -133,14 +149,6 @@ def guild(self) -> Optional[Guild]:
     def guild_id(self) -> Optional[int]:
         return self.interaction.guild_id
 
-    @cached_property
-    def locale(self) -> Optional[str]:
-        return self.interaction.locale
-
-    @cached_property
-    def guild_locale(self) -> Optional[str]:
-        return self.interaction.guild_locale
-
     @cached_property
     def me(self) -> Union[Member, User]:
         return self.guild.me if self.guild is not None else self.bot.user
@@ -168,6 +176,14 @@ def voice_client(self):
     def response(self) -> InteractionResponse:
         return self.interaction.response
 
+    @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:
+            return None
+
+        return self.command.cog
+
     @property
     def respond(self) -> Callable[..., Union[Interaction, WebhookMessage]]:
         """Callable[..., Union[:class:`~.Interaction`, :class:`~.Webhook`]]: Sends either a response
@@ -195,33 +211,42 @@ def send_followup(self):
                 f"Interaction was not yet issued a response. Try using {type(self).__name__}.respond() first."
             )
 
-    @property
-    def defer(self):
-        return self.interaction.response.defer
+    @discord.utils.copy_doc(InteractionResponse.defer)
+    async def defer(self, *, ephemeral: bool = False) -> None:
+        return await self.interaction.response.defer(ephemeral=ephemeral)
 
     @property
-    def followup(self):
+    def followup(self) -> Webhook:
         return self.interaction.followup
 
-    async def delete(self):
+    async def delete(self) -> None:
         """Calls :attr:`~discord.commands.ApplicationContext.respond`.
         If the response is done, then calls :attr:`~discord.commands.ApplicationContext.respond` first."""
         if not self.response.is_done():
             await self.defer()
 
         return await self.interaction.delete_original_message()
 
-    @property
-    def edit(self):
-        return self.interaction.edit_original_message
-
-    @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:
-            return None
-
-        return self.command.cog
+    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:
+        return await self.interaction.edit_original_message(
+            content=content,
+            embeds=embeds,
+            embed=embed,
+            file=file,
+            files=files,
+            view=view,
+            allowed_mentions=allowed_mentions,
+        )
 
 
 class AutocompleteContext:
@@ -248,18 +273,24 @@ class AutocompleteContext:
     """
 
     __slots__ = ("bot", "interaction", "command", "focused", "value", "options")
-
-    def __init__(self, bot: Bot, interaction: Interaction) -> None:
-        self.bot = bot
-        self.interaction = interaction
-
-        self.command: ApplicationCommand = None  # type: ignore
-        self.focused: Option = None  # type: ignore
-        self.value: str = None  # type: ignore
-        self.options: dict = None  # type: ignore
+
+    def __init__(
+        self,
+        interaction: Interaction,
+        *,
+        command: ApplicationCommand,
+        focused: Option,
+        value: str,
+        options: Dict[str, Any],
+    ) -> None:
+        self.interaction: Interaction = interaction
+        self.command: ApplicationCommand = command
+        self.focused: Option = focused
+        self.value: str = value
+        self.options: Dict[str, Any] = options
 
     @property
-    def cog(self) -> Optional[Cog]:
+    def cog(self) -> Optional[CogT]:
         """Optional[:class:`.Cog`]: Returns the cog associated with this context's command. ``None`` if it does not exist."""
         if self.command is None:
             return None