James Hilton-Balfe
3 years ago
committed by
GitHub
GitHub
11 changed files with 435 additions and 148 deletions
@ -0,0 +1,246 @@ |
|||
""" |
|||
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 operator import attrgetter |
|||
from typing import TYPE_CHECKING, Any, Literal, Optional, OrderedDict, Union |
|||
|
|||
from discord.utils import MISSING, maybe_coroutine |
|||
|
|||
from . import converter |
|||
from .errors import MissingRequiredArgument |
|||
|
|||
if TYPE_CHECKING: |
|||
from typing_extensions import Self |
|||
|
|||
from discord import Guild, Member, TextChannel, User |
|||
|
|||
from .context import Context |
|||
|
|||
__all__ = ( |
|||
'Parameter', |
|||
'parameter', |
|||
'param', |
|||
'Author', |
|||
'CurrentChannel', |
|||
'CurrentGuild', |
|||
) |
|||
|
|||
|
|||
ParamKinds = Union[ |
|||
Literal[inspect.Parameter.POSITIONAL_ONLY], |
|||
Literal[inspect.Parameter.POSITIONAL_OR_KEYWORD], |
|||
Literal[inspect.Parameter.VAR_POSITIONAL], |
|||
Literal[inspect.Parameter.KEYWORD_ONLY], |
|||
Literal[inspect.Parameter.VAR_KEYWORD], |
|||
] |
|||
|
|||
empty: Any = inspect.Parameter.empty |
|||
|
|||
|
|||
def _gen_property(name: str) -> property: |
|||
attr = f'_{name}' |
|||
return property( |
|||
attrgetter(attr), |
|||
lambda self, value: setattr(self, attr, value), |
|||
doc="The parameter's {name}.", |
|||
) |
|||
|
|||
|
|||
class Parameter(inspect.Parameter): |
|||
r"""A class that stores information on a :class:`Command`\'s parameter. |
|||
This is a subclass of :class:`inspect.Parameter`. |
|||
|
|||
.. versionadded:: 2.0 |
|||
""" |
|||
|
|||
__slots__ = ('_displayed_default',) |
|||
|
|||
def __init__( |
|||
self, |
|||
name: str, |
|||
kind: ParamKinds, |
|||
default: Any = empty, |
|||
annotation: Any = empty, |
|||
displayed_default: str = empty, |
|||
) -> None: |
|||
super().__init__(name=name, kind=kind, default=default, annotation=annotation) |
|||
self._name = name |
|||
self._kind = kind |
|||
self._default = default |
|||
self._annotation = annotation |
|||
self._displayed_default = displayed_default |
|||
|
|||
def replace( |
|||
self, |
|||
*, |
|||
name: str = MISSING, # MISSING here cause empty is valid |
|||
kind: ParamKinds = MISSING, |
|||
default: Any = MISSING, |
|||
annotation: Any = MISSING, |
|||
displayed_default: Any = MISSING, |
|||
) -> Self: |
|||
if name is MISSING: |
|||
name = self._name |
|||
if kind is MISSING: |
|||
kind = self._kind # type: ignore # this assignment is actually safe |
|||
if default is MISSING: |
|||
default = self._default |
|||
if annotation is MISSING: |
|||
annotation = self._annotation |
|||
if displayed_default is MISSING: |
|||
displayed_default = self._displayed_default |
|||
|
|||
return self.__class__( |
|||
name=name, |
|||
kind=kind, |
|||
default=default, |
|||
annotation=annotation, |
|||
displayed_default=displayed_default, |
|||
) |
|||
|
|||
if not TYPE_CHECKING: # this is to prevent anything breaking if inspect internals change |
|||
name = _gen_property('name') |
|||
kind = _gen_property('kind') |
|||
default = _gen_property('default') |
|||
annotation = _gen_property('annotation') |
|||
|
|||
@property |
|||
def required(self) -> bool: |
|||
""":class:`bool`: Whether this parameter is required.""" |
|||
return self.default is empty |
|||
|
|||
@property |
|||
def converter(self) -> Any: |
|||
"""The converter that should be used for this parameter.""" |
|||
if self.annotation is empty: |
|||
return type(self.default) if self.default not in (empty, None) else str |
|||
|
|||
return self.annotation |
|||
|
|||
@property |
|||
def displayed_default(self) -> Optional[str]: |
|||
"""Optional[:class:`str`]: The displayed default in :class:`Command.signature`.""" |
|||
if self._displayed_default is not empty: |
|||
return self._displayed_default |
|||
|
|||
return None if self.required else str(self.default) |
|||
|
|||
async def get_default(self, ctx: Context) -> Any: |
|||
"""|coro| |
|||
|
|||
Gets this parameter's default value. |
|||
|
|||
Parameters |
|||
---------- |
|||
ctx: :class:`Context` |
|||
The invocation context that is used to get the default argument. |
|||
""" |
|||
# pre-condition: required is False |
|||
if callable(self.default): |
|||
return await maybe_coroutine(self.default, ctx) # type: ignore |
|||
return self.default |
|||
|
|||
|
|||
def parameter( |
|||
*, |
|||
converter: Any = empty, |
|||
default: Any = empty, |
|||
displayed_default: str = empty, |
|||
) -> Any: |
|||
r"""parameter(\*, converter=..., default=..., displayed_default=...) |
|||
|
|||
A way to assign custom metadata for a :class:`Command`\'s parameter. |
|||
|
|||
.. versionadded:: 2.0 |
|||
|
|||
Examples |
|||
-------- |
|||
A custom default can be used to have late binding behaviour. |
|||
|
|||
.. code-block:: python3 |
|||
|
|||
@bot.command() |
|||
async def wave(to: discord.User = commands.parameter(default=lambda ctx: ctx.author)): |
|||
await ctx.send(f'Hello {to.mention} :wave:') |
|||
|
|||
Parameters |
|||
---------- |
|||
converter: Any |
|||
The converter to use for this parameter, this replaces the annotation at runtime which is transparent to type checkers. |
|||
default: Any |
|||
The default value for the parameter, if this is a :term:`callable` or a |coroutine_link|_ it is called with a |
|||
positional :class:`Context` argument. |
|||
displayed_default: :class:`str` |
|||
The displayed default in :attr:`Command.signature`. |
|||
""" |
|||
return Parameter( |
|||
name='empty', |
|||
kind=inspect.Parameter.POSITIONAL_OR_KEYWORD, |
|||
annotation=converter, |
|||
default=default, |
|||
displayed_default=displayed_default, |
|||
) |
|||
|
|||
|
|||
param = parameter |
|||
r"""param(\*, converter=..., default=..., displayed_default=...) |
|||
|
|||
An alias for :func:`parameter`. |
|||
|
|||
.. versionadded:: 2.0 |
|||
""" |
|||
|
|||
# some handy defaults |
|||
Author: Union[Member, User] = parameter( |
|||
default=attrgetter('author'), |
|||
displayed_default='<you>', |
|||
converter=Union[converter.MemberConverter, converter.UserConverter], |
|||
) |
|||
|
|||
CurrentChannel: TextChannel = parameter( |
|||
default=attrgetter('channel'), |
|||
displayed_default='<this channel>', |
|||
converter=converter.TextChannelConverter, |
|||
) |
|||
|
|||
|
|||
def default_guild(ctx: Context) -> Guild: |
|||
if ctx.guild is not None: |
|||
return ctx.guild |
|||
raise MissingRequiredArgument(ctx.current_parameter) # type: ignore # this is never going to be None |
|||
|
|||
|
|||
CurrentGuild: Guild = parameter( |
|||
default=default_guild, |
|||
displayed_default='<this server>', |
|||
converter=converter.GuildConverter, |
|||
) |
|||
|
|||
|
|||
class Signature(inspect.Signature): |
|||
_parameter_cls = Parameter |
|||
parameters: OrderedDict[str, Parameter] |
|||
Loading…
Reference in new issue