Browse Source
This facilitates the "converter-like" API of the app_commands submodule. As a consequence of this refactor, more types are supported like channels and attachment.pull/7492/head
Rapptz
3 years ago
4 changed files with 565 additions and 189 deletions
@ -0,0 +1,496 @@ |
|||
""" |
|||
The MIT License (MIT) |
|||
|
|||
Copyright (c) 2015-present Rapptz |
|||
|
|||
Permission is hereby granted, free of charge, to any person obtaining a |
|||
copy of this software and associated documentation files (the "Software"), |
|||
to deal in the Software without restriction, including without limitation |
|||
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
|||
and/or sell copies of the Software, and to permit persons to whom the |
|||
Software is furnished to do so, subject to the following conditions: |
|||
|
|||
The above copyright notice and this permission notice shall be included in |
|||
all copies or substantial portions of the Software. |
|||
|
|||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS |
|||
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
|||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
|||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
|||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
|||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
|||
DEALINGS IN THE SOFTWARE. |
|||
""" |
|||
|
|||
from __future__ import annotations |
|||
import inspect |
|||
|
|||
from dataclasses import dataclass |
|||
from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Optional, Set, Tuple, Type, TypeVar, Union |
|||
|
|||
from .enums import AppCommandOptionType |
|||
from .errors import TransformerError |
|||
from .models import AppCommandChannel, AppCommandThread, Choice |
|||
from ..channel import StageChannel, StoreChannel, VoiceChannel, TextChannel, CategoryChannel |
|||
from ..enums import ChannelType |
|||
from ..utils import MISSING |
|||
from ..user import User |
|||
from ..role import Role |
|||
from ..member import Member |
|||
from ..message import Attachment |
|||
|
|||
__all__ = ( |
|||
'Transformer', |
|||
'Transform', |
|||
) |
|||
|
|||
T = TypeVar('T') |
|||
NoneType = type(None) |
|||
|
|||
if TYPE_CHECKING: |
|||
from ..interactions import Interaction |
|||
|
|||
|
|||
@dataclass |
|||
class CommandParameter: |
|||
"""Represents a application command parameter. |
|||
|
|||
Attributes |
|||
----------- |
|||
name: :class:`str` |
|||
The name of the parameter. |
|||
description: :class:`str` |
|||
The description of the parameter |
|||
required: :class:`bool` |
|||
Whether the parameter is required |
|||
choices: List[:class:`~discord.app_commands.Choice`] |
|||
A list of choices this parameter takes |
|||
type: :class:`~discord.app_commands.AppCommandOptionType` |
|||
The underlying type of this parameter. |
|||
channel_types: List[:class:`~discord.ChannelType`] |
|||
The channel types that are allowed for this parameter. |
|||
min_value: Optional[Union[:class:`int`, :class:`float`]] |
|||
The minimum supported value for this parameter. |
|||
max_value: Optional[Union[:class:`int`, :class:`float`]] |
|||
The maximum supported value for this parameter. |
|||
autocomplete: :class:`bool` |
|||
Whether this parameter enables autocomplete. |
|||
""" |
|||
|
|||
name: str = MISSING |
|||
description: str = MISSING |
|||
required: bool = MISSING |
|||
default: Any = MISSING |
|||
choices: List[Choice] = MISSING |
|||
type: AppCommandOptionType = MISSING |
|||
channel_types: List[ChannelType] = MISSING |
|||
min_value: Optional[Union[int, float]] = None |
|||
max_value: Optional[Union[int, float]] = None |
|||
autocomplete: bool = MISSING |
|||
_annotation: Any = MISSING |
|||
|
|||
def to_dict(self) -> Dict[str, Any]: |
|||
base = { |
|||
'type': self.type.value, |
|||
'name': self.name, |
|||
'description': self.description, |
|||
'required': self.required, |
|||
} |
|||
|
|||
if self.choices: |
|||
base['choices'] = [choice.to_dict() for choice in self.choices] |
|||
if self.channel_types: |
|||
base['channel_types'] = [t.value for t in self.channel_types] |
|||
if self.autocomplete: |
|||
base['autocomplete'] = True |
|||
if self.min_value is not None: |
|||
base['min_value'] = self.min_value |
|||
if self.max_value is not None: |
|||
base['max_value'] = self.max_value |
|||
|
|||
return base |
|||
|
|||
async def transform(self, interaction: Interaction, value: Any) -> Any: |
|||
if hasattr(self._annotation, '__discord_app_commands_transformer__'): |
|||
return await self._annotation.transform(interaction, value) |
|||
return value |
|||
|
|||
|
|||
class Transformer: |
|||
"""The base class that allows a type annotation in an application command parameter |
|||
to map into a :class:`AppCommandOptionType` and transform the raw value into one from |
|||
this type. |
|||
|
|||
This class is customisable through the overriding of :obj:`classmethod`s in the class |
|||
and by using it as the second type parameter of the :class:`~discord.app_commands.Transform` |
|||
class. For example, to convert a string into a custom pair type: |
|||
|
|||
.. code-block:: python3 |
|||
|
|||
class Point(typing.NamedTuple): |
|||
x: int |
|||
y: int |
|||
|
|||
class PointTransformer(app_commands.Transformer): |
|||
@classmethod |
|||
async def transform(cls, interaction: discord.Interaction, value: str) -> Point: |
|||
(x, _, y) = value.partition(',') |
|||
return Point(x=int(x.strip()), y=int(y.strip())) |
|||
|
|||
@app_commands.command() |
|||
async def graph( |
|||
interaction: discord.Interaction, |
|||
point: app_commands.Transform[Point, PointTransformer], |
|||
): |
|||
await interaction.response.send_message(str(point)) |
|||
|
|||
.. versionadded:: 2.0 |
|||
""" |
|||
|
|||
__discord_app_commands_transformer__: ClassVar[bool] = True |
|||
|
|||
@classmethod |
|||
def type(cls) -> AppCommandOptionType: |
|||
""":class:`AppCommandOptionType`: The option type associated with this transformer. |
|||
|
|||
This must be a :obj:`classmethod`. |
|||
|
|||
Defaults to :attr:`AppCommandOptionType.string`. |
|||
""" |
|||
return AppCommandOptionType.string |
|||
|
|||
@classmethod |
|||
def channel_types(cls) -> List[ChannelType]: |
|||
"""List[:class:`~discord.ChannelType`]: A list of channel types that are allowed to this parameter. |
|||
|
|||
Only valid if the :meth:`type` returns :attr:`AppCommandOptionType.channel`. |
|||
|
|||
Defaults to an empty list. |
|||
""" |
|||
return [] |
|||
|
|||
@classmethod |
|||
def min_value(cls) -> Optional[Union[int, float]]: |
|||
"""Optional[:class:`int`]: The minimum supported value for this parameter. |
|||
|
|||
Only valid if the :meth:`type` returns :attr:`AppCommandOptionType.number` or |
|||
:attr:`AppCommandOptionType.integer`. |
|||
|
|||
Defaults to ``None``. |
|||
""" |
|||
return None |
|||
|
|||
@classmethod |
|||
def max_value(cls) -> Optional[Union[int, float]]: |
|||
"""Optional[:class:`int`]: The maximum supported value for this parameter. |
|||
|
|||
Only valid if the :meth:`type` returns :attr:`AppCommandOptionType.number` or |
|||
:attr:`AppCommandOptionType.integer`. |
|||
|
|||
Defaults to ``None``. |
|||
""" |
|||
return None |
|||
|
|||
@classmethod |
|||
async def transform(cls, interaction: Interaction, value: Any) -> Any: |
|||
"""|coro| |
|||
|
|||
Transforms the converted option value into another value. |
|||
|
|||
The value passed into this transform function is the same as the |
|||
one in the :class:`conversion table <discord.app_commands.Namespace>`. |
|||
|
|||
Parameters |
|||
----------- |
|||
interaction: :class:`~discord.Interaction` |
|||
The interaction being handled. |
|||
value: Any |
|||
The value of the given argument after being resolved. |
|||
See the :class:`conversion table <discord.app_commands.Namespace>` |
|||
for how certain option types correspond to certain values. |
|||
""" |
|||
raise NotImplementedError('Derived classes need to implement this.') |
|||
|
|||
|
|||
class _TransformMetadata: |
|||
__discord_app_commands_transform__: ClassVar[bool] = True |
|||
__slots__ = ('metadata',) |
|||
|
|||
def __init__(self, metadata: Type[Transformer]): |
|||
self.metadata: Type[Transformer] = metadata |
|||
|
|||
|
|||
def _dynamic_transformer( |
|||
opt_type: AppCommandOptionType, |
|||
*, |
|||
channel_types: List[ChannelType] = MISSING, |
|||
min: Optional[Union[int, float]] = None, |
|||
max: Optional[Union[int, float]] = None, |
|||
) -> Type[Transformer]: |
|||
types = channel_types or [] |
|||
|
|||
async def transform(cls, interaction: Interaction, value: Any) -> Any: |
|||
return value |
|||
|
|||
ns = { |
|||
'type': classmethod(lambda _: opt_type), |
|||
'channel_types': classmethod(lambda _: types), |
|||
'min_value': classmethod(lambda _: min), |
|||
'max_value': classmethod(lambda _: max), |
|||
'transform': classmethod(transform), |
|||
} |
|||
return type('_DynamicTransformer', (Transformer,), ns) |
|||
|
|||
|
|||
if TYPE_CHECKING: |
|||
from typing_extensions import Annotated as Transform |
|||
else: |
|||
|
|||
class Transform: |
|||
"""A type annotation that can be applied to a parameter to customise the behaviour of |
|||
an option type by transforming with the given :class:`Transformer`. This requires |
|||
the usage of two generic parameters, the first one is the type you're converting to and the second |
|||
one is the type of the :class:`Transformer` actually doing the transformation. |
|||
|
|||
During type checking time this is equivalent to :obj:`py:Annotated` so type checkers understand |
|||
the intent of the code. |
|||
|
|||
For example usage, check :class:`Transformer`. |
|||
|
|||
.. versionadded:: 2.0 |
|||
""" |
|||
|
|||
def __class_getitem__(cls, items) -> _TransformMetadata: |
|||
if not isinstance(items, tuple): |
|||
raise TypeError(f'expected tuple for arguments, received {items.__class__!r} instead') |
|||
|
|||
if len(items) != 2: |
|||
raise TypeError(f'Transform only accepts exactly two arguments') |
|||
|
|||
_, transformer = items |
|||
|
|||
is_valid = inspect.isclass(transformer) and issubclass(transformer, Transformer) |
|||
if not is_valid: |
|||
raise TypeError(f'second argument of Transform must be a Transformer class not {transformer!r}') |
|||
|
|||
return _TransformMetadata(transformer) |
|||
|
|||
|
|||
def passthrough_transformer(opt_type: AppCommandOptionType) -> Type[Transformer]: |
|||
class _Generated(Transformer): |
|||
@classmethod |
|||
def type(cls) -> AppCommandOptionType: |
|||
return opt_type |
|||
|
|||
@classmethod |
|||
async def transform(cls, interaction: Interaction, value: Any) -> Any: |
|||
return value |
|||
|
|||
return _Generated |
|||
|
|||
|
|||
class MemberTransformer(Transformer): |
|||
@classmethod |
|||
def type(cls) -> AppCommandOptionType: |
|||
return AppCommandOptionType.user |
|||
|
|||
@classmethod |
|||
async def transform(cls, interaction: Interaction, value: Any) -> Member: |
|||
if not isinstance(value, Member): |
|||
raise TransformerError(value, cls.type(), cls) |
|||
return value |
|||
|
|||
|
|||
def channel_transformer(*channel_types: Type[Any], raw: Optional[bool] = False) -> Type[Transformer]: |
|||
if raw: |
|||
|
|||
async def transform(cls, interaction: Interaction, value: Any): |
|||
if not isinstance(value, channel_types): |
|||
raise TransformerError(value, AppCommandOptionType.channel, cls) |
|||
return value |
|||
|
|||
elif raw is False: |
|||
|
|||
async def transform(cls, interaction: Interaction, value: Any): |
|||
resolved = value.resolve() |
|||
if resolved is None or not isinstance(resolved, channel_types): |
|||
raise TransformerError(value, AppCommandOptionType.channel, cls) |
|||
return resolved |
|||
|
|||
else: |
|||
|
|||
async def transform(cls, interaction: Interaction, value: Any): |
|||
if isinstance(value, channel_types): |
|||
return value |
|||
|
|||
resolved = value.resolve() |
|||
if resolved is None or not isinstance(resolved, channel_types): |
|||
raise TransformerError(value, AppCommandOptionType.channel, cls) |
|||
return resolved |
|||
|
|||
if len(channel_types) == 1: |
|||
name = channel_types[0].__name__ |
|||
types = CHANNEL_TO_TYPES[channel_types[0]] |
|||
else: |
|||
name = 'MultiChannel' |
|||
types = [] |
|||
|
|||
for t in channel_types: |
|||
try: |
|||
types.extend(CHANNEL_TO_TYPES[t]) |
|||
except KeyError: |
|||
raise TypeError(f'Union type of channels must be entirely made up of channels') from None |
|||
|
|||
return type( |
|||
f'{name}Transformer', |
|||
(Transformer,), |
|||
{ |
|||
'type': classmethod(lambda cls: AppCommandOptionType.channel), |
|||
'transform': classmethod(transform), |
|||
'channel_types': classmethod(lambda cls: types), |
|||
}, |
|||
) |
|||
|
|||
|
|||
CHANNEL_TO_TYPES: Dict[Any, List[ChannelType]] = { |
|||
AppCommandChannel: [ |
|||
ChannelType.stage_voice, |
|||
ChannelType.store, |
|||
ChannelType.voice, |
|||
ChannelType.text, |
|||
ChannelType.category, |
|||
], |
|||
AppCommandThread: [ChannelType.news_thread, ChannelType.private_thread, ChannelType.public_thread], |
|||
StageChannel: [ChannelType.stage_voice], |
|||
StoreChannel: [ChannelType.store], |
|||
VoiceChannel: [ChannelType.voice], |
|||
TextChannel: [ChannelType.text], |
|||
CategoryChannel: [ChannelType.category], |
|||
} |
|||
|
|||
BUILT_IN_TRANSFORMERS: Dict[Any, Type[Transformer]] = { |
|||
str: passthrough_transformer(AppCommandOptionType.string), |
|||
int: passthrough_transformer(AppCommandOptionType.integer), |
|||
float: passthrough_transformer(AppCommandOptionType.number), |
|||
bool: passthrough_transformer(AppCommandOptionType.boolean), |
|||
User: passthrough_transformer(AppCommandOptionType.user), |
|||
Member: MemberTransformer, |
|||
Role: passthrough_transformer(AppCommandOptionType.role), |
|||
AppCommandChannel: channel_transformer(AppCommandChannel, raw=True), |
|||
AppCommandThread: channel_transformer(AppCommandThread, raw=True), |
|||
StageChannel: channel_transformer(StageChannel), |
|||
StoreChannel: channel_transformer(StoreChannel), |
|||
VoiceChannel: channel_transformer(VoiceChannel), |
|||
TextChannel: channel_transformer(TextChannel), |
|||
CategoryChannel: channel_transformer(CategoryChannel), |
|||
Attachment: passthrough_transformer(AppCommandOptionType.attachment), |
|||
} |
|||
|
|||
ALLOWED_DEFAULTS: Dict[AppCommandOptionType, Tuple[Type[Any], ...]] = { |
|||
AppCommandOptionType.string: (str, NoneType), |
|||
AppCommandOptionType.integer: (int, NoneType), |
|||
AppCommandOptionType.boolean: (bool, NoneType), |
|||
} |
|||
|
|||
|
|||
def get_supported_annotation( |
|||
annotation: Any, |
|||
*, |
|||
_none=NoneType, |
|||
_mapping: Dict[Any, Type[Transformer]] = BUILT_IN_TRANSFORMERS, |
|||
) -> Tuple[Any, Any]: |
|||
"""Returns an appropriate, yet supported, annotation along with an optional default value. |
|||
|
|||
This differs from the built in mapping by supporting a few more things. |
|||
Likewise, this returns a "transformed" annotation that is ready to use with CommandParameter.transform. |
|||
""" |
|||
|
|||
try: |
|||
return (_mapping[annotation], MISSING) |
|||
except KeyError: |
|||
pass |
|||
|
|||
if hasattr(annotation, '__discord_app_commands_transform__'): |
|||
return (annotation.metadata, MISSING) |
|||
|
|||
if inspect.isclass(annotation) and issubclass(annotation, Transformer): |
|||
return (annotation, MISSING) |
|||
|
|||
# Check if there's an origin |
|||
origin = getattr(annotation, '__origin__', None) |
|||
if origin is not Union: |
|||
# Only Union/Optional is supported right now so bail early |
|||
raise TypeError(f'unsupported type annotation {annotation!r}') |
|||
|
|||
default = MISSING |
|||
args = annotation.__args__ # type: ignore |
|||
if args[-1] is _none: |
|||
if len(args) == 2: |
|||
underlying = args[0] |
|||
inner, _ = get_supported_annotation(underlying) |
|||
if inner is None: |
|||
raise TypeError(f'unsupported inner optional type {underlying!r}') |
|||
return (inner, None) |
|||
else: |
|||
args = args[:-1] |
|||
default = None |
|||
|
|||
# Check for channel union types |
|||
if any(arg in CHANNEL_TO_TYPES for arg in args): |
|||
# If any channel type is given, then *all* must be channel types |
|||
return (channel_transformer(*args, raw=None), default) |
|||
|
|||
# The only valid transformations here are: |
|||
# [Member, User] => user |
|||
# [Member, User, Role] => mentionable |
|||
# [Member | User, Role] => mentionable |
|||
supported_types: Set[Any] = {Role, Member, User} |
|||
if not all(arg in supported_types for arg in args): |
|||
raise TypeError(f'unsupported types given inside {annotation!r}') |
|||
if args == (User, Member) or args == (Member, User): |
|||
return (passthrough_transformer(AppCommandOptionType.user), default) |
|||
|
|||
return (passthrough_transformer(AppCommandOptionType.mentionable), default) |
|||
|
|||
|
|||
def annotation_to_parameter(annotation: Any, parameter: inspect.Parameter) -> CommandParameter: |
|||
"""Returns the appropriate :class:`CommandParameter` for the given annotation. |
|||
|
|||
The resulting ``_annotation`` attribute might not match the one given here and might |
|||
be transformed in order to be easier to call from the ``transform`` asynchronous function |
|||
of a command parameter. |
|||
""" |
|||
|
|||
(inner, default) = get_supported_annotation(annotation) |
|||
type = inner.type() |
|||
if default is MISSING: |
|||
default = parameter.default |
|||
if default is parameter.empty: |
|||
default = MISSING |
|||
|
|||
# Verify validity of the default parameter |
|||
if default is not MISSING: |
|||
valid_types: Tuple[Any, ...] = ALLOWED_DEFAULTS.get(type, (NoneType,)) |
|||
if not isinstance(default, valid_types): |
|||
raise TypeError(f'invalid default parameter type given ({default.__class__}), expected {valid_types}') |
|||
|
|||
result = CommandParameter( |
|||
type=type, |
|||
_annotation=inner, |
|||
default=default, |
|||
required=default is MISSING, |
|||
name=parameter.name, |
|||
) |
|||
|
|||
# These methods should be duck typed |
|||
if type in (AppCommandOptionType.number, AppCommandOptionType.integer): |
|||
result.min_value = inner.min_value() |
|||
result.max_value = inner.max_value() |
|||
|
|||
if type is AppCommandOptionType.channel: |
|||
result.channel_types = inner.channel_types() |
|||
|
|||
if parameter.kind in (parameter.POSITIONAL_ONLY, parameter.VAR_KEYWORD, parameter.VAR_POSITIONAL): |
|||
raise TypeError(f'unsupported parameter kind in callback: {parameter.kind!s}') |
|||
|
|||
return result |
|||
Loading…
Reference in new issue