diff --git a/changelog/1538.deprecate.rst b/changelog/1538.deprecate.rst new file mode 100644 index 0000000000..e48bc2a4ce --- /dev/null +++ b/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. diff --git a/disnake/ext/commands/params.py b/disnake/ext/commands/params.py index 5f9b8bf85f..b8bddc47cd 100644 --- a/disnake/ext/commands/params.py +++ b/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,13 +1221,57 @@ 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 @@ -1232,6 +1279,10 @@ def Param( 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,7 +1305,6 @@ 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``. @@ -1263,18 +1312,18 @@ def Param( .. 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 `. """ + 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,