diff --git a/docs/ext/commands/commands.rst b/docs/ext/commands/commands.rst index f268c7ad7..cc591156b 100644 --- a/docs/ext/commands/commands.rst +++ b/docs/ext/commands/commands.rst @@ -281,6 +281,64 @@ fine tuning the converter. An example of this is actually in the library, :class If a converter fails to convert an argument to its designated target type, the :exc:`.BadArgument` exception must be raised. +Inline Advanced Converters ++++++++++++++++++++++++++++++ + +If we don't want to inherit from :class:`~ext.commands.Converter`, we can still provide a converter that has the +advanced functionalities of an advanced converter and save us from specifying two types. + +For example, a common idiom would be to have a class and a converter for that class: + +.. code-block:: python3 + + class JoinDistance: + def __init__(self, joined, created): + self.joined = joined + self.created = created + + @property + def delta(self): + return self.joined - self.created + + class JoinDistanceConverter(commands.MemberConverter): + async def convert(self, ctx, argument): + member = await super().convert(ctx, argument) + return JoinDistance(member.joined_at, member.created_at) + + @bot.command() + async def delta(ctx, *, member: JoinDistanceConverter): + is_new = member.delta.days < 100 + if is_new: + await ctx.send("Hey you're pretty new!") + else: + await ctx.send("Hm you're not so new.") + +This can get tedious, so an inline advanced converter is possible through a ``classmethod`` inside the type: + +.. code-block:: python3 + + class JoinDistance: + def __init__(self, joined, created): + self.joined = joined + self.created = created + + @classmethod + async def convert(cls, ctx, argument): + member = await commands.MemberConverter().convert(ctx, argument) + return cls(member.joined_at, member.created_at) + + @property + def delta(self): + return self.joined - self.created + + @bot.command() + async def delta(ctx, *, member: JoinDistance): + is_new = member.delta.days < 100 + if is_new: + await ctx.send("Hey you're pretty new!") + else: + await ctx.send("Hm you're not so new.") + Discord Converters ++++++++++++++++++++ @@ -359,64 +417,6 @@ By providing the converter it allows us to use them as building blocks for anoth """Tells you a member's roles.""" await ctx.send('I see the following roles: ' + ', '.join(member)) -Inline Advanced Converters -+++++++++++++++++++++++++++++ - -If we don't want to inherit from :class:`~ext.commands.Converter`, we can still provide a converter that has the -advanced functionalities of an advanced converter and save us from specifying two types. - -For example, a common idiom would be to have a class and a converter for that class: - -.. code-block:: python3 - - class JoinDistance: - def __init__(self, joined, created): - self.joined = joined - self.created = created - - @property - def delta(self): - return self.joined - self.created - - class JoinDistanceConverter(commands.MemberConverter): - async def convert(self, ctx, argument): - member = await super().convert(ctx, argument) - return JoinDistance(member.joined_at, member.created_at) - - @bot.command() - async def delta(ctx, *, member: JoinDistanceConverter): - is_new = member.delta.days < 100 - if is_new: - await ctx.send("Hey you're pretty new!") - else: - await ctx.send("Hm you're not so new.") - -This can get tedious, so an inline advanced converter is possible through a ``classmethod`` inside the type: - -.. code-block:: python3 - - class JoinDistance: - def __init__(self, joined, created): - self.joined = joined - self.created = created - - @classmethod - async def convert(cls, ctx, argument): - member = await commands.MemberConverter().convert(ctx, argument) - return cls(member.joined_at, member.created_at) - - @property - def delta(self): - return self.joined - self.created - - @bot.command() - async def delta(ctx, *, member: JoinDistance): - is_new = member.delta.days < 100 - if is_new: - await ctx.send("Hey you're pretty new!") - else: - await ctx.send("Hm you're not so new.") - .. _ext_commands_special_converters: Special Converters