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`

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