Update deprecation warnings (#3608)

* Make deprecation notice specify minor release based on soonest date

* Stop specifying a specific release in shared libs deprecation notice

* Add actual deprecation warning for `APIToken` (OMG, this is so cool)

* Add dates (2020-08-05 for all)

* address review

* improve consistency

* Add __dir__ and show APIToken in docs (or maybe I want to annoy Flame)

* fix module name when importing non-existent name from parent package

* Fix stack level used by depr warn in `redbot.core.commands`

docs/framework_commands.rst

@@ -34,3 +34,5 @@ extend functionalities used throughout the bot, as outlined below.
     :members:
     :exclude-members: convert
     :no-undoc-members:
+
+    .. autoclass:: APIToken

redbot/cogs/downloader/downloader.py

@@ -29,7 +29,7 @@ _ = Translator("Downloader", __file__)
 
 DEPRECATION_NOTICE = _(
     "\n**WARNING:** The following repos are using shared libraries"
-    " which are marked for removal in Red 3.4: {repo_list}.\n"
+    " which are marked for removal in the future: {repo_list}.\n"
     " You should inform maintainers of these repos about this message."
 )
 
@@ -245,7 +245,6 @@ class Downloader(commands.Cog):
                     installed[module._json_repo_name].pop(module.name)
 
     async def _shared_lib_load_check(self, cog_name: str) -> Optional[Repo]:
-        # remove in Red 3.4
         is_installed, cog = await self.is_installed(cog_name)
         # it's not gonna be None when `is_installed` is True
         # if we'll use typing_extensions in future, `Literal` can solve this

redbot/core/_sharedlibdeprecation.py

@@ -22,7 +22,7 @@ class SharedLibImportWarner(MetaPathFinder):
             return None
         msg = (
             "One of cogs uses shared libraries which are"
-            " deprecated and scheduled for removal in Red 3.4.\n"
+            " deprecated and scheduled for removal in the future.\n"
             "You should inform author of the cog about this message."
         )
         warnings.warn(msg, SharedLibDeprecationWarning, stacklevel=2)

redbot/core/commands/__init__.py

@@ -19,7 +19,6 @@ from .commands import (
 )
 from .context import Context as Context, GuildContext as GuildContext, DMContext as DMContext
 from .converter import (
-    APIToken as APIToken,
     DictConverter as DictConverter,
     GuildConverter as GuildConverter,
     TimedeltaConverter as TimedeltaConverter,
@@ -29,6 +28,7 @@ from .converter import (
     NoParseOptional as NoParseOptional,
     UserInputOptional as UserInputOptional,
     Literal as Literal,
+    __getattr__ as _converter__getattr__,  # this contains deprecation of APIToken
 )
 from .errors import (
     ConversionFailure as ConversionFailure,
@@ -143,3 +143,14 @@ from discord.ext.commands import (
     MaxConcurrencyReached as MaxConcurrencyReached,
     bot_has_guild_permissions as bot_has_guild_permissions,
 )
+
+
+def __getattr__(name):
+    try:
+        return _converter__getattr__(name, stacklevel=3)
+    except AttributeError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+
+def __dir__():
+    return [*globals().keys(), "APIToken"]

redbot/core/commands/converter.py

@@ -5,9 +5,10 @@ This module contains useful functions and classes for command argument conversio
 
 Some of the converters within are included provisionaly and are marked as such.
 """
+import functools
 import os
 import re
-import functools
+import warnings
 from datetime import timedelta
 from typing import (
     TYPE_CHECKING,
@@ -20,6 +21,7 @@ from typing import (
     Type,
     TypeVar,
     Literal as Literal,
+    Any,
 )
 
 import discord
@@ -33,7 +35,6 @@ if TYPE_CHECKING:
     from .context import Context
 
 __all__ = [
-    "APIToken",
     "DictConverter",
     "GuildConverter",
     "UserInputOptional",
@@ -154,7 +155,7 @@ class GuildConverter(discord.Guild):
         return ret
 
 
-class APIToken(discord.ext.commands.Converter):
+class _APIToken(discord.ext.commands.Converter):
     """Converts to a `dict` object.
 
     This will parse the input argument separating the key value pairs into a 
@@ -168,7 +169,7 @@ class APIToken(discord.ext.commands.Converter):
     Note: Core usage of this has been replaced with `DictConverter` use instead.
 
     .. warning::
-        This will be removed in version 3.4.
+        This will be removed in the first minor release after 2020-08-05.
     """
 
     async def convert(self, ctx: "Context", argument) -> dict:
@@ -185,6 +186,26 @@ class APIToken(discord.ext.commands.Converter):
         return result
 
 
+_APIToken.__name__ = "APIToken"
+
+
+def __getattr__(name: str, *, stacklevel: int = 2) -> Any:
+    # honestly, this is awesome (PEP-562)
+    if name == "APIToken":
+        warnings.warn(
+            "`APIToken` is deprecated since Red 3.3.0 and will be removed"
+            " in the first minor release after 2020-08-05. Use `DictConverter` instead.",
+            DeprecationWarning,
+            stacklevel=stacklevel,
+        )
+        return globals()["_APIToken"]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> List[str]:
+    return [*globals().keys(), "APIToken"]
+
+
 # Below this line are a lot of lies for mypy about things that *end up* correct when
 # These are used for command conversion purposes. Please refer to the portion
 # which is *not* for type checking for the actual implementation

redbot/core/core_commands.py

@@ -778,13 +778,13 @@ class Core(commands.Cog, CoreLogic):
             if len(repos_with_shared_libs) == 1:
                 formed = _(
                     "**WARNING**: The following repo is using shared libs"
-                    " which are marked for removal in Red 3.4: {repo}.\n"
+                    " which are marked for removal in the future: {repo}.\n"
                     "You should inform maintainer of the repo about this message."
                 ).format(repo=inline(repos_with_shared_libs.pop()))
             else:
                 formed = _(
                     "**WARNING**: The following repos are using shared libs"
-                    " which are marked for removal in Red 3.4: {repos}.\n"
+                    " which are marked for removal in the future: {repos}.\n"
                     "You should inform maintainers of these repos about this message."
                 ).format(repos=humanize_list([inline(repo) for repo in repos_with_shared_libs]))
             output.append(formed)
@@ -896,13 +896,13 @@ class Core(commands.Cog, CoreLogic):
             if len(repos_with_shared_libs) == 1:
                 formed = _(
                     "**WARNING**: The following repo is using shared libs"
-                    " which are marked for removal in Red 3.4: {repo}.\n"
+                    " which are marked for removal in the future: {repo}.\n"
                     "You should inform maintainers of these repos about this message."
                 ).format(repo=inline(repos_with_shared_libs.pop()))
             else:
                 formed = _(
                     "**WARNING**: The following repos are using shared libs"
-                    " which are marked for removal in Red 3.4: {repos}.\n"
+                    " which are marked for removal in the future: {repos}.\n"
                     "You should inform maintainers of these repos about this message."
                 ).format(repos=humanize_list([inline(repo) for repo in repos_with_shared_libs]))
             output.append(formed)

redbot/core/utils/__init__.py

@@ -184,8 +184,8 @@ def bounded_gather_iter(
     """
     if loop is not None:
         warnings.warn(
-            "Explicitly passing the loop will not work in Red 3.4+ and is currently ignored."
+            "`loop` kwarg is deprecated since Red 3.3.1. It is currently being ignored"
-            "Call this from the related event loop.",
+            " and will be removed in the first minor release after 2020-08-05.",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -242,8 +242,8 @@ def bounded_gather(
     """
     if loop is not None:
         warnings.warn(
-            "Explicitly passing the loop will not work in Red 3.4+ and is currently ignored."
+            "`loop` kwarg is deprecated since Red 3.3.1. It is currently being ignored"
-            "Call this from the related event loop.",
+            " and will be removed in the first minor release after 2020-08-05.",
             DeprecationWarning,
             stacklevel=2,
         )

redbot/core/utils/menus.py

@@ -214,7 +214,8 @@ def start_adding_reactions(
         loop = asyncio.get_running_loop()
     else:
         warnings.warn(
-            "Explicitly passing the loop will not work in Red 3.4+",
+            "`loop` kwarg is deprecated since Red 3.3.1. It is currently being ignored"
+            " and will be removed in the first minor release after 2020-08-05.",
             DeprecationWarning,
             stacklevel=2,
         )