コマンド

コマンド拡張の最も魅力的な機能の一つは、簡単にコマンドが定義でき、かつそのコマンドを好きなようにネスト状にして、豊富なサブコマンドを用意することができる点です。

コマンドは、Pythonの関数と関連付けすることによって定義され、同様のシグネチャを使用してユーザーに呼び出されます。

例えば、指定されたコマンド定義を使うと次のようになります。

@bot.command()
async def foo(ctx, arg):
    await ctx.send(arg)

Prefixを ($) としたとすると、このコマンドは次の用に実行できます。

$foo abc

コマンドには、少なくとも Context を渡すための引数 ctx が必要です。

コマンドを登録するには二通りの方法があります。一つ目は Bot.command() を使用する方法で、二つ目が command() デコレータを使用して Bot.add_command() でインスタンスにコマンドを追加していく方法です。

本質的に、これら2つは同等になります:

from discord.ext import commands

bot = commands.Bot(command_prefix='$')

@bot.command()
async def test(ctx):
    pass

# or:

@commands.command()
async def test(ctx):
    pass

bot.add_command(test)

Bot.command() が簡単かつ理解がしやすいので、ドキュメント上ではこちらを使っています。

Command のコンストラクタの引数はデコレータに渡すことで利用できます。例えば、コマンドの名前を関数以外のものへと変更したい場合は以下のように簡単に設定することができます。

@bot.command(name='list')
async def _list(ctx, arg):
    pass

パラメーター

Pythonの関数定義によって、同時にコマンドを定義するので、関数のパラメーターを設定することにより、コマンドの引数受け渡し動作も定義することができます。

特定のパラメータタイプはユーザーサイドで異なる動作を行い、そしてほとんどの形式のパラメータタイプがサポートされています。

位置引数

最も基本的な引数は位置パラメーターです。与えられた値をそのまま渡します。

@bot.command()
async def test(ctx, arg):
    await ctx.send(arg)

Botの使用者側は、通常の文字列を渡すだけで位置引数に値を渡すことができます。

../../_images/positional1.png

間に空白を含む文字列を渡す場合は、文字列を引用符で囲む必要があります。

../../_images/positional2.png

引用符を用いなかった場合、最初の文字列のみが渡されます。

../../_images/positional3.png

位置引数は、Pythonの引数と同じものなので、好きなだけ設定することが可能です。

@bot.command()
async def test(ctx, arg1, arg2):
    await ctx.send('You passed {} and {}'.format(arg1, arg2))

可変長引数

場合によっては、可変長のパラメーターを設定したい場合もあるでしょう。このライブラリはPythonの可変長パラメーターと同様にこれをサポートしています。

@bot.command()
async def test(ctx, *args):
    await ctx.send('{} arguments: {}'.format(len(args), ', '.join(args)))

これによって一つ、あるいは複数の引数を受け取ることができます。ただし、引数を渡す際の挙動は位置引数と同様のため、複数の単語を含む文字列は引用符で囲む必要があります。

例えば、Bot側ではこのように動きます。

../../_images/variable1.png

複数単語の文字列を渡す際は、引用符で囲んでください。

../../_images/variable2.png

Pythonの振る舞いと同様に、ユーザーは引数なしの状態を技術的に渡すことができます。

../../_images/variable3.png

Since the args variable is a tuple, you can do anything you would usually do with one.

キーワード引数

引数の構文解析を自分で行う場合や、複数単語の入力を引用符で囲む必要のないようにしたい場合は、渡された値を単一の引数として受け取るようにライブラリに求めることができます。以下のコードのようにキーワード引数のみを使用することでこれが可能になります。

@bot.command()
async def test(ctx, *, arg):
    await ctx.send(arg)

警告

解析が曖昧になるため、一つのキーワードのみの引数しか扱えません。

Bot側では、スペースを含む入力を引用符で囲む必要がありません:

../../_images/keyword1.png

引用符で囲んだ場合、消えずに残るので注意してください:

../../_images/keyword2.png

通常、キーワード引数は利便性のために空白文字で分割されます。この動作はデコレータの引数として Command.rest_is_raw を使うことで切り替えることが可能です。

呼び出しコンテクスト

前述の通り、すべてのコマンドは必ず Context と呼ばれるパラメータを受け取らなければいけません。

このパラメータにより、「呼び出しコンテクスト」というものにアクセスできます。言うなればコマンドがどのように実行されたのかを知るのに必要な基本的情報です。これにはたくさんの有用な情報が含まれています。

コンテクストは abc.Messageable インタフェースを実装しているため、 abc.Messageable 上でできることは Context 上でも行うことが可能です。

コンバータ

Botの引数を関数のパラメータとして設定するのは、Botのコマンドインタフェースを定義する第一歩です。引数を実際に扱うには、大抵の場合、データを目的の型へとと変換する必要があります。私達はこれを Converters と呼んでいます。

コンバータにはいくつかの種類があります:

  • 引数を一つのパラメータとして受け取り、異なる型として返す、通常の呼び出し可能オブジェクト。

    • これらにはあなたの作った関数、 boolint といったものまで含まれます。

  • Converter を継承したカスタムクラス。

基本的なコンバーター

基本的なコンバーターは、中核をなすものであり、受け取った引数を別のものへと変換します。

例えば、二つの値を加算したい場合、コンバーターを指定することにより、受け取った値を整数型へ変換するように要求できます。

@bot.command()
async def add(ctx, a: int, b: int):
    await ctx.send(a + b)

コンバーターの指定には関数アノテーションというもの用います。これは PEP 3107 にて追加された Python 3 にのみ実装されている機能です。

これは、文字列をすべて大文字に変換する関数などといった、任意の呼び出し可能関数でも動作します。

def to_upper(argument):
    return argument.upper()

@bot.command()
async def up(ctx, *, content: to_upper):
    await ctx.send(content)

論理型

Unlike the other basic converters, the bool converter is treated slightly different. Instead of casting directly to the bool type, which would result in any non-empty argument returning True, it instead evaluates the argument as True or False based on its given content:

if lowered in ('yes', 'y', 'true', 't', '1', 'enable', 'on'):
    return True
elif lowered in ('no', 'n', 'false', 'f', '0', 'disable', 'off'):
    return False

応用的なコンバータ

場合によっては、基本的なコンバータを動かすのに必要な情報が不足していることがあります。例えば、実行されたコマンドの Message から情報を取得したい場合や、非同期処理を行いたい場合です。

そういった用途のために、このライブラリは Converter インタフェースを提供します。これによって Context にアクセスが可能になり、また、呼び出し可能関数を非同期にもできるようになります。このインタフェースを使用して、カスタムコンバーターを定義したい場合は Converter.convert() をオーバーライドしてください。

コンバーターの例

import random

class Slapper(commands.Converter):
    async def convert(self, ctx, argument):
        to_slap = random.choice(ctx.guild.members)
        return '{0.author} slapped {1} because *{2}*'.format(ctx, to_slap, argument)

@bot.command()
async def slap(ctx, *, reason: Slapper):
    await ctx.send(reason)

コンバーターはインスタンス化されていなくても構いません。以下の例の二つのは同じ処理になります。

@bot.command()
async def slap(ctx, *, reason: Slapper):
    await ctx.send(reason)

# is the same as...

@bot.command()
async def slap(ctx, *, reason: Slapper()):
    await ctx.send(reason)

コンバーターをインスタンス化する可能性がある場合、コンバーターの調整を行うために __init__ で何かしらの状態を設定することが出来ます。この例としてライブラリに実際に存在する clean_content があります。

@bot.command()
async def clean(ctx, *, content: commands.clean_content):
    await ctx.send(content)

# or for fine-tuning

@bot.command()
async def clean(ctx, *, content: commands.clean_content(use_nicknames=False)):
    await ctx.send(content)

コンバーターが渡された引数を指定の型に変換できなかった場合は BadArgument を発生させてください。

埋込み型の応用的なコンバーター

Converter を継承したくない場合のために、応用的なコンバータの高度な機能を備えたコンバータを提供しています。これを使用することで2つのクラスを作成する必要がなくなります。

例えば、一般的な書き方だと、クラスとそのクラスへのコンバーターを定義します:

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:

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 コンバーター

Discordモデル を使用して作業を行うのは、コマンドを定義する際には一般的なことです。そのため、このライブラリでは簡単に作業が行えるようになっています。

例えば、 Member を受け取るには、これをコンバーターとして渡すだけです。

@bot.command()
async def joined(ctx, *, member: discord.Member):
    await ctx.send('{0} joined on {0.joined_at}'.format(member))

このコマンドが実行されると、与えられた文字列を Member に変換して、それを関数のパラメーターとして渡します。これは文字列がメンション、ID、ニックネーム、ユーザー名 + Discordタグ、または普通のユーザー名かどうかをチェックすることで機能しています。デフォルトで定義されているコンバーターは、できるだけ簡単に使えるように作られています。

Discordモデルの多くがコンバーターとして動作します。

これらをコンバーターとして設定すると、引数を指定した型へとインテリジェントに変換します。

これらは 応用的なコンバータ インタフェースによって実装されています。コンバーターとクラスの関係は以下の通りです。

コンバーターを継承することで、他のコンバーターの一部として使うことができます:

class MemberRoles(commands.MemberConverter):
    async def convert(self, ctx, argument):
        member = await super().convert(ctx, argument)
        return [role.name for role in member.roles[1:]] # Remove everyone role!

@bot.command()
async def roles(ctx, *, member: MemberRoles):
    """Tells you a member's roles."""
    await ctx.send('I see the following roles: ' + ', '.join(member))

特殊なコンバーター

コマンド拡張機能は一般的な線形解析を超える、より高度で複雑なユースケースに対応するため、特殊なコンバータをサポートしています。これらのコンバータは、簡単な方法でコマンドに更に容易で動的な文法の導入を可能にします。

typing.Union

typing.Union はコマンドが単数の型の代わりに、複数の特定の型を取り込める特殊な型ヒントです。例えば:

import typing

@bot.command()
async def union(ctx, what: typing.Union[discord.TextChannel, discord.Member]):
    await ctx.send(what)

what パラメータには discord.TextChannel コンバーターか discord.Member コンバーターのいずれかが用いられます。これは左から右の順で変換できるか試行することになります。最初に渡された値を discord.TextChannel へ変換しようと試み、失敗した場合は discord.Member に変換しようとします。すべてのコンバーターで失敗した場合は BadUnionArgument というエラーが発生します。

以前に説明した有効なコンバーターは、すべて typing.Union にわたすことが可能です。

typing.Optional

typing.Optional は「後方参照」のような動作をする特殊な型ヒントです。コンバーターが指定された型へのパースに失敗した場合、パーサーは代わりに None または指定されたデフォルト値をパラメータに渡したあと、そのパラメータをスキップします。次のパラメータまたはコンバータがあれば、そちらに進みます。

次の例をみてください:

import typing

@bot.command()
async def bottles(ctx, amount: typing.Optional[int] = 99, *, liquid="beer"):
    await ctx.send('{} bottles of {} on the wall!'.format(amount, liquid))
../../_images/optional1.png

この例では引数を int に変換することができなかったので、デフォルト値である 99 を代入し、パーサーは処理を続行しています。この場合、先程の変換に失敗した引数は liquid パラメータに渡されます。

注釈

このコンバーターは位置パラメータでのみ動作し、可変長パラメータやキーワードパラメータでは機能しません。

Greedy

Greedy コンバータは引数にリストが適用される以外は typing.Optional を一般化したものです。簡単に言うと、与えられた引数を変換ができなくなるまで指定の型に変換しようと試みます。

次の例をみてください:

@bot.command()
async def slap(ctx, members: commands.Greedy[discord.Member], *, reason='no reason'):
    slapped = ", ".join(x.name for x in members)
    await ctx.send('{} just got slapped for {}'.format(slapped, reason))

これが呼び出されると、任意の数のメンバーを渡すことができます:

../../_images/greedy1.png

The type passed when using this converter depends on the parameter type that it is being attached to:

  • Positional parameter types will receive either the default parameter or a list of the converted values.

  • Variable parameter types will be a tuple as usual.

  • Keyword-only parameter types will be the same as if Greedy was not passed at all.

Greedy parameters can also be made optional by specifying an optional value.

When mixed with the typing.Optional converter you can provide simple and expressive command invocation syntaxes:

import typing

@bot.command()
async def ban(ctx, members: commands.Greedy[discord.Member],
                   delete_days: typing.Optional[int] = 0, *,
                   reason: str):
    """Mass bans members with an optional delete_days parameter"""
    for member in members:
        await member.ban(delete_message_days=delete_days, reason=reason)

This command can be invoked any of the following ways:

$ban @Member @Member2 spam bot
$ban @Member @Member2 7 spam bot
$ban @Member spam

警告

The usage of Greedy and typing.Optional are powerful and useful, however as a price, they open you up to some parsing ambiguities that might surprise some people.

For example, a signature expecting a typing.Optional of a discord.Member followed by a int could catch a member named after a number due to the different ways a MemberConverter decides to fetch members. You should take care to not introduce unintended parsing ambiguities in your code. One technique would be to clamp down the expected syntaxes allowed through custom converters or reordering the parameters to minimise clashes.

To help aid with some parsing ambiguities, str, None, typing.Optional and Greedy are forbidden as parameters for the Greedy converter.

エラーハンドリング

When our commands fail to parse we will, by default, receive a noisy error in stderr of our console that tells us that an error has happened and has been silently ignored.

In order to handle our errors, we must use something called an error handler. There is a global error handler, called on_command_error() which works like any other event in the イベントリファレンス. This global error handler is called for every error reached.

Most of the time however, we want to handle an error local to the command itself. Luckily, commands come with local error handlers that allow us to do just that. First we decorate an error handler function with Command.error():

@bot.command()
async def info(ctx, *, member: discord.Member):
    """Tells you some info about the member."""
    fmt = '{0} joined on {0.joined_at} and has {1} roles.'
    await ctx.send(fmt.format(member, len(member.roles)))

@info.error
async def info_error(ctx, error):
    if isinstance(error, commands.BadArgument):
        await ctx.send('I could not find that member...')

The first parameter of the error handler is the Context while the second one is an exception that is derived from CommandError. A list of errors is found in the Exceptions page of the documentation.

チェック

コマンドをユーザーに使ってほしくない場合などがあります。例えば、使用者が権限を持っていない場合や、Botをブロックしている場合などです。コマンド拡張ではこのような機能を Checks と呼び、完全にサポートしています。

A check is a basic predicate that can take in a Context as its sole parameter. Within it, you have the following options:

  • Return True to signal that the person can run the command.

  • Return False to signal that the person cannot run the command.

  • Raise a CommandError derived exception to signal the person cannot run the command.

    • This allows you to have custom error messages for you to handle in the error handlers.

To register a check for a command, we would have two ways of doing so. The first is using the check() decorator. For example:

async def is_owner(ctx):
    return ctx.author.id == 316026178463072268

@bot.command(name='eval')
@commands.check(is_owner)
async def _eval(ctx, *, code):
    """A bad example of an eval command"""
    await ctx.send(eval(code))

This would only evaluate the command if the function is_owner returns True. Sometimes we re-use a check often and want to split it into its own decorator. To do that we can just add another level of depth:

def is_owner():
    async def predicate(ctx):
        return ctx.author.id == 316026178463072268
    return commands.check(predicate)

@bot.command(name='eval')
@is_owner()
async def _eval(ctx, *, code):
    """A bad example of an eval command"""
    await ctx.send(eval(code))

Since an owner check is so common, the library provides it for you (is_owner()):

@bot.command(name='eval')
@commands.is_owner()
async def _eval(ctx, *, code):
    """A bad example of an eval command"""
    await ctx.send(eval(code))

When multiple checks are specified, all of them must be True:

def is_in_guild(guild_id):
    async def predicate(ctx):
        return ctx.guild and ctx.guild.id == guild_id
    return commands.check(predicate)

@bot.command()
@commands.is_owner()
@is_in_guild(41771983423143937)
async def secretguilddata(ctx):
    """super secret stuff"""
    await ctx.send('secret stuff')

If any of those checks fail in the example above, then the command will not be run.

When an error happens, the error is propagated to the error handlers. If you do not raise a custom CommandError derived exception, then it will get wrapped up into a CheckFailure exception as so:

@bot.command()
@commands.is_owner()
@is_in_guild(41771983423143937)
async def secretguilddata(ctx):
    """super secret stuff"""
    await ctx.send('secret stuff')

@secretguilddata.error
async def secretguilddata_error(ctx, error):
    if isinstance(error, commands.CheckFailure):
        await ctx.send('nothing to see here comrade.')

If you want a more robust error system, you can derive from the exception and raise it instead of returning False:

class NoPrivateMessages(commands.CheckFailure):
    pass

def guild_only():
    async def predicate(ctx):
        if ctx.guild is None:
            raise NoPrivateMessages('Hey no DMs!')
        return True
    return commands.check(predicate)

@guild_only()
async def test(ctx):
    await ctx.send('Hey this is not a DM! Nice.')

@test.error
async def test_error(ctx, error):
    if isinstance(error, NoPrivateMessages):
        await ctx.send(error)

注釈

Since having a guild_only decorator is pretty common, it comes built-in via guild_only().

グローバルチェック

Sometimes we want to apply a check to every command, not just certain commands. The library supports this as well using the global check concept.

Global checks work similarly to regular checks except they are registered with the Bot.check() decorator.

For example, to block all DMs we could do the following:

@bot.check
async def globally_block_dms(ctx):
    return ctx.guild is not None

警告

Be careful on how you write your global checks, as it could also lock you out of your own bot.