Merge branch 'master' into core/v9

Author: Lulalaby

.github/CONTRIBUTING.md

@@ -34,6 +34,11 @@ If the bug report is missing this information then it'll take us longer to fix t
 
 Submitting a pull request is fairly simple, just make sure it focuses on a single aspect and doesn't manage to have scope creep and it's probably good to go. It would be incredibly lovely if the style is consistent to that found in the project. This project follows PEP-8 guidelines (mostly) with a column limit of 125.
 
+## Use of "type: ignore" comments
+In some cases, it might be necessary to ignore type checker warnings for one reason or another.
+If that is that case, it is **required** that a comment is left explaining why you are
+deciding to ignore type checking warnings.
+
 ### Licensing
 
 By submitting a pull request, you agree that; 1) You hold the copyright on all submitted code inside said pull request; 2) You agree to transfer all rights to the owner of this repository, and; 3) If you are found to be in fault with any of the above, we shall not be held responsible in any way after the pull request has been merged.

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,6 +8,7 @@
 
 - [ ] If code changes were made then they have been tested.
     - [ ] I have updated the documentation to reflect the changes.
+- [ ] If `type: ignore` comments were used, a comment is also left explaining why
 - [ ] This PR fixes an issue.
 - [ ] This PR adds something new (e.g. new method or parameters).
 - [ ] This PR is a breaking change (e.g. methods or parameters removed/renamed)

.pylintrc

@@ -0,0 +1,12 @@
+[MESSAGES CONTROL]
+
+disable=protected-access
+
+enable=bad-indentation,line-too-long
+
+
+[FORMAT]
+
+indent-string='    '
+
+max-line-length=120

discord/commands/permissions.py

@@ -35,6 +35,25 @@
 )
 
 class Permission:
+    """The class used in the application command decorators
+    to hash permission data into a dictionary using the
+    :meth:`to_dict` method to be sent to the discord API later on.
+
+    .. versionadded:: 2.0
+
+    Attributes
+    -----------
+    id: Union[:class:`int`, :class:`str`]
+        A string or integer that represents or helps get
+        the id of the user or role that the permission is tied to.
+    type: :class:`int`
+        An integer representing the type of the permission.
+    permission: :class:`bool`
+        A boolean representing the permission's value.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def __init__(self, id: Union[int, str], type: int, permission: bool = True, guild_id: int = None):
         self.id = id
         self.type = type
@@ -45,6 +64,27 @@ def to_dict(self) -> Dict[str, Union[int, bool]]:
         return {"id": self.id, "type": self.type, "permission": self.permission}
 
 def permission(role_id: int = None, user_id: int = None, permission: bool = True, guild_id: int = None):
+    """The method used to specify application command permissions 
+    for specific users or roles using their id.
+
+    This method is meant to be used as a decorator.
+
+    .. versionadded:: 2.0
+
+    Parameters
+    -----------
+    role_id: :class:`int`
+        An integer which represents the id of the role that the
+        permission may be tied to.
+    user_id: :class:`int`
+        An integer which represents the id of the user that the
+        permission may be tied to.
+    permission: :class:`bool`
+        A boolean representing the permission's value.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         if not role_id is None:
             app_cmd_perm = Permission(role_id, 1, permission, guild_id)
@@ -65,6 +105,21 @@ def decorator(func: Callable):
     return decorator
 
 def has_role(item: Union[int, str], guild_id: int = None):
+    """The method used to specify application command role restrictions.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    item: Union[:class:`int`, :class:`str`]
+        An integer or string that represent the id or name of the role 
+        that the permission is tied to.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -81,6 +136,22 @@ def decorator(func: Callable):
     return decorator
 
 def has_any_role(*items: Union[int, str], guild_id: int = None):
+    """The method used to specify multiple application command role restrictions,
+    The application command runs if the invoker has **any** of the specified roles.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    *items: Union[:class:`int`, :class:`str`]
+        The integers or strings that represent the ids or names of the roles
+        that the permission is tied to.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -98,6 +169,20 @@ def decorator(func: Callable):
     return decorator
 
 def is_user(user: int, guild_id: int = None):
+    """The method used to specify application command user restrictions.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    user: :class:`int`
+        An integer that represent the id of the user that the permission is tied to.
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -114,6 +199,19 @@ def decorator(func: Callable):
     return decorator
 
 def is_owner(guild_id: int = None):
+    """The method used to limit application commands exclusively
+    to the owner of the bot.
+    
+    This method is meant to be used as a decorator.
+    
+    .. versionadded:: 2.0
+    
+    Parameters
+    -----------
+    guild_id: :class:`int`
+        The integer which represents the id of the guild that the
+        permission may be tied to.
+    """
     def decorator(func: Callable):
         # Create __app_cmd_perms__
         if not hasattr(func, '__app_cmd_perms__'):
@@ -127,4 +225,4 @@ def decorator(func: Callable):
 
         return func
 
-    return decorator
+    return decorator

discord/webhook/async_.py

@@ -1312,6 +1312,7 @@ async def send(
         view: View = MISSING,
         thread: Snowflake = MISSING,
         wait: bool = False,
+        delete_after: float = None,
     ) -> Optional[WebhookMessage]:
         """|coro|
 
@@ -1377,6 +1378,9 @@ async def send(
             The thread to send this webhook to.
 
             .. versionadded:: 2.0
+        delete_after: :class:`float`
+            If provided, the number of seconds to wait in the background
+            before deleting the message we just sent.
 
         Raises
         --------
@@ -1459,6 +1463,12 @@ async def send(
             message_id = None if msg is None else msg.id
             self._state.store_view(view, message_id)
 
+        if delete_after is not None:
+            async def delete():
+                await asyncio.sleep(delete_after)
+                await msg.delete()
+            asyncio.ensure_future(delete(), loop=self._state.loop)
+
         return msg
 
     async def fetch_message(

docs/conf.py

@@ -159,15 +159,15 @@
 html_theme = 'basic'
 
 html_context = {
-  'discord_invite': 'https://discord.gg/rdXkRJG7pS',
+  'discord_invite': 'https://pycord.dev/discord',
   'discord_extensions': [
     ('discord.ext.commands', 'ext/commands'),
     ('discord.ext.tasks', 'ext/tasks'),
   ],
 }
 
 resource_links = {
-  'discord': 'https://discord.gg/rdXkRJG7pS',
+  'discord': 'https://pycord.dev/discord',
   'issues': 'https://github.com/Pycord-Development/pycord/issues',
   'discussions': 'https://github.com/Pycord-Development/pycord/discussions',
   'examples': f'https://github.com/Pycord-Development/pycord/tree/{branch}/examples',
@@ -357,5 +357,5 @@
 def setup(app):
   if app.config.language == 'ja':
     app.config.intersphinx_mapping['py'] = ('https://docs.python.org/ja/3', None)
-    app.config.html_context['discord_invite'] = 'https://discord.gg/rdXkRJG7pS'
-    app.config.resource_links['discord'] = 'https://discord.gg/rdXkRJG7pS'
+    app.config.html_context['discord_invite'] = 'https://pycord.dev/discord'
+    app.config.resource_links['discord'] = 'https://pycord.dev/discord'

setup.py

@@ -93,5 +93,6 @@
         'Topic :: Software Development :: Libraries :: Python Modules',
         'Topic :: Utilities',
         'Typing :: Typed',
-      ]
+      ],
+      test_suite='tests',
 )