fix(commands): deprecate old Param() aliases properly

changelog/1538.deprecate.rst

@@ -0,0 +1 @@
+|commands| Deprecate old :func:`~ext.commands.Param` kwarg aliases ``desc``, ``conv``, ``autocomp``, ``min_value``, and ``max_value``. Use ``description``, ``converter``, ``autocomplete``, ``ge``, or ``le`` respectively instead.

disnake/ext/commands/params.py

@@ -28,11 +28,13 @@
     TypeVar,
     Union,
     get_origin,
+    overload,
 )
 
 from typing_extensions import ParamSpec, Self
 
 import disnake
+from disnake import utils
 from disnake.app_commands import Option, OptionChoice
 from disnake.channel import _channel_type_factory
 from disnake.enums import ChannelType, OptionType, try_enum_to_int
@@ -569,10 +571,10 @@ def __init__(
         choices: Choices | None = None,
         type: type | None = None,
         channel_types: list[ChannelType] | None = None,
-        lt: int | float | None = None,
-        le: int | float | None = None,
         gt: int | float | None = None,
         ge: int | float | None = None,
+        lt: int | float | None = None,
+        le: int | float | None = None,
         large: bool = False,
         min_length: int | None = None,
         max_length: int | None = None,
@@ -1208,6 +1210,7 @@ def expand_params(command: AnySlashCommand) -> list[Option]:
     return [param.to_option() for param in params]
 
 
+@overload
 def Param(
     default: Any | Callable[[ApplicationCommandInteraction[BotT]], Any] = ...,
     *,
@@ -1218,20 +1221,68 @@ def Param(
     convert_defaults: bool = False,
     autocomplete: AnyAutocompleter | None = None,
     channel_types: list[ChannelType] | None = None,
+    gt: float | None = None,
+    ge: float | None = None,
     lt: float | None = None,
     le: float | None = None,
+    large: bool = False,
+    min_length: int | None = None,
+    max_length: int | None = None,
+) -> Any: ...
+
+
+@overload
+@utils.deprecated(
+    "The `desc`, `conv`, `autocomp`, `min_value`, and `max_value` parameter aliases are deprecated. "
+    "Use `description`, `converter`, `autocomplete`, `ge`, or `le` respectively instead."
+)
+def Param(
+    default: Any | Callable[[ApplicationCommandInteraction[BotT]], Any] = ...,
+    *,
+    name: LocalizedOptional = None,
+    desc: LocalizedOptional = None,
+    choices: Choices | None = None,
+    conv: Callable[[ApplicationCommandInteraction[BotT], Any], Any] | None = None,
+    convert_defaults: bool = False,
+    autocomp: AnyAutocompleter | None = None,
+    channel_types: list[ChannelType] | None = None,
+    min_value: float | None = None,
+    max_value: float | None = None,
+    large: bool = False,
+    min_length: int | None = None,
+    max_length: int | None = None,
+) -> Any: ...
+
+
+def Param(
+    default: Any | Callable[[ApplicationCommandInteraction[BotT]], Any] = ...,
+    *,
+    name: LocalizedOptional = None,
+    description: LocalizedOptional = None,
+    choices: Choices | None = None,
+    converter: Callable[[ApplicationCommandInteraction[BotT], Any], Any] | None = None,
+    convert_defaults: bool = False,
+    autocomplete: AnyAutocompleter | None = None,
+    channel_types: list[ChannelType] | None = None,
     gt: float | None = None,
     ge: float | None = None,
+    lt: float | None = None,
+    le: float | None = None,
     large: bool = False,
     min_length: int | None = None,
     max_length: int | None = None,
+    # for deprecated aliases
     **kwargs: Any,
 ) -> Any:
     r"""A special function that creates an instance of :class:`ParamInfo` that contains some information about a
     slash command option. This instance should be assigned to a parameter of a function representing your slash command.
 
     See :ref:`param_syntax` for more info.
 
+    .. versionchanged:: |vnext|
+        Deprecated kwarg aliases ``desc``, ``conv``, ``autocomp``, ``min_value``, and ``max_value``.
+        Use ``description``, ``converter``, ``autocomplete``, ``ge``, or ``le`` respectively instead.
+
     Parameters
     ----------
     default: Any | :class:`~collections.abc.Callable`\[[:class:`.ApplicationCommandInteraction`], :data:`~typing.Any`]
@@ -1246,7 +1297,6 @@ def Param(
 
     description: :class:`str` | :class:`.Localized` | :data:`None`
         The description of the option. You can skip this kwarg and use docstrings. See :ref:`param_syntax`.
-        Kwarg aliases: ``desc``.
 
         .. versionchanged:: 2.5
             Added support for localizations.
@@ -1255,26 +1305,25 @@ def Param(
         The pre-defined choices for this slash command option.
     converter: :class:`~collections.abc.Callable`\[[:class:`.ApplicationCommandInteraction`, :data:`~typing.Any`], :data:`~typing.Any`]
         A function that will convert the original input to a desired format.
-        Kwarg aliases: ``conv``.
     convert_defaults: :class:`bool`
         Whether to also apply the converter to the provided default value.
         Defaults to ``False``.
 
         .. versionadded:: 2.3
     autocomplete: :class:`~collections.abc.Callable`\[[:class:`.ApplicationCommandInteraction`, :class:`str`], :data:`~typing.Any`]
         A function that will suggest possible autocomplete options while typing.
-        See :ref:`param_syntax`. Kwarg aliases: ``autocomp``.
+        See :ref:`param_syntax`.
     channel_types: :class:`~collections.abc.Iterable`\[:class:`.ChannelType`]
         A list of channel types that should be allowed.
         By default these are discerned from the annotation.
-    lt: :class:`float`
-        The (exclusive) upper bound of values for this option (less-than).
-    le: :class:`float`
-        The (inclusive) upper bound of values for this option (less-than-or-equal). Kwarg aliases: ``max_value``.
     gt: :class:`float`
         The (exclusive) lower bound of values for this option (greater-than).
     ge: :class:`float`
-        The (inclusive) lower bound of values for this option (greater-than-or-equal). Kwarg aliases: ``min_value``.
+        The (inclusive) lower bound of values for this option (greater-than-or-equal).
+    lt: :class:`float`
+        The (exclusive) upper bound of values for this option (less-than).
+    le: :class:`float`
+        The (inclusive) upper bound of values for this option (less-than-or-equal).
     large: :class:`bool`
         For a parameter of type :class:`int`, this controls whether to accept values outside the
         range of ``[-2**53+1, 2**53-1]``, at the cost of reduced Discord-side input validation.
@@ -1309,11 +1358,18 @@ def Param(
             but at runtime this is always a :class:`ParamInfo` instance.
             You can find a more in-depth explanation :ref:`here <why_params_and_injections_return_any>`.
     """
+    if kwargs.keys() & {"desc", "conv", "autocomp", "max_value", "min_value"}:
+        utils.warn_deprecated(
+            "The `desc`, `conv`, `autocomp`, `min_value`, and `max_value` parameter aliases are deprecated. "
+            "Use `description`, `converter`, `autocomplete`, `ge`, or `le` respectively instead.",
+            stacklevel=2,
+        )
+
     description = kwargs.pop("desc", description)
     converter = kwargs.pop("conv", converter)
     autocomplete = kwargs.pop("autocomp", autocomplete)
-    le = kwargs.pop("max_value", le)
     ge = kwargs.pop("min_value", ge)
+    le = kwargs.pop("max_value", le)
 
     if kwargs:
         a = ", ".join(map(repr, kwargs))
@@ -1329,10 +1385,10 @@ def Param(
         convert_default=convert_defaults,
         autocomplete=autocomplete,
         channel_types=channel_types,
-        lt=lt,
-        le=le,
         gt=gt,
         ge=ge,
+        lt=lt,
+        le=le,
         large=large,
         min_length=min_length,
         max_length=max_length,