APIリファレンス¶

この項目ではdiscord.pyのAPIが持つコマンド拡張モジュールについて解説します。

Bot¶

Methods

defadd_check
asyncadd_cog
defadd_command
defadd_listener
defadd_view
@after_invoke
asyncapplication_info
asyncbefore_identify_hook
@before_invoke
asyncchange_presence
@check
@check_once
defclear
asyncclose
@command
asyncconnect
asynccreate_dm
asynccreate_guild
asyncdelete_invite
@event
asyncfetch_channel
asyncfetch_guild
async forfetch_guilds
asyncfetch_invite
asyncfetch_premium_sticker_packs
asyncfetch_stage_instance
asyncfetch_sticker
asyncfetch_template
asyncfetch_user
asyncfetch_webhook
asyncfetch_widget
defget_all_channels
defget_all_members
defget_channel
defget_cog
defget_command
asyncget_context
defget_emoji
defget_guild
defget_partial_messageable
asyncget_prefix
defget_stage_instance
defget_sticker
defget_user
@group
@hybrid_command
@hybrid_group
asyncinvoke
defis_closed
asyncis_owner
defis_ready
defis_ws_ratelimited
@listen
asyncload_extension
asynclogin
asyncon_command_error
asyncon_error
asyncprocess_commands
asyncreload_extension
defremove_check
asyncremove_cog
defremove_command
defremove_listener
defrun
asyncsetup_hook
asyncstart
asyncunload_extension
asyncwait_for
asyncwait_until_ready
defwalk_commands

class discord.ext.commands.Bot(command_prefix, *, help_command=<default-help-command>, tree_cls=<class 'discord.app_commands.tree.CommandTree'>, description=None, intents, **options)¶

Discord Botを表します。

このクラスは discord.Client のサブクラスのため、 discord.Client でできることと同じことをこのBotで行うことができます。

また、 GroupMixin も継承しており、コマンド管理の機能も使用可能です。

discord.Client とは異なり、このクラスでは CommandTree を手動で設定する必要はなく、クラスのインスタンスを作成する際に自動的に設定されます。

async with x: 非同期的にボットを初期化し自動でクリーンアップします。

バージョン 2.0 で追加.

command_prefix¶

コマンドの接頭詞とは、コマンドの判定のためにメッセージの先頭に付けなければならないものです。接頭詞には、そのまま接頭詞として使用する文字列、または discord.Message を二つ目の引数として受け取り、接頭詞を返す呼び出し可能な関数を渡すことができます。これは「動的な」接頭詞の実装を容易にするためです。

接頭詞に空文字列を渡せば、接頭詞なしでコマンドの呼び出しができます。これはDM上では有用ですが、サーバーでは意図せずコマンドを呼び出してしまうことに繋がるため、避けるべきです。

コマンドの接頭辞を文字列のイテラブルで指定することもできます。この場合、接頭辞を複数回チェックし、最初にマッチしたものを呼び出し時の接頭辞とします。使用された接頭辞は、 Context.prefix で取得することができます。

注釈

複数の接頭辞を渡すとき、後の接頭辞にマッチする接頭辞を、それよりも前に渡さないよう注意してください。たとえば、接頭辞が ('!', '!?') のとき、 !? の接頭辞は、その前のものが !? で始まるメッセージにマッチするため、どのメッセージにも反応しません。これは空文字列を渡すときは特に重要で、その後の接頭辞は無視されるため、空文字列は最後に置かないといけません。

case_insensitive¶

コマンド名で大文字と小文字を区別するかどうか。デフォルトではFalseです。この属性はグループに適用されません。もしグループコマンドも大文字と小文字を区別したくない場合、すべてのグループで設定しなければなりません。

型: bool

description¶

デフォルトのヘルプメッセージの最初に表示される文字列。

型: str

help_command¶

使用するヘルプコマンドの実装。これは、実行時でも動的に設定できます。ヘルプコマンドを削除するには、None を引数に入れてください。ヘルプコマンドの実装の詳細については、ヘルプコマンドを参照してください。

型: Optional[HelpCommand]

owner_id¶

Botを所有するユーザーのID。もし設定されていない場合、 is_owner() が呼び出されたとき、 application_info() を用いて自動的に取得します。

型: Optional[int]

owner_ids¶

Botを所有するユーザーのID群。これは owner_id と同様のものです。もしこの変数が設定されておらず、Botのアプリケーションがチームに帰属する場合、自動的に application_info() から取得されます。パフォーマンス上の問題により、このID群を操作するにあたって set を使うことが推奨されています。 owner_id と owner_ids は、どちらか片方しか設定することができません。

バージョン 1.3 で追加.

型: Optional[Collection[int]]

strip_after_prefix¶

接頭辞の後の空白を除去するかどうか。 command_prefix が ! に設定されているときに、これが有効だと ! hello 、 !hello 両方が動作するようになります。デフォルトは False です。

バージョン 1.7 で追加.

型: bool

tree_cls¶

使用するアプリケーションコマンドツリーの型を指定します。デフォルトは CommandTree です。

バージョン 2.0 で追加.

型: Type[CommandTree]

@after_invoke¶

コルーチンを、実行後に呼び出すフックとして登録するデコレータ。

実行後呼び出しフックは、コマンドが呼び出された直後に呼び出されます。これにより、データベース接続をクリーンアップしたり、必要なクリーンアップを行うための便利な機能になります。

この実行後呼び出しフックは、 Context を単独の引数として取ります。

注釈

before_invoke()と似て、チェックと引数展開が成功しない限り、これが呼び出されることはありません。ただし、このフックは、コマンドのエラー発生にかかわらず(例えば、CommandInvokeErrorなど)、常時呼び出されます。そのため、クリーンアップするのに最適です。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行後呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@before_invoke¶

渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。

実行前呼び出しフックは、コマンドが呼び出される前に呼び出されます。これにより、データベース接続のセットアップや、必要なセットアップを行うにあたって便利です。

この実行前呼び出しフックは、 Context を単独の引数として取ります。

注釈

before_invoke() と after_invoke() は、すべてのチェックと引数解析が、例外を送出せずに渡された場合にのみ呼び出されます。何らかのチェックまたは引数の解析に失敗した場合、これらのフックは呼び出されません。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行前呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@check¶

ボットにグローバルチェックを追加するデコレーター。

このグローバルチェックは、コマンドごとに適用される check() と似ていますが、コマンドチェックが検証される前に実行され、かつボットが持つすべてのコマンドに適用される点で異なります。

注釈

この関数は、通常の関数かコルーチン、どちらでも成り得ます。

check() コマンドと同様、 Context 型の単一のパラメータを取り、 CommandError から継承された例外のみを投げることができます。

サンプル

@bot.check
def check_commands(ctx):
    return ctx.command.qualified_name in allowed_commands

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

@check_once¶

ボットに「一度だけ実行される」グローバルチェックを追加するデコレーター。

通常のグローバルチェックとは異なり、 invoke() の呼び出し毎に一度だけ実行されます。

通常のグローバルチェックは、コマンドが呼び出されるか Command.can_run() が呼び出されるたび、実行されます。しかしこのグローバルチェックはそれを迂回し、デフォルトのhelpコマンドの中であっても、たった一度だけ呼ばれます。

注釈

この関数を使用する場合、グループのサブコマンドに送信される Context は、 Bot.invoke() の呼び出しごとに一度だけ呼び出されるため、親コマンドの時にしかチェックされず、サブコマンドの時はチェックはされません。

注釈

この関数は、通常の関数かコルーチン、どちらでも成り得ます。

check() コマンドと同様、 Context 型の単一のパラメータを取り、 CommandError から継承された例外のみを投げることができます。

サンプル

@bot.check_once
def whitelist(ctx):
    return ctx.message.author.id in my_whitelist

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

@command(*args, **kwargs)¶

command() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
戻り値の型: Callable[..., Command]

@event¶

受け取るイベントを登録するデコレータ。

イベントの詳細については以下のドキュメントを参照してください。

イベントはコルーチンでなければいけません。違う場合は TypeError が発生します。

サンプル

@client.event
async def on_ready():
    print('Ready!')

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

例外: TypeError -- 渡された関数がコルーチンではない場合。

@group(*args, **kwargs)¶

group() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
戻り値の型: Callable[..., Group]

@hybrid_command(name=..., with_app_command=True, *args, **kwargs)¶

hybrid_command() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
戻り値の型: Callable[..., HybridCommand]

@hybrid_group(name=..., with_app_command=True, *args, **kwargs)¶

hybrid_group() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
戻り値の型: Callable[..., HybridGroup]

@listen(name=None)¶

関数を追加のイベントリスナーとして登録するデコレータ。基本的には異なる場所から複数のイベントを登録することに使われます（ on_ready() など）。

登録する関数はコルーチンでなければなりません。

サンプル

@bot.listen()
async def on_message(message):
    print('one')

# in some other file...

@bot.listen('on_message')
async def my_message(message):
    print('two')

の、oneとtwoの出力順は保証されません。

例外: TypeError -- 受け取る関数がコルーチンではない場合。

property activity¶

ログイン時に使用されるアクティビティ。

型: Optional[BaseActivity]

add_check(func, /, *, call_once=False)¶

ボットにグローバルチェックを追加します。

これは check() と check_once() のデコレータでない実装です。

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

参考

check() デコレータ

パラメータ

func -- グローバルチェックとして使用される関数。
call_once (bool) -- 関数が invoke() 呼び出しの時に、一度だけ呼び出されるべきかどうか。

await add_cog(cog, /, *, override=False, guild=..., guilds=...)¶

This function is a coroutine.

ボットに「コグ」を追加します。

コグは、イベントリスナーとコマンドを持つクラスです。

コグが app_commands.Group の場合、ボットの CommandTree にも追加されます。

注釈

Cog の、 cog_load() メソッド内で発生した例外は呼び出し元に伝播されます。

バージョン 2.0 で変更: 同じ名前のコグがすでに読み込まれている場合、ClientException が発生します。

バージョン 2.0 で変更: cog 引数は位置限定引数になりました。

バージョン 2.0 で変更: このメソッドは、coroutine です。

パラメータ

cog (Cog) -- ボットに登録するコグ。
override (bool) --
同じ名前のコグがすでに読み込まれているときに、例外を発生せず既存のものを削除するか。

バージョン 2.0 で追加.
guild (Optional[Snowflake]) --
コグがアプリケーションコマンドグループの場合、これはコググループが追加されるギルドになります。与えられない場合はグローバルコマンドになります。

バージョン 2.0 で追加.
guilds (List[Snowflake]) --
コグがアプリケーションコマンドグループの場合、これはコググループが追加されるギルドになります。与えられない場合はグローバルコマンドになります。 guild と併用することはできません。

バージョン 2.0 で追加.

例外

TypeError -- コグが Cog から継承されていない場合。
CommandError -- 読み込み中にエラーが発生した場合。
ClientException -- 同じ名前のコグがすでに読み込まれている場合。

add_command(command, /)¶

Command を内部のコマンドリストに追加します。

これは通常、呼び出されません。代わりに command() か group() のショートカットデコレータが使われます。

バージョン 1.4 で変更: 一般的な ClientException の代わりに、 CommandRegistrationError を送出します。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ

command (Command) -- 追加するコマンド。

例外

CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
TypeError -- 渡されたコマンドが、 Command のサブクラスでない場合。

add_listener(func, /, name=...)¶

listen() に対するデコレーターでない代替物です。

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ

func (coroutine) -- 呼び出される関数。
name (str) -- 受け取るイベントの名前。デフォルトでは func.__name__ です。

サンプル

async def on_ready(): pass
async def my_message(message): pass

bot.add_listener(on_ready)
bot.add_listener(my_message, 'on_message')

add_view(view, *, message_id=None)¶

View を永続的にインタラクションを受け取るために登録します。

このメソッドは、ビューがプログラムのライフサイクルを超えて存在するコンポーネントで構成されている場合に利用すべきです。

バージョン 2.0 で追加.

パラメータ

view (discord.ui.View) -- 実行するために登録するView
message_id (Optional[int]) -- Viewが添付されているメッセージID。これは、現在のViewの状態をメッセージ更新イベントの後に更新するのに使用されています。値が与えられていない場合はメッセージ更新のイベントはViewに伝わりません

例外

TypeError -- Viewが渡されなかった
ValueError -- Viewは永続的ではありません。永続的なViewにはタイムアウトがなく、すべてのコンポーネントには明示的に渡された custom_id があります

property allowed_mentions¶

許可されたメンションの設定。

バージョン 1.4 で追加.

型: Optional[AllowedMentions]

property application¶

クライアントのアプリケーション情報。

これは login() で取得され、その後更新されません。これによりゲートウェイ接続を行わずにapplication_idを取得できます。

もし login() の呼び出し前にアクセスされた場合は None です。

参考

application_info() API呼び出し

バージョン 2.0 で追加.

型: Optional[AppInfo]

property application_flags¶

クライアントのアプリケーションフラグ。

バージョン 2.0 で追加.

型: ApplicationFlags

property application_id¶

クライアントのアプリケーションID。

これが __init__ で渡されなかった場合、データを含むイベントが発生した際にゲートウェイを介して、または login() の後に取得されます。通常は on_connect() が呼び出された後です。

バージョン 2.0 で追加.

型: Optional[int]

await application_info()¶

This function is a coroutine.

Botのアプリケーション情報を取得します。

例外: HTTPException -- 情報の取得に失敗した場合。
戻り値: Botのアプリケーション情報。
戻り値の型: AppInfo

await before_identify_hook(shard_id, *, initial=False)¶

This function is a coroutine.

セッションをIDENTIFYingする前に、呼び出されるフック。これは、複数の IDENTIFYing クライアントの同期を、より詳細に制御したい場合に便利です。

デフォルトでは、5秒間スリープします。

バージョン 1.4 で追加.

パラメータ

shard_id (int) -- IDENTIFYを要求した時のシャードID。
initial (bool) -- この IDENTIFY が、最初の初期化時の IDENTIFY であるかどうか。

property cached_messages¶

接続済みクライアントがキャッシュしている、読み取り専用のメッセージのリスト。

バージョン 1.1 で追加.

型: Sequence[Message]

await change_presence(*, activity=None, status=None)¶

This function is a coroutine.

クライアントのステータスを変更します。

サンプル

game = discord.Game("with the API")
await client.change_presence(status=discord.Status.idle, activity=game)

バージョン 2.0 で変更: キーワード引数 afk は削除されました。

バージョン 2.0 で変更: この関数は InvalidArgument の代わりに TypeError を発生させます。

パラメータ

activity (Optional[BaseActivity]) -- 実行中のアクティビティ。何も実行していない場合は None です。
status (Optional[Status]) -- 変更するステータスを示します。 None の場合、 Status.online が使用されます。

例外

TypeError -- 引数 activity が適切な型でない場合。

clear()¶

Botの内部状態をクリアします。

これが実行されると、Botは「再実行」されたと見なされます。また、これにより is_closed() や is_ready() は False を返し、内部のキャッシュもクリアされます。

await close()¶

This function is a coroutine.

Discordとの接続を閉じます。

property cogs¶

コグ名をキーとし、コグを値とする読み取り専用のマッピング。

型: Mapping[str, Cog]

property commands¶

登録済みの、別名を含まないコマンドの集合。

型: Set[Command]

await connect(*, reconnect=True)¶

This function is a coroutine.

WebSocket接続を作成し、Discordからのメッセージを受け取れるようにします。これはイベントシステム全体とライブラリの様々な機能を実行するループです。WebSocket接続が終了するまで、制御は再開されません。

パラメータ

reconnect (bool) -- インターネットの障害やDiscord側の特定の障害が発生した際に再接続を試みるかどうか。不正な状態による特定の切断 (無効なシャーディングペイロードや不正なトークンなど) は処理されません。

例外

GatewayNotFound -- Discordに接続するゲートウェイが見つからない場合。通常、これが発生した場合は、Discord側のAPIの停止が考えられます。
ConnectionClosed -- WebSocket接続が終了した場合。

await create_dm(user)¶

This function is a coroutine.

このユーザーと DMChannel を作成します。

これは、ほとんどの人にとっては自動で行われるため、呼び出す必要はめったにありません。

バージョン 2.0 で追加.

パラメータ: user (Snowflake) -- DMを作成するユーザー。
戻り値: 作成されたチャンネル。
戻り値の型: DMChannel

await create_guild(*, name, icon=..., code=...)¶

This function is a coroutine.

Guild を作成します。

10以上のギルドに参加しているBotアカウントは、ギルドの作成ができません。

バージョン 2.0 で変更: name と icon パラメータはキーワード限定引数になりました。 region パラメータは削除されました。

バージョン 2.0 で変更: この関数は InvalidArgument の代わりに ValueError を発生させます。

パラメータ

name (str) -- ギルドの名前。
icon (Optional[bytes]) -- アイコンを表す bytes-like object 。引数の詳細については、 ClientUser.edit() を参照してください。
code (str) --
ギルドを作成するためのテンプレートコード。

バージョン 1.4 で追加.

例外

HTTPException -- ギルドの作成に失敗した場合。
ValueError -- アイコンの画像形式が無効だった場合。画像は、PNGまたはJPGである必要があります。

戻り値

作成されたGuild。Botのキャッシュに追加されるGuildとはまた別物です。

戻り値の型

Guild

await delete_invite(invite, /)¶

This function is a coroutine.

Invite や、招待のURL、IDを削除します。

これを行うには、関連付けられたGuildにて、 manage_channels が必要です。

バージョン 2.0 で変更: invite 引数は位置限定引数になりました。

パラメータ

invite (Union[Invite, str]) -- 取り消す招待。

例外

Forbidden -- 削除する権限がない場合。
NotFound -- 招待が無効または期限切れの場合。
HTTPException -- 招待の取り消しに失敗した場合。

property emojis¶

接続したクライアントが利用できる絵文字。

型: Sequence[Emoji]

property extensions¶

エクステンション名の読み取り専用マッピング。

型: Mapping[str, types.ModuleType]

await fetch_channel(channel_id, /)¶

This function is a coroutine.

指定されたIDを持つ abc.GuildChannel 、 abc.PrivateChannel 、または Thread を取得します。

注釈

このメソッドはDiscord APIからGETします。通常は get_channel() を代わりとして使用してください。

バージョン 1.2 で追加.

バージョン 2.0 で変更: channel_id 引数は位置限定引数になりました。

例外

InvalidData -- まだ定義されていないチャンネルタイプがDiscord APIから受信された場合。
HTTPException -- チャンネルの取得に失敗した場合。
NotFound -- 引数が無効なチャンネル IDである場合。
Forbidden -- このチャンネルからメッセージを取得する権限がない場合。

戻り値

IDから取得したチャンネル。

戻り値の型

Union[abc.GuildChannel, abc.PrivateChannel, Thread]

await fetch_guild(guild_id, /, *, with_counts=True)¶

This function is a coroutine.

IDから Guild を取得します。

注釈

これを使用した場合、 Guild.channels 、 Guild.members 、そして各 Member ごとの Member.activity 、 Member.voice を**取得することができません** 。

注釈

このメソッドはAPIを呼び出します。通常は get_guild() を代わりとして使用してください。

バージョン 2.0 で変更: guild_id 引数は位置限定引数になりました。

パラメータ

guild_id (int) -- 取得したいギルドのID。
with_counts (bool) --
ギルドにカウント情報を含めるかどうか。これを使うことで特権インテントがなくても Guild.approximate_member_count と Guild.approximate_presence_count 属性が設定されます。デフォルトは True です。

バージョン 2.0 で追加.

例外

Forbidden -- Guildに「アクセス」する権限を持っていない場合。
HTTPException -- Guildの取得に失敗した場合。

戻り値

IDから取得したギルド。

戻り値の型

Guild

async for ... in fetch_guilds(*, limit=200, before=None, after=None)¶

Botが所属するGuildを取得できる、 asynchronous iterator を取得します。

注釈

これを使った場合、各 Guild の Guild.owner 、 Guild.icon 、 Guild.id 、 Guild.name のみ取得できます。

注釈

これはAPIを呼び出します。通常は guilds を代わりに使用してください。

サンプル

使い方

async for guild in client.fetch_guilds(limit=150):
    print(guild.name)

リストへフラット化

guilds = [guild async for guild in client.fetch_guilds(limit=150)]
# guilds is now a list of Guild...

すべてのパラメータがオプションです。

パラメータ

limit (Optional[int]) --
取得するギルドの数。 None の場合、Botがアクセスできるギルドすべてを取得します。ただし、これには時間が掛かることに注意してください。デフォルトは200です。

バージョン 2.0 で変更: デフォルトが200に変更されました。
before (Union[abc.Snowflake, datetime.datetime]) -- 渡された日付、またはギルドより前のギルドを取得します。日付を指定する場合、UTC aware datetimeを利用することを推奨します。naive datetimeである場合、これはローカル時間であるとみなされます。
after (Union[abc.Snowflake, datetime.datetime]) -- 渡された日付、またはオブジェクトより後のギルドを取得します。日付を指定する場合、UTC対応の「aware」を利用することを推奨します。日付が「naive」である場合、これは地域時間であるとみなされます。

例外

HTTPException -- Guildの取得に失敗した場合。

列挙

Guild -- データを解析したGuild。

await fetch_invite(url, *, with_counts=True, with_expiration=True, scheduled_event_id=None)¶

This function is a coroutine.

discord.gg URLまたはIDから、 Invite を取得します。

注釈

もしBotがInviteのGuildに参加していない場合、 Invite のguildとchannel属性はそれぞれ PartialInviteGuild と PartialInviteChannel になります。

パラメータ

url (Union[Invite, str]) -- Discordの招待ID、またはURL (discord.gg URLである必要があります)。
with_counts (bool) -- 招待にカウントの情報を含めるかどうか。これにより Invite.approximate_member_count と Invite.approximate_presence_count 属性が追加されます。
with_expiration (bool) --
招待の有効期限を含めるかどうか。有効期限は Invite.expires_at に代入されます。

バージョン 2.0 で追加.
scheduled_event_id (Optional[int]) --
招待に紐づいたスケジュールイベントのID。

注釈

このパラメータを使用する場合、event_id パラメータを含む url を指定することはできません。

バージョン 2.0 で追加.

例外

ValueError -- URLに event_id が含まれているのに、 scheduled_event_id も渡された場合。
NotFound -- 招待の有効期限が切れたか無効の場合。
HTTPException -- 招待の取得に失敗した場合。

戻り値

URL/IDから取得した招待。

戻り値の型

Invite

await fetch_premium_sticker_packs()¶

This function is a coroutine.

利用可能なプレミアムスタンプパックをすべて取得します。

バージョン 2.0 で追加.

例外: HTTPException -- スタンプパックの取得に失敗した場合。
戻り値: 利用可能なプレミアムスタンプパックすべて。
戻り値の型: List[StickerPack]

await fetch_stage_instance(channel_id, /)¶

This function is a coroutine.

ステージチャンネルIDの StageInstance を取得します。

バージョン 2.0 で追加.

パラメータ

channel_id (int) -- ステージチャンネルのID。

例外

NotFound -- ステージインスタンスまたはチャンネルが見つからなかった場合。
HTTPException -- ステージインスタンスの取得に失敗した場合。

戻り値

ステージチャンネルIDで取得したステージインスタンス

戻り値の型

StageInstance

await fetch_sticker(sticker_id, /)¶

This function is a coroutine.

特定のIDの Sticker を取得します。

バージョン 2.0 で追加.

例外

HTTPException -- スタンプの取得に失敗した場合。
NotFound -- スタンプIDが無効な場合。

戻り値

要求されたスタンプ。

戻り値の型

Union[StandardSticker, GuildSticker]

await fetch_template(code)¶

This function is a coroutine.

discord.new URL またはコードから Template を取得します。

パラメータ

code (Union[Template, str]) -- DiscordテンプレートコードまたはURL (discord.new URLである必要があります)。

例外

NotFound -- 無効なテンプレートである場合。
HTTPException -- テンプレートの取得に失敗した場合。

戻り値

URL/コードからのテンプレート。

戻り値の型

Template

await fetch_user(user_id, /)¶

This function is a coroutine.

IDをもとに User を取得します。そのユーザーとギルドを共有する必要はありませんが、操作の多くはそれを必要とします。

注釈

このメソッドはAPIを呼び出します。 discord.Intents.members とメンバーキャッシュを有効化している場合は、 get_user() を使用するべきです

バージョン 2.0 で変更: user_id 引数は位置限定引数になりました。

パラメータ

user_id (int) -- 取得したいユーザーのID。

例外

NotFound -- この ID を持つユーザーが存在しない場合。
HTTPException -- ユーザーの取得に失敗した場合。

戻り値

あなたがリクエストしたユーザー。

戻り値の型

User

await fetch_webhook(webhook_id, /)¶

This function is a coroutine.

指定した ID の Webhook を取得します。

バージョン 2.0 で変更: webhook_id 引数は位置限定引数になりました。

例外

HTTPException -- Webhookの取得に失敗した場合。
NotFound -- 無効なWebhookのIDだった場合。
Forbidden -- Webhookを取得する権限がない場合。

戻り値

BotがリクエストしたWebhook。

戻り値の型

Webhook

await fetch_widget(guild_id, /)¶

This function is a coroutine.

Guild IDから Widget を取得します。

注釈

この情報を取得するためには、Guildのウィジェットを有効化しておく必要があります。

バージョン 2.0 で変更: guild_id 引数は位置限定引数になりました。

パラメータ

guild_id (int) -- GuildのID。

例外

Forbidden -- Guildのウィジェットが無効になっている場合。
HTTPException -- ウィジェットの取得に失敗した場合。

戻り値

Guildのウィジェット。

戻り値の型

Widget

for ... in get_all_channels()¶

クライアントが「アクセス」できるすべての abc.GuildChannel のジェネレータを取得します。

これは以下に相当します:

for guild in client.guilds:
    for channel in guild.channels:
        yield channel

注釈

abc.GuildChannel を受け取ったからと言って、そのチャンネルで、クライアントが発言可能であるとは限りません。クライアントが発言可能なチャンネルのみを取得したいのなら、 abc.GuildChannel.permissions_for() を使ってください。

列挙: abc.GuildChannel -- クライアントが「アクセスする」ことができるチャンネル。

for ... in get_all_members()¶

クライアントが参照可能なすべての Member のgeneratorを返します。

これは以下に相当します:

for guild in client.guilds:
    for member in guild.members:
        yield member

列挙: Member -- クライアントが見れる、Guildのメンバー。

get_channel(id, /)¶

与えられたIDのチャンネルまたはスレッドを返します。

バージョン 2.0 で変更: id 引数は位置限定引数になりました。

パラメータ: id (int) -- 検索するID。
戻り値: チャンネル、または該当するものが見つからない場合 None が返ります。
戻り値の型: Optional[Union[abc.GuildChannel, Thread, abc.PrivateChannel]]

get_cog(name, /)¶

要求されたコグのインスタンスを取得します。

コグが見つからなかった場合、代わりに None が返されます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- リクエストしているコグの名前です。これは、クラス作成時にキーワード引数で渡された名前と同等です。指定しない場合は、クラス名と同等になります。
戻り値: 要求されたコグ。見つからない場合は None を返します。
戻り値の型: Optional[bool]

get_command(name, /)¶

内部のコマンドリストから検索し、 Command を取得します。

これはコマンドのエイリアスを取得する方法としても使用できます。

名前は修飾されていても構いません(例： 'foo bar' など)。サブコマンドが見つからなかった場合は、通常通り None が返されます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 取得するコマンドの名前。
戻り値: 要求されたコマンド。見つからなければ None を返します。
戻り値の型: Optional[Command]

await get_context(origin, /, *, cls=...)¶

This function is a coroutine.

メッセージまたはインタラクションから、呼び出しコンテキストを返します。

これは process_commands() より低レベルなcounter-partで、開発者がより細かく処理を制御できるようにするためのものです。

返されたコンテキストが、有効な呼び出しコンテキストであることは保証していないので、 Context.valid によってチェックして確認する必要があります。コンテキストが有効でない場合は、 invoke() で呼び出される有効な候補ではありません。

注釈

インタラクションベースのコンテキストでカスタムコンテキストを使用する場合（ HybridCommand など）にはこのメソッドを上書きしてクラスを返さないといけません。

バージョン 2.0 で変更: message パラメータが位置指定のみになり、 origin に改名されました。

パラメータ

origin (Union[discord.Message, discord.Interaction]) -- 呼び出しコンテキストを取得するためのメッセージやインタラクション。
cls -- コンテキストを作成するために使用されるファクトリークラス。デフォルトでは、これは Context です。カスタムクラスを提供する場合は、 Context の引数が同じようにならなければなりません。

戻り値

呼び出しコンテキスト。このタイプは cls パラメータを使用して変更できます。

戻り値の型

Context

get_emoji(id, /)¶

与えられた ID の絵文字を返します。

バージョン 2.0 で変更: id 引数は位置限定引数になりました。

パラメータ: id (int) -- 検索するID。
戻り値: カスタム絵文字が返されます。見つからなかった場合は、 None が返ります。
戻り値の型: Optional[Emoji]

get_guild(id, /)¶

与えられたIDを検索し、それに合致するGuildを返します。

バージョン 2.0 で変更: id 引数は位置限定引数になりました。

パラメータ: id (int) -- 検索するID。
戻り値: Guildが返されます。見つからなかった場合は、 None が返ります。
戻り値の型: Optional[Guild]

get_partial_messageable(id, *, guild_id=None, type=None)¶

与えられたチャンネルIDのPartialMessageableを返します。

これはチャンネルIDがあるがメッセージを送信するためにAPI呼び出しをしたくない場合に便利です。

バージョン 2.0 で追加.

パラメータ

id (int) -- PartialMessageableを作成するためのチャンネルID。
guild_id (Optional[int]) -- 部分的なメッセージ可能チャンネルを作成するためのオプションのギルドID。これはメッセージの送信には必須ではありませんが、 jump_url() や guild プロパティが適切に動作するようになります。
type (Optional[ChannelType]) -- PartialMessageableの基礎となるチャンネルタイプ。

戻り値

PartialMessageable

戻り値の型

PartialMessageable

await get_prefix(message, /)¶

This function is a coroutine.

特定のメッセージの文脈内でボットが使用する接頭辞を取得します。

バージョン 2.0 で変更: message パラメータが位置指定のみになりました。

パラメータ: message (discord.Message) -- 接頭辞を取得するメッセージのコンテキスト。
戻り値: ボットが受け取る接頭辞またはそのリスト。
戻り値の型: Union[List[str], str]

get_stage_instance(id, /)¶

与えられたステージチャンネルIDを持つステージインスタンスを返します。

バージョン 2.0 で追加.

パラメータ: id (int) -- 検索するID。
戻り値: ステージインスタンス、または該当するものが見つからない場合 None が返ります。
戻り値の型: Optional[StageInstance]

get_sticker(id, /)¶

与えられたIDに合致するギルドスタンプを返します。

バージョン 2.0 で追加.

注釈

標準スタンプを取得するには、 fetch_sticker() か fetch_premium_sticker_packs() を使用してください。

戻り値: Stickerが返ります。見つからなかった場合は None が返ります。
戻り値の型: Optional[GuildSticker]

get_user(id, /)¶

与えられたIDを検索し、それに合致するユーザーを返します。

バージョン 2.0 で変更: id 引数は位置限定引数になりました。

パラメータ: id (int) -- 検索するID。
戻り値: Userが返されます。見つからなかった場合は、 None が返ります。
戻り値の型: Optional[User]

property guilds¶

接続したクライアントがメンバーとして参加しているギルド。

型: Sequence[Guild]

property intents¶

この接続用に設定されたインテント。

バージョン 1.5 で追加.

型: Intents

await invoke(ctx, /)¶

This function is a coroutine.

コンテキストに与えられたコマンドを呼び出します。すべての内部イベントも処理されます。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- 呼び出すコンテキスト。

is_closed()¶: bool: WebSocket接続が閉じられているかどうか。

await is_owner(user, /)¶

This function is a coroutine.

User または Member がこのボットの所有者か確認します。

owner_id が設定されていない場合、 application_info() から取得されます。

バージョン 1.3 で変更: owner_ids が設定されていない場合、この関数はチームが所有しているかも確認します。

バージョン 2.0 で変更: user 引数は位置限定引数になりました。

パラメータ: user (abc.User) -- 確認するユーザー。
戻り値: ユーザーが所有者かどうか。
戻り値の型: bool

is_ready()¶: bool: クライアントの内部キャッシュが利用可能となっているかを表します。

is_ws_ratelimited()¶

bool: WebSocketがレート制限中かどうか。

メンバーへのクエリをHTTPで行うか、ゲートウェイ経由で行うかを決めるときに役立ちます。

バージョン 1.6 で追加.

property latency¶

HEARTBEATとHEARTBEAT_ACKの間の遅延を秒単位で測定します。

DiscordのWebSocketプロトコルの遅延として使うこともできます。

型: float

await load_extension(name, *, package=None)¶

This function is a coroutine.

エクステンションを読み込みます。

エクステンションはコマンド、コグ、リスナーを含むPythonのモジュールです。

エクステンションは setup という名前のグローバルな関数を持っている必要があります。 setup はエクステンションを読み込むときのエントリーポイントになります。エントリーポイントは bot という引数を持っている必要があります。

バージョン 2.0 で変更: このメソッドは、coroutine です。

パラメータ

name (str) -- 読み込むエクステンションの名前。サブモジュールにアクセスする場合はPythonのimport文のようにドットで区切る必要があります。例えば hoge/test.py を読み込むときには hoge.test になります。
package (Optional[str]) --
相対インポートを解決するためのパッケージ名。例えば .foo.test のように、相対パスで拡張機能を読み込む場合に必要になります。デフォルトは None です。

バージョン 1.7 で追加.

例外

ExtensionNotFound -- エクステンションを読み込めなかった場合。この例外は渡された package パラメータを解釈できなかったときにも発生します。
ExtensionAlreadyLoaded -- エクステンションがすでに読み込まれている場合。
NoEntryPointError -- エクステンションに setup 関数がない場合。
ExtensionFailed -- エクステンション、または setup 関数で例外が発生した場合。

await login(token)¶

This function is a coroutine.

指定した資格情報を使用してクライアントにログインし、 setup_hook() を呼び出します。

パラメータ

token (str) -- 認証トークン。ライブラリが処理するのでトークンには何もつけないでください（ Bot 等）。

例外

LoginFailure -- 不正な認証情報が渡された場合。
HTTPException -- 不明なHTTP関連のエラーが発生した場合。通常、ステータスコードが200でないか、既知の誤った資格情報が渡された場合です。

await on_command_error(context, exception, /)¶

This function is a coroutine.

ボットに渡されたデフォルトのコマンドの例外のハンドラ。

デフォルトではライブラリロガーに出力しますが、他の実装をするために上書きすることもできます。

これは、コマンドの例外のリスナーを指定していない場合にのみ発生します。

バージョン 2.0 で変更: context と exception が位置限定引数になりました。 sys.stderr に出力するのではなくライブラリロガーが使用されるようになりました。

await on_error(event_method, /, *args, **kwargs)¶

This function is a coroutine.

クライアントによって提供されるデフォルトのエラーハンドラ。

デフォルトでは、これはライブラリロガーに出力されますが、異なる実装によって上書きされる可能性があります。詳細については on_error() を確認してください。

バージョン 2.0 で変更: event_method パラメータが位置限定引数になり、 sys.stderr に出力するのではなくログに記録するようになりました。

property persistent_views¶

クライアントに追加された永続的なビューのシーケンスです。

バージョン 2.0 で追加.

型: Sequence[View]

property private_channels¶

接続したクライアントが参加しているプライベートチャンネル。

注釈

Discordでのプライベートチャンネルの取扱いは内部的に処理されているため、これは最新のプライベートチャンネルから最大128個までしか取得できません。

型: Sequence[abc.PrivateChannel]

await process_commands(message, /)¶

This function is a coroutine.

ボットとそのグルーブに登録されたコマンドを処理します。この関数を取り除くとコマンドは処理されません。

デフォルトでは、この関数は on_message() のなかで呼び出されます。 on_message() を上書きした場合にはこの関数を呼び出す処理を書く必要があります。

これは他の低レベルのツールを使って構築されており、 get_context() の呼び出しに続いて、 invoke() の呼び出しに相当します。

また、メッセージの作成者がボットであるか確認し、その場合 get_context() や invoke() を呼び出しません。

バージョン 2.0 で変更: message パラメータが位置指定のみになりました。

パラメータ: message (discord.Message) -- コマンドを処理するメッセージ。

await reload_extension(name, *, package=None)¶

This function is a coroutine.

拡張機能を「極小単位で」リロードします。

これにより、拡張機能が、ほとんど同じ拡張機能で置き換えられ、更新されるだけです。これは、unload_extension() が実行され、次に load_extension() が実行される、この一連の流れと同等です。つまり、操作がリロード中に失敗した場合、Botは以前の状態にロールバックします。

パラメータ

name (str) -- リロードする拡張モジュール名。サブモジュールにアクセスする場合は、通常の Pythonのimportのように、ドットで区切られている必要があります。例: foo.test を foo/test.py をインポートする場合。
package (Optional[str]) --
相対インポートを解決するためのパッケージ名。 .hoge.test のように、相対パスを使用してエクステンションを再読込する場合に必要です。デフォルトは None です。

バージョン 1.7 で追加.

例外

ExtensionNotLoaded -- 拡張機能がもともとロードされていなかった場合。
ExtensionNotFound -- エクステンションを読み込めなかった場合。この例外は渡された package パラメータを解釈できなかったときにも発生します。
NoEntryPointError -- エクステンションに setup 関数がない場合。
ExtensionFailed -- エクステンションセットアップ関数に、何らかの実行エラーが発生した場合。

remove_check(func, /, *, call_once=False)¶

ボットからグローバルチェックを除去します。

この関数は冪等性を保持しており、関数がグローバルチェックに含まれていない場合でも例外が発生しません。

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ

func -- グローバルチェックから除去する関数。
call_once (bool) -- Bot.add_check() によって call_once=True を指定して関数を追加していた場合、または check_once() を使用して関数を追加していた場合。

await remove_cog(name, /, *, guild=..., guilds=...)¶

This function is a coroutine.

ボットからコグを除去し、それを返します。

これにより、コグが登録したすべての登録済みのコマンドと、コグに登録されているイベントリスナーも全て削除されます。

コグが見つからない場合、このメソッドによる影響はありません。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

バージョン 2.0 で変更: このメソッドは、coroutine です。

パラメータ

name (str) -- 削除するコグの名前。
guild (Optional[Snowflake]) --
コグがアプリケーションコマンドグループの場合、これはコググループが除去されるギルドになります。与えられない場合はグローバルコマンドになります。

バージョン 2.0 で追加.
guilds (List[Snowflake]) --
コグがアプリケーションコマンドグループの場合、これはコググループが除去されるギルドになります。与えられない場合はグローバルコマンドになります。 guild と併用することはできません。

バージョン 2.0 で追加.

戻り値

除去されたコグ。見つからない場合は None 。

戻り値の型

Optional[Cog]

remove_command(name, /)¶

内部のコマンドリストから該当するコマンドを検索し、その Command を除去します。

これはコマンドのエイリアスによって、コマンドを除去することもできます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 除去するコマンドの名前。
戻り値: 除去されたコマンド。有効な名前ではない場合は None が返されます。
戻り値の型: Optional[Command]

remove_listener(func, /, name=...)¶

リスナープールからリスナーを除去します。

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ

func -- 除去するリスナーとして使用された関数。
name (str) -- 除去したいイベントの名前。デフォルトでは func.__name__ です。

run(token, *, reconnect=True, log_handler=..., log_formatter=..., log_level=..., root_logger=False)¶

イベントループの初期化を簡単に行うことができるブロッキングコール。

イベントループをより詳細に制御するには、この関数を使用しないでください。 start() または connect() + login() を使用してください。

またこの関数は、初心者がライブラリの仕組みを知ることが簡単にできるよう logging ライブラリを設定します。より高度なユーザーは、 log_handler に None を渡してこれを無効化することもできます。

警告

この関数はブロッキングを行うため、必ず最後の方で呼び出してください。この関数を呼び出した後に書かれているイベントや関数は、Botが停止するまで実行されません。

パラメータ

token (str) -- 認証トークン。ライブラリが処理するのでトークンには何もつけないでください（ Bot 等）。
reconnect (bool) -- インターネットの障害やDiscord側の特定の障害が発生した際に再接続を試みるかどうか。不正な状態による特定の切断 (無効なシャーディングペイロードや不正なトークンなど) は処理されません。
log_handler (Optional[logging.Handler]) --
ライブラリロガーにて使用すべきログハンドラ。もしこれが None の場合ライブラリはログ関連のセットアップを一切行いません。 None を渡してもログは記録されますが、設定は自己責任となります。

渡されない場合のデフォルトは logging.StreamHandler です。

バージョン 2.0 で追加.
log_formatter (logging.Formatter) --
指定されたログハンドラで使用するフォーマッタ。渡されない場合は、既定で色ベースのログフォーマッタが使用されます (使用可能な場合)。

バージョン 2.0 で追加.
log_level (int) --
ライブラリロガーの既定のログレベル。これは log_handler が None でない場合のみ適用されます。デフォルトは logging.INFO です。

バージョン 2.0 で追加.
root_logger (bool) --
ライブラリロガーではなくルートロガーを設定するかどうか。デフォルトではライブラリロガー ('discord') のみが設定されています。これが True に設定されている場合、ルートロガーも設定されます。

デフォルトでは False です。

バージョン 2.0 で追加.

await setup_hook()¶

This function is a coroutine.

Botのセットアップ時に呼び出されるコルーチンです。デフォルトでは空白です

Websocketに接続する前になにか非同期な関数を実行したい場合は、このコルーチンを上書きして下さい。

login() で１回だけ呼ばれ、全てのイベントが発火する前に呼ばれます。 on_ready() より良いセットアップの方法です。

警告

これはWebSocket接続の前に呼ばれるため、WebSocketを待つ関数の呼び出しはデッドロックします。これには wait_for() や wait_until_ready() が含まれます。

バージョン 2.0 で追加.

await start(token, *, reconnect=True)¶

This function is a coroutine.

login() + connect() を簡略化したコルーチン。

パラメータ

token (str) -- 認証トークン。ライブラリが処理するのでトークンには何もつけないでください（ Bot 等）。
reconnect (bool) -- インターネットの障害やDiscord側の特定の障害が発生した際に再接続を試みるかどうか。不正な状態による特定の切断 (無効なシャーディングペイロードや不正なトークンなど) は処理されません。

例外

TypeError -- 予期しないキーワード引数を受け取った場合。

property status¶: Status: Discordへのログイン時に使用されるステータス。

property stickers¶

接続したクライアントが持つスタンプ。

バージョン 2.0 で追加.

型: Sequence[GuildSticker]

property tree¶

このボット内のアプリケーションコマンドを処理するコマンドツリー。

バージョン 2.0 で追加.

型: CommandTree

await unload_extension(name, *, package=None)¶

This function is a coroutine.

拡張機能をアンロードします。

拡張機能がアンロードされると、すべてのコマンド、リスナー、コグがボットから除去され、モジュールはアンインポートされます。

拡張機能から提供される、オプションのグローバル関数 teardown によって、必要に応じてその他のクリーンアップを行うことができます。この関数は、 load_extension() の setup と似た、単一のパラメータを取ります。

バージョン 2.0 で変更: このメソッドは、coroutine です。

パラメータ

name (str) -- アンロードする拡張モジュール名。サブモジュールにアクセスする場合は、通常の Pythonのimportのように、ドットで区切られている必要があります。例: foo/test.py をアンロードする場合、foo.test と書いてください。
package (Optional[str]) --
相対インポートを解決するためのパッケージ名。例えば .foo.test のように、相対パスで拡張機能をアンロードするときに必要です。デフォルトでは None です。

バージョン 1.7 で追加.

例外

ExtensionNotFound -- 渡された package パラメータを使用してエクステンションの名前を解決できなかった場合。
ExtensionNotLoaded -- 拡張機能がもともとロードされていなかった場合。

property user¶

接続されたクライアントを表します。ログインしていない場合は None が返されます。

型: Optional[ClientUser]

property users¶

Botが見ることができるユーザーのリストを返します。

型: List[User]

property voice_clients¶

ボイス接続のリストを表します。

これらは通常、 VoiceClient のインスタンスです。

型: List[VoiceProtocol]

wait_for(event, /, *, check=None, timeout=None)¶

This function is a coroutine.

WebSocketイベントがディスパッチされるまで待機します。

これは、ユーザーがメッセージに返信するのを待ったり、メッセージに反応したり、メッセージを自己完結的に編集したりするために使うことができます。

timeout パラメータは asyncio.wait_for() に渡されます。デフォルトではタイムアウトしません。タイムアウトした際に asyncio.TimeoutError が発生するのは、使いやすさを考慮したためです。

指定されたイベントが複数の引数を返す場合は、代わりとしてその引数を含んだ tuple が返ります。イベントとそのパラメータについては documentation を参照してください。

この関数は 条件を満たす最初のイベント を返します。

サンプル

ユーザーからの返信メッセージを待つ場合、次のような書き方ができます:

@client.event
async def on_message(message):
    if message.content.startswith('$greet'):
        channel = message.channel
        await channel.send('Say hello!')

        def check(m):
            return m.content == 'hello' and m.channel == channel

        msg = await client.wait_for('message', check=check)
        await channel.send(f'Hello {msg.author}!')

また、メッセージ送信者が、サムズアップリアクションを付けるのを待つ場合、次のようにも書けます:

@client.event
async def on_message(message):
    if message.content.startswith('$thumb'):
        channel = message.channel
        await channel.send('Send me that 👍 reaction, mate')

        def check(reaction, user):
            return user == message.author and str(reaction.emoji) == '👍'

        try:
            reaction, user = await client.wait_for('reaction_add', timeout=60.0, check=check)
        except asyncio.TimeoutError:
            await channel.send('👎')
        else:
            await channel.send('👍')

バージョン 2.0 で変更: event 引数は位置限定引数になりました。

パラメータ

event (str) -- イベント名はイベントリファレンスに似ていますが、接頭詞の on_ がありません。
check (Optional[Callable[..., bool]]) -- 待っているものに該当するかを確認する関数。引数は、待機しているイベントの返り値を満たしている必要があります。
timeout (Optional[float]) -- タイムアウトして asyncio.TimeoutError が送出されるまでの秒数。

例外

asyncio.TimeoutError -- タイムアウトが設定されていて、かつその時間が経過した場合。

戻り値

単一の引数、あるいはイベントリファレンスの返り値を反映した、複数の引数の値を含む tuple が返ります。返り値がない場合もあります。

戻り値の型

Any

await wait_until_ready()¶

This function is a coroutine.

クライアントの内部キャッシュの準備が完了するまで待機します。

警告

setup_hook() の内部でこれを呼び出すと、デッドロックになる可能性があります。

for ... in walk_commands()¶

すべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。

バージョン 1.4 で変更: エイリアスによって重複した場合は、そのエイリアスまたはコマンドは返しません。

列挙: Union[Command, Group] -- コマンドの内部リストからの、コマンドまたはグループ。

AutoShardedBot¶

class discord.ext.commands.AutoShardedBot(command_prefix, *, help_command=<default-help-command>, tree_cls=<class 'discord.app_commands.tree.CommandTree'>, description=None, intents, **options)¶

これは、 discord.AutoShardedClient から代わりに継承されていることを除いて、 Bot と似ています。

async with x: 非同期的にボットを初期化し自動でクリーンアップします。

バージョン 2.0 で追加.

接頭辞のヘルパー¶

discord.ext.commands.when_mentioned(bot, msg, /)¶

メンションされるのと同等のコマンドの接頭辞を実装する呼び出し可能オブジェクト。

これらは Bot.command_prefix 属性に渡されます。

バージョン 2.0 で変更: bot と msg のパラメータは位置指定のみになりました。

discord.ext.commands.when_mentioned_or(*prefixes)¶

上記または他の接頭辞が提供されたときの接頭辞を実装する呼び出し可能オブジェクト。

これらは Bot.command_prefix 属性に渡されます。

サンプル

bot = commands.Bot(command_prefix=commands.when_mentioned_or('!'))

注釈

この呼び出し可能オブジェクトは別の呼び出し可能オブジェクトを返すため、カスタム呼び出し可能オブジェクト内でこれが行われる場合は、返される呼び出し可能オブジェクトを必ず呼び出さなければなりません。例:

async def get_prefix(bot, message):
    extras = await prefixes_for(message.guild) # returns a list
    return commands.when_mentioned_or(*extras)(bot, message)

参考

when_mentioned()

イベントリファレンス¶

これらのイベントは、コマンド拡張モジュールのカスタム関数であることを除けば、通常のイベントに似ています。

discord.ext.commands.on_command_error(ctx, error)¶

ユーザーによる入力エラー、チェックの失敗、またはコードの記述ミスによって、コマンド内でエラーが発生したときに呼び出されるエラーハンドラ。

デフォルトは (Bot.on_command_error()) です。

パラメータ

ctx (Context) -- 呼び出しコンテキスト。
error (CommandError derived) -- 発生したエラー。

discord.ext.commands.on_command(ctx)¶

該当するコマンドが見つかり、呼び出されようとするときに、呼び出されるイベント。

このイベントは、エラーまたは完了を介して、コマンド自体が成功するかどうかに関係なく、必ず呼び出されます。

パラメータ: ctx (Context) -- 呼び出しコンテキスト。

discord.ext.commands.on_command_completion(ctx)¶

コマンドの呼び出しが完了したときに呼び出されるイベント。

このイベントは、コマンドの実行が成功した場合にのみ呼び出されます。すなわち、すべてのチェックが成功し、ユーザーによって正しく入力された場合にのみ実行されます。

パラメータ: ctx (Context) -- 呼び出しコンテキスト。

コマンド¶

デコレータ¶

@discord.ext.commands.command(name=..., cls=..., **attrs)¶

関数を Command 、または group() で呼び出した場合には Group に変換するデコレータです。

デフォルトでは、 help 属性は、関数の docstring から自動的に取得したものを inspect.cleandoc を使用してクリーンアップされたものを使用します。 docstring が bytes の場合、utf-8 エンコーディングを使って str にデコードされます。

check() & co.デコレータを使用して追加された、すべてのチェックを機能に追加されます。このデコレータを通さずして、独自のチェックを提供する以外の方法はありません。

パラメータ

name (str) -- コマンドの名前。デフォルトでは関数名をそのまま使用します。
cls -- 構築するクラス。デフォルトでは、 Command です。通常これは変更しません。
attrs -- cls で指定されたクラスの構築時に渡すキーワード引数。

例外

TypeError -- 関数がコルーチンでない場合、またはすでにコマンドが登録されている場合。

@discord.ext.commands.group(name=..., cls=..., **attrs)¶

関数を Group に変換するデコレータ。

これは command() デコレータに似ていますが、デフォルトでは引数の cls は Group に設定されています。

バージョン 1.1 で変更: cls パラメータを渡せるようになりました。

@discord.ext.commands.hybrid_command(name=..., *, with_app_command=True, **attrs)¶

関数を HybridCommand に変換するデコレータ。

ハイブリッドコマンドは、通常の Command と app_commands.Command の両方として機能するコマンドです。

コマンドのコールバックはアプリケーションコマンドコールバックとして表現できるものでないといけません。コンバーターは discord.AppCommandOptionType.string 型の Transformer に暗黙的に変換されます。

チェックとエラーハンドラは、 Command のようなコマンドであるかのように呼び出されます。つまり、パラメータには discord.Interaction ではなく Context を取ります。

バージョン 2.0 で追加.

パラメータ

name (Union[str, locale_str]) -- コマンドの名前。デフォルトでは関数名をそのまま使用します。
with_app_command (bool) -- アプリケーションコマンドとしてもコマンドを登録するかどうか。
**attrs -- ハイブリッドコマンドの構築時に渡すキーワード引数。

例外

TypeError -- 関数がコルーチンでない場合、またはすでにコマンドが登録されている場合。

@discord.ext.commands.hybrid_group(name=..., *, with_app_command=True, **attrs)¶

関数を HybridGroup に変換するデコレータ。

これは group() デコレータに似ていますが、代わりにハイブリッドグループを作成します。

パラメータ: with_app_command (bool) -- アプリケーションコマンドとしてもコマンドを登録するかどうか。
例外: TypeError -- 関数がコルーチンでない場合、またはすでにコマンドが登録されている場合。

Command¶

class discord.ext.commands.Command(*args, **kwargs)¶

Botのテキストコマンドのプロトコルを実装するクラス。

これらは手動では作成されず、デコレータまたは機能インターフェースを介して作成されます。

name¶

コマンドの名前。

型: str

callback¶

コマンドが呼び出されたときに実行されるコルーチン。

型: コルーチン

help¶

コマンドに関する、長いヘルプテキスト。

型: Optional[str]

brief¶

コマンドに関する、短いヘルプテキスト。

型: Optional[str]

usage¶

デフォルトのヘルプテキストを置き換えるための引数。

型: Optional[str]

aliases¶

そのコマンドを呼び出すことができるエイリアスのリスト。

型: Union[List[str], Tuple[str]]

enabled¶

コマンドが、現在、有効かどうかを示すbool値。コマンドが無効化されている状態で呼び出された場合、DisabledCommand が on_command_error() にて発生します。デフォルトは True です。

型: bool

parent¶

このコマンドが属する親コマンド。親コマンドが存在しない場合、None が返ります。

型: Optional[Group]

cog¶

このコマンドが属するコグ。属するコグが存在しない場合、None が返ります。

型: Optional[bool]

checks¶

与えられた Context を唯一のパラメータとしてコマンドが実行できるかどうかを確認するチェック関数のリストです。もし失敗を知らせるために例外を発生させる必要がある場合には、 CommandError から継承したものを使用する必要があります。もしチェックに失敗した場合には、 on_command_error() イベントで CheckFailure 例外が発生することに注意してください。

型: List[Callable[[Context], bool]]

description¶

デフォルトのヘルプコマンドの前に表示されるメッセージ。

型: str

hidden¶

True の場合、デフォルトのヘルプコマンドではヘルプ出力に表示されません。

型: bool

rest_is_raw¶

もし False でキーワードのみの引数を指定した場合には、キーワードのみの引数は取り除かれて、残りを完全に生のまま渡すのではなく、 MissingRequiredArgument やデフォルト値を通常の引数として扱うように処理されます。もし True ならば、キーワードのみの引数は、残りの引数を完全に生のまま渡します。デフォルトは False です。

型: bool

invoked_subcommand¶

存在する場合、呼び出されたサブコマンド。

型: Optional[Command]

require_var_positional¶

もし True で可変長の位置引数が指定された場合、少なくとも1つの引数を指定するようユーザーに要求します。デフォルトは False です。

バージョン 1.5 で追加.

型: bool

ignore_extra¶

もし True ならば、コマンドの要求がすべて満たされていれば、余計な文字列を無視します (例: ?foo a b c で a と b しか期待できない場合)。そうでなければ on_command_error() とローカルのエラーハンドラが TooManyArguments と共に呼び出されます。デフォルトは True です。

型: bool

cooldown_after_parsing¶

もし True ならば、引数解析の後にクールダウン処理が行われ、コンバータが呼び出されます。 False の場合は、クールダウン処理が最初に行われ、その後にコンバータが呼ばれます。デフォルトは False です。

型: bool

extras¶

コマンドに添付するユーザー提供のオマケの辞書。

注釈

このオブジェクトはライブラリによってコピーされることがあります。

型: dict

バージョン 2.0 で追加.

@after_invoke¶

コルーチンを、実行後に呼び出すフックとして登録するデコレータ。

この実行後呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.after_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行後呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@before_invoke¶

渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。

この実行前呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.before_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行前呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@error¶

コルーチンをローカルエラーハンドラとして登録するデコレータです。

ローカルエラーハンドラは、一つのコマンドに限定された on_command_error() イベントです。しかし、キャッチオールとして on_command_error() イベントはその後も呼び出されます。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- ローカルエラーハンドラとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

add_check(func, /)¶

コマンドにチェックを追加します。

これは check() に対する非デコレーターインターフェイスです。

バージョン 1.3 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

参考

check() デコレータ

パラメータ: func -- チェックとして使用される関数。

remove_check(func, /)¶

コマンドからチェックを削除します。

この関数は冪等性を保持しており、関数がグローバルチェックに含まれていない場合でも例外が発生しません。

バージョン 1.3 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ: func -- チェックから除去する関数。

update(**kwargs)¶

Command インスタンスを更新された属性で更新します。

これは command() デコレーターと同様に動作します。パラメータは Command やサブクラスのコンストラクターに渡され、名前とコールバックは除かれます。

await __call__(context, /, *args, **kwargs)¶

This function is a coroutine.

コマンドが保持する内部コールバックを呼び出します。

注釈

これは、チェック、コンバーター、呼び出しフック、クールダウンなど、すべてのメカニズムを回避します。この関数には、適切な引数と型を渡すように注意してください。

バージョン 1.3 で追加.

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

copy()¶

コマンドのコピーを作成します。

戻り値: このコマンドの新しいインスタンス。
戻り値の型: Command

property clean_params¶

Dict[str, Parameter]: コンテキストまたは自己のパラメータなしでパラメータ辞書を取得します。

シグネチャーの検査に便利です。

property cooldown¶

コマンドを実行したときのクールダウン。クールダウンが登録されていないコマンドの場合は None となります。

バージョン 2.0 で追加.

型: Optional[discord.app_commands.Cooldown]

property full_parent_name¶

完全修飾された親コマンド名を取得します。

これは実行に必要なベースコマンド名です。例えば、 ?one two three では親名は one two になります。

型: str

property parents¶

このコマンドの親を取得します。

親がない場合は、空の list を返します。

例えば、?a b c test では、親は [c, b, a] です。

バージョン 1.1 で追加.

型: List[Group]

property root_parent¶

このコマンドの大元の親を取得します。

親がない場合は、None を返します。

例えば、?a b c test では、親は a です。

型: Optional[Group]

property qualified_name¶

完全修飾されたコマンド名を取得します。

これは、コマンド名を含む完全な親名称です。例えば、 ?one two three の場合、完全修飾名は one two three となります。

型: str

is_on_cooldown(ctx, /)¶

コマンドが現在クールダウン中であるかどうかを確認します。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- コマンドのクールダウン状況を確認するときに使用する呼び出しコンテキスト。
戻り値: コマンドがクールダウン中かを示すbool値。
戻り値の型: bool

reset_cooldown(ctx, /)¶

このコマンドのクールダウンをリセットします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- クールダウンをリセットするための呼び出しコンテキスト。

get_cooldown_retry_after(ctx, /)¶

このコマンドを再試行できるまでの秒数を取得します。

バージョン 1.4 で追加.

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- クールダウンをリセットするための呼び出しコンテキスト。
戻り値: このコマンドのクールダウンの残り時間（秒）。これが 0.0 であれば、コマンドはクールダウン中ではありません。
戻り値の型: float

has_error_handler()¶: bool: コマンドにエラーハンドラが登録されているかどうかを確認します。

バージョン 1.7 で追加.

property cog_name¶

このコマンドが属するコグの名前があれば、その名前。

型: Optional[str]

property short_doc¶

コマンドの「短い」説明を取得します。

デフォルトでは、これは brief 属性です。属性値が空の文字列であれば、代わりに help 属性の最初の行が使われます。

型: str

property signature¶

POSIX のような書式テキストを返します。

型: str

await can_run(ctx, /)¶

This function is a coroutine.

checks 属性内のすべての関数をチェックすることで、コマンドが実行可能かどうかをチェックします。また、コマンドが無効かどうかもチェックします。

バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- 現在呼び出されているコマンドのコンテキスト。
例外: CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
戻り値: コマンドが呼び出し可能かどうかを示すbool値。
戻り値の型: bool

Group¶

Attributes

case_insensitive
clean_params
cog_name
commands
cooldown
full_parent_name
invoke_without_command
parents
qualified_name
root_parent
short_doc
signature

Methods

defadd_check
defadd_command
@after_invoke
@before_invoke
asynccan_run
@command
defcopy
@error
defget_command
defget_cooldown_retry_after
@group
defhas_error_handler
defis_on_cooldown
defremove_check
defremove_command
defreset_cooldown
defupdate
defwalk_commands

class discord.ext.commands.Group(*args, **kwargs)¶

サブコマンドとして実行されるコマンド用のgroupingプロトコルを実装したクラス。

このクラスは Command のサブクラスなので、 Command で使える関数も使えます。

invoke_without_command¶

サブコマンドが見つからなかった場合にのみ、グループコールバックが解析と呼び出しを開始するかどうかを示します。サブコマンドが見つからなかったこと、またはサブコマンドが見つからなかった場合に異なる機能を持つことをユーザに伝えるエラー処理関数にするのに便利です。これが False の場合、グループコールバックは常に最初に呼び出されます。つまり、パラメータによって決定されるチェックと解析が実行されます。デフォルトは False です。

型: bool

case_insensitive¶

グループのコマンドが大文字と小文字を区別する必要があるかどうかを示します。デフォルトは False です。

型: bool

@after_invoke¶

コルーチンを、実行後に呼び出すフックとして登録するデコレータ。

この実行後呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.after_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行後呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@before_invoke¶

渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。

この実行前呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.before_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行前呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@command(*args, **kwargs)¶

command() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
戻り値の型: Callable[..., Command]

@error¶

コルーチンをローカルエラーハンドラとして登録するデコレータです。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- ローカルエラーハンドラとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@group(*args, **kwargs)¶

group() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
戻り値の型: Callable[..., Group]

copy()¶

この Group のコピーを作成します。

戻り値: このグループの新しいインスタンス。
戻り値の型: Group

add_check(func, /)¶

コマンドにチェックを追加します。

これは check() に対する非デコレーターインターフェイスです。

バージョン 1.3 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

参考

check() デコレータ

パラメータ: func -- チェックとして使用される関数。

add_command(command, /)¶

Command を内部のコマンドリストに追加します。

これは通常、呼び出されません。代わりに command() か group() のショートカットデコレータが使われます。

バージョン 1.4 で変更: 一般的な ClientException の代わりに、 CommandRegistrationError を送出します。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ

command (Command) -- 追加するコマンド。

例外

CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
TypeError -- 渡されたコマンドが、 Command のサブクラスでない場合。

await can_run(ctx, /)¶

This function is a coroutine.

バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- 現在呼び出されているコマンドのコンテキスト。
例外: CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
戻り値: コマンドが呼び出し可能かどうかを示すbool値。
戻り値の型: bool

property clean_params¶

Dict[str, Parameter]: コンテキストまたは自己のパラメータなしでパラメータ辞書を取得します。

シグネチャーの検査に便利です。

property cog_name¶

このコマンドが属するコグの名前があれば、その名前。

型: Optional[str]

property commands¶

登録済みの、別名を含まないコマンドの集合。

型: Set[Command]

property cooldown¶

コマンドを実行したときのクールダウン。クールダウンが登録されていないコマンドの場合は None となります。

バージョン 2.0 で追加.

型: Optional[discord.app_commands.Cooldown]

property full_parent_name¶

完全修飾された親コマンド名を取得します。

これは実行に必要なベースコマンド名です。例えば、 ?one two three では親名は one two になります。

型: str

get_command(name, /)¶

内部のコマンドリストから検索し、 Command を取得します。

これはコマンドのエイリアスを取得する方法としても使用できます。

名前は修飾されていても構いません(例： 'foo bar' など)。サブコマンドが見つからなかった場合は、通常通り None が返されます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 取得するコマンドの名前。
戻り値: 要求されたコマンド。見つからなければ None を返します。
戻り値の型: Optional[Command]

get_cooldown_retry_after(ctx, /)¶

このコマンドを再試行できるまでの秒数を取得します。

バージョン 1.4 で追加.

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- クールダウンをリセットするための呼び出しコンテキスト。
戻り値: このコマンドのクールダウンの残り時間（秒）。これが 0.0 であれば、コマンドはクールダウン中ではありません。
戻り値の型: float

has_error_handler()¶: bool: コマンドにエラーハンドラが登録されているかどうかを確認します。

バージョン 1.7 で追加.

is_on_cooldown(ctx, /)¶

コマンドが現在クールダウン中であるかどうかを確認します。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- コマンドのクールダウン状況を確認するときに使用する呼び出しコンテキスト。
戻り値: コマンドがクールダウン中かを示すbool値。
戻り値の型: bool

property parents¶

このコマンドの親を取得します。

親がない場合は、空の list を返します。

例えば、?a b c test では、親は [c, b, a] です。

バージョン 1.1 で追加.

型: List[Group]

property qualified_name¶

完全修飾されたコマンド名を取得します。

これは、コマンド名を含む完全な親名称です。例えば、 ?one two three の場合、完全修飾名は one two three となります。

型: str

remove_check(func, /)¶

コマンドからチェックを削除します。

この関数は冪等性を保持しており、関数がグローバルチェックに含まれていない場合でも例外が発生しません。

バージョン 1.3 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ: func -- チェックから除去する関数。

remove_command(name, /)¶

内部のコマンドリストから該当するコマンドを検索し、その Command を除去します。

これはコマンドのエイリアスによって、コマンドを除去することもできます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 除去するコマンドの名前。
戻り値: 除去されたコマンド。有効な名前ではない場合は None が返されます。
戻り値の型: Optional[Command]

reset_cooldown(ctx, /)¶

このコマンドのクールダウンをリセットします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- クールダウンをリセットするための呼び出しコンテキスト。

property root_parent¶

このコマンドの大元の親を取得します。

親がない場合は、None を返します。

例えば、?a b c test では、親は a です。

型: Optional[Group]

property short_doc¶

コマンドの「短い」説明を取得します。

デフォルトでは、これは brief 属性です。属性値が空の文字列であれば、代わりに help 属性の最初の行が使われます。

型: str

property signature¶

POSIX のような書式テキストを返します。

型: str

update(**kwargs)¶

Command インスタンスを更新された属性で更新します。

for ... in walk_commands()¶

すべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。

バージョン 1.4 で変更: エイリアスによって重複した場合は、そのエイリアスまたはコマンドは返しません。

列挙: Union[Command, Group] -- コマンドの内部リストからの、コマンドまたはグループ。

GroupMixin¶

Attributes

all_commands
case_insensitive
commands

Methods

defadd_command
@command
defget_command
@group
defremove_command
defwalk_commands

class discord.ext.commands.GroupMixin(*args, **kwargs)¶

Group と同様に動作し、コマンドを登録可能なクラスの共通機能を実装したミックスイン。

all_commands¶

コマンド名の Command オブジェクトへのマッピング。

型: dict

case_insensitive¶

コマンドの大文字小文字を区別するかどうか。デフォルトは False です。

型: bool

@command(*args, **kwargs)¶

command() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
戻り値の型: Callable[..., Command]

@group(*args, **kwargs)¶

group() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
戻り値の型: Callable[..., Group]

property commands¶

登録済みの、別名を含まないコマンドの集合。

型: Set[Command]

add_command(command, /)¶

Command を内部のコマンドリストに追加します。

これは通常、呼び出されません。代わりに command() か group() のショートカットデコレータが使われます。

バージョン 1.4 で変更: 一般的な ClientException の代わりに、 CommandRegistrationError を送出します。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ

command (Command) -- 追加するコマンド。

例外

CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
TypeError -- 渡されたコマンドが、 Command のサブクラスでない場合。

remove_command(name, /)¶

内部のコマンドリストから該当するコマンドを検索し、その Command を除去します。

これはコマンドのエイリアスによって、コマンドを除去することもできます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 除去するコマンドの名前。
戻り値: 除去されたコマンド。有効な名前ではない場合は None が返されます。
戻り値の型: Optional[Command]

for ... in walk_commands()¶

すべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。

バージョン 1.4 で変更: エイリアスによって重複した場合は、そのエイリアスまたはコマンドは返しません。

列挙: Union[Command, Group] -- コマンドの内部リストからの、コマンドまたはグループ。

get_command(name, /)¶

内部のコマンドリストから検索し、 Command を取得します。

これはコマンドのエイリアスを取得する方法としても使用できます。

名前は修飾されていても構いません(例： 'foo bar' など)。サブコマンドが見つからなかった場合は、通常通り None が返されます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 取得するコマンドの名前。
戻り値: 要求されたコマンド。見つからなければ None を返します。
戻り値の型: Optional[Command]

HybridCommand¶

Methods

@after_invoke
@autocomplete
@before_invoke
asynccan_run
@error

class discord.ext.commands.HybridCommand(*args, **kwargs)¶

アプリケーションコマンドと通常のテキストコマンドの両方であるクラス。

これは通常の Command と同じパラメータや属性を有します。しかし、これは アプリケーションコマンド としても動作します。このため、コールバックはアプリケーションコマンドでサポートされるものでないといけません。

これらは手動では作成されず、デコレータまたは機能インターフェースを介して作成されます。

バージョン 2.0 で追加.

@after_invoke¶

コルーチンを、実行後に呼び出すフックとして登録するデコレータ。

この実行後呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.after_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行後呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@autocomplete(name)¶

パラメータのオートコンプリートに使用されるコルーチンを登録するデコレータ。

これは autocomplete() と同じです。これはアプリケーションコマンドにのみ適用され、通常のコマンドでは何もしません。

注釈

autocomplete() メソッドと同様に、 Context ではなく Interaction をパラメータとして取ります。

パラメータ: name (str) -- オートコンプリートに登録するパラメータ名。
例外: TypeError -- 渡されたコルーチンが実際にはコルーチンでない場合や、パラメータが見つからず、または無効な型であった場合。

@before_invoke¶

渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。

この実行前呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.before_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行前呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@error¶

コルーチンをローカルエラーハンドラとして登録するデコレータです。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- ローカルエラーハンドラとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

await can_run(ctx, /)¶

This function is a coroutine.

バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- 現在呼び出されているコマンドのコンテキスト。
例外: CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
戻り値: コマンドが呼び出し可能かどうかを示すbool値。
戻り値の型: bool

HybridGroup¶

Attributes

clean_params
cog_name
commands
cooldown
fallback
full_parent_name
parents
qualified_name
root_parent
short_doc
signature

Methods

defadd_check
defadd_command
@after_invoke
@autocomplete
@before_invoke
asynccan_run
@command
defcopy
@error
defget_command
defget_cooldown_retry_after
@group
defhas_error_handler
defis_on_cooldown
defremove_check
defremove_command
defreset_cooldown
defupdate
defwalk_commands

class discord.ext.commands.HybridGroup(*args, **kwargs)¶

アプリケーションコマンドグループと通常のテキストグループの両方であるクラス。

これは通常の Group と同じパラメータや属性を有します。しかし、これは アプリケーションコマンドグループ としても動作します。なお、アプリケーションコマンドグループにはコールバックを付けることはできないため、コールバックはアプリケーションコマンドとして呼び出されていない場合のみに呼び出されます。

ハイブリッドグループでは Group.invoke_without_command が常に True に設定されています。

これらは手動では作成されず、デコレータまたは機能インターフェースを介して作成されます。

バージョン 2.0 で追加.

fallback¶

アプリケーションコマンド用のフォールバックとして使用するコマンド名。アプリケーションコマンドグループを呼び出すことはできないため、これはグループ内に与えられたグループコールバックで呼び出すことのできるサブコマンドを作成します。 None の場合、フォールバックコマンドは指定されません。デフォルトは None です。

型: Optional[str]

@after_invoke¶

コルーチンを、実行後に呼び出すフックとして登録するデコレータ。

この実行後呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.after_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行後呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@autocomplete(name)¶

パラメータのオートコンプリートに使用されるコルーチンを登録するデコレータ。

これは autocomplete() と同じです。これはアプリケーションコマンドにのみ適用され、通常のコマンドでは何もしません。

これは、フォールバックアプリケーションコマンドが登録されている場合にのみ使用できます。

注釈

autocomplete() メソッドと同様に、 Context ではなく Interaction をパラメータとして取ります。

パラメータ: name (str) -- オートコンプリートに登録するパラメータ名。
例外: TypeError -- 渡されたコルーチンが実際にはコルーチンでない場合や、パラメータが見つからず、または無効な型であった場合。

@before_invoke¶

渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。

この実行前呼び出しフックは、 Context を単独の引数として取ります。

詳細は Bot.before_invoke() を参照してください。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- 実行前呼び出しフックとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@command(*args, **kwargs)¶

hybrid_command() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
戻り値の型: Callable[..., HybridCommand]

@error¶

コルーチンをローカルエラーハンドラとして登録するデコレータです。

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

パラメータ: coro (coroutine) -- ローカルエラーハンドラとして登録するコルーチン。
例外: TypeError -- 渡された関数がコルーチンではない場合。

@group(*args, **kwargs)¶

hybrid_group() を呼び出し、 add_command() を介して内部コマンドリストに追加するショートカットデコレータ。

戻り値: 提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
戻り値の型: Callable[..., HybridGroup]

await can_run(ctx, /)¶

This function is a coroutine.

バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- 現在呼び出されているコマンドのコンテキスト。
例外: CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
戻り値: コマンドが呼び出し可能かどうかを示すbool値。
戻り値の型: bool

add_check(func, /)¶

コマンドにチェックを追加します。

これは check() に対する非デコレーターインターフェイスです。

バージョン 1.3 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

参考

check() デコレータ

パラメータ: func -- チェックとして使用される関数。

add_command(command, /)¶

HybridCommand を内部のコマンドリストに追加します。

これは通常、呼び出されません。代わりに command() か group() のショートカットデコレータが使われます。

パラメータ

command (HybridCommand) -- 追加するコマンド。

例外

CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
TypeError -- 渡されたコマンドが、 HybridCommand のサブクラスでない場合。

property clean_params¶

Dict[str, Parameter]: コンテキストまたは自己のパラメータなしでパラメータ辞書を取得します。

シグネチャーの検査に便利です。

property cog_name¶

このコマンドが属するコグの名前があれば、その名前。

型: Optional[str]

property commands¶

登録済みの、別名を含まないコマンドの集合。

型: Set[Command]

property cooldown¶

コマンドを実行したときのクールダウン。クールダウンが登録されていないコマンドの場合は None となります。

バージョン 2.0 で追加.

型: Optional[discord.app_commands.Cooldown]

copy()¶

この Group のコピーを作成します。

戻り値: このグループの新しいインスタンス。
戻り値の型: Group

property full_parent_name¶

完全修飾された親コマンド名を取得します。

これは実行に必要なベースコマンド名です。例えば、 ?one two three では親名は one two になります。

型: str

get_command(name, /)¶

内部のコマンドリストから検索し、 Command を取得します。

これはコマンドのエイリアスを取得する方法としても使用できます。

名前は修飾されていても構いません(例： 'foo bar' など)。サブコマンドが見つからなかった場合は、通常通り None が返されます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 取得するコマンドの名前。
戻り値: 要求されたコマンド。見つからなければ None を返します。
戻り値の型: Optional[Command]

get_cooldown_retry_after(ctx, /)¶

このコマンドを再試行できるまでの秒数を取得します。

バージョン 1.4 で追加.

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- クールダウンをリセットするための呼び出しコンテキスト。
戻り値: このコマンドのクールダウンの残り時間（秒）。これが 0.0 であれば、コマンドはクールダウン中ではありません。
戻り値の型: float

has_error_handler()¶: bool: コマンドにエラーハンドラが登録されているかどうかを確認します。

バージョン 1.7 で追加.

is_on_cooldown(ctx, /)¶

コマンドが現在クールダウン中であるかどうかを確認します。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- コマンドのクールダウン状況を確認するときに使用する呼び出しコンテキスト。
戻り値: コマンドがクールダウン中かを示すbool値。
戻り値の型: bool

property parents¶

このコマンドの親を取得します。

親がない場合は、空の list を返します。

例えば、?a b c test では、親は [c, b, a] です。

バージョン 1.1 で追加.

型: List[Group]

property qualified_name¶

完全修飾されたコマンド名を取得します。

これは、コマンド名を含む完全な親名称です。例えば、 ?one two three の場合、完全修飾名は one two three となります。

型: str

remove_check(func, /)¶

コマンドからチェックを削除します。

この関数は冪等性を保持しており、関数がグローバルチェックに含まれていない場合でも例外が発生しません。

バージョン 1.3 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ: func -- チェックから除去する関数。

reset_cooldown(ctx, /)¶

このコマンドのクールダウンをリセットします。

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

パラメータ: ctx (Context) -- クールダウンをリセットするための呼び出しコンテキスト。

property root_parent¶

このコマンドの大元の親を取得します。

親がない場合は、None を返します。

例えば、?a b c test では、親は a です。

型: Optional[Group]

property short_doc¶

コマンドの「短い」説明を取得します。

デフォルトでは、これは brief 属性です。属性値が空の文字列であれば、代わりに help 属性の最初の行が使われます。

型: str

property signature¶

POSIX のような書式テキストを返します。

型: str

update(**kwargs)¶

Command インスタンスを更新された属性で更新します。

for ... in walk_commands()¶

すべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。

バージョン 1.4 で変更: エイリアスによって重複した場合は、そのエイリアスまたはコマンドは返しません。

列挙: Union[Command, Group] -- コマンドの内部リストからの、コマンドまたはグループ。

remove_command(name, /)¶

内部のコマンドリストから該当するコマンドを検索し、その Command を除去します。

これはコマンドのエイリアスによって、コマンドを除去することもできます。

バージョン 2.0 で変更: name 引数は位置限定引数になりました。

パラメータ: name (str) -- 除去するコマンドの名前。
戻り値: 除去されたコマンド。有効な名前ではない場合は None が返されます。
戻り値の型: Optional[Command]

Cogs¶

Cog¶

Attributes

app_command
description
qualified_name

Methods

clsCog.listener
defbot_check
defbot_check_once
asynccog_after_invoke
asynccog_app_command_error
asynccog_before_invoke
defcog_check
asynccog_command_error
asynccog_load
asynccog_unload
defget_app_commands
defget_commands
defget_listeners
defhas_app_command_error_handler
defhas_error_handler
defwalk_app_commands
defwalk_commands

class discord.ext.commands.Cog(*args, **kwargs)¶

すべてのコグが継承しなければならないベースクラス。

コグは、コマンドをまとめるのに役立つ、コマンド、リスナー、任意の状態の集まりです。詳細については、コグページを参照してください。

このクラスを継承する場合、 CogMeta に表示されているオプションもここで同様に有効です。

get_commands()¶

このコグ内で定義されているコマンドを返します。

これには discord.app_commands.Command や discord.app_commands.Group のインスタンスは 含まれません 。

戻り値: このコグ内で定義されているサブコマンドを含まない Command の list 。
戻り値の型: List[Command]

get_app_commands()¶

このコグ内で定義されているアプリケーションコマンドを返します。

戻り値: このコグ内で定義されている、サブコマンドを除いた discord.app_commands.Command と discord.app_commands.Group の list 。
戻り値の型: List[Union[discord.app_commands.Command, discord.app_commands.Group]]

property qualified_name¶

クラス名ではなく、コグの指定した名前を返します。

型: str

property description¶

コグの説明を返します。通常、クリーンな docstring を返します。

型: str

for ... in walk_commands()¶

このコグのすべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。

列挙: Union[Command, Group] -- コグ内のコマンドまたはグループ。

for ... in walk_app_commands()¶

このコグのすべてのアプリケーションコマンドとサブコマンドを、再帰的に網羅するイテレータ。

列挙: Union[discord.app_commands.Command, discord.app_commands.Group] -- コグのアプリケーションコマンドまたはグループ。

property app_command¶

このコグに関連付けられたグループを返します。

GroupCog から継承する場合にのみ使用できます。

型: Optional[discord.app_commands.Group]

get_listeners()¶

このコグで定義されている (コマンド名 , 関数) リスナーのペアの list を返します。

戻り値: このコグで定義されるリスナー。
戻り値の型: List[Tuple[str, coroutine]]

classmethod listener(name=...)¶

関数をリスナーとしてマークするデコレータ。

これはコグの Bot.listen() に相当するものです。

パラメータ: name (str) -- 受信するイベント名です。指定されていない場合は、関数の名前がデフォルトで使われます。
例外: TypeError -- 関数がコルーチンではないか、文字列が名前として渡されていません。

has_error_handler()¶: bool: コグにエラーハンドラが登録されているかどうかをチェックします。

バージョン 1.7 で追加.

has_app_command_error_handler()¶: bool: Checks whether the cog has an app error handler.

バージョン 2.1 で追加.

await cog_load()¶

This function could be a coroutine.

コグが読み込まれた際に呼び出される特別なメソッド。

サブクラスは特別な非同期読み込み動作が必要な場合にこれを置き換えなければなりません。特別な __init__ メソッドは、その中で非同期コードを実行することを許可しないので、これは非同期な必要があるコードを設定することに役立つ、ということに注意してください。

バージョン 2.0 で追加.

await cog_unload()¶

This function could be a coroutine.

コグが削除された際に呼び出される特別なメソッド。

サブクラスは特別なアンロード動作が必要な場合にこれを置き換えなければなりません。

バージョン 2.0 で変更: このメソッドは現在 coroutine になりました。

bot_check_once(ctx)¶

Bot.check_once() チェックとして登録する特別なメソッド。

この関数はコルーチンであり、 Context を表すために唯一のパラメータである ctx を取る必要があります。

bot_check(ctx)¶

Bot.check() チェックとして登録する特別なメソッド。

この関数はコルーチンであり、 Context を表すために唯一のパラメータである ctx を取る必要があります。

cog_check(ctx)¶

このコグのすべてのコマンドとサブコマンドに対して check() として登録する特別なメソッド。

この関数はコルーチンであり、 Context を表すために唯一のパラメータである ctx を取る必要があります。

await cog_command_error(ctx, error)¶

This function is a coroutine.

このコグ内でエラーが発生するたびに呼び出される特別なメソッド。

これは on_command_error() に似ていますが、コグ内のコマンドにのみ適用されます。

コルーチンでなければなりません。

パラメータ

ctx (Context) -- エラーが発生した呼び出しコンテキスト。
error (CommandError) -- 発生したエラー

await cog_app_command_error(interaction, error)¶

This function is a coroutine.

このコグ内でアプリケーションコマンドのエラーが発生するたびに呼び出される特別なメソッド。

これは discord.app_commands.CommandTree.on_error() に似ていますが、コグ内のアプリケーションコマンドにのみ適用されます。

コルーチンでなければなりません。

パラメータ

interaction (Interaction) -- 処理中のインタラクション。
error (AppCommandError) -- 発生した例外。

await cog_before_invoke(ctx)¶

This function is a coroutine.

コグのローカル事前呼び出しフックとして機能する特別なメソッド。

これは Command.before_invoke() に似ています。

コルーチンでなければなりません。

パラメータ: ctx (Context) -- 呼び出しコンテキスト。

await cog_after_invoke(ctx)¶

This function is a coroutine.

コグのローカルポスト呼び出しフックとして機能する特別なメソッド。

これは Command.after_invoke() に似ています。

コルーチンでなければなりません。

パラメータ: ctx (Context) -- 呼び出しコンテキスト。

GroupCog¶

class discord.ext.commands.GroupCog(*args, **kwargs)¶

この中で定義されたアプリケーションコマンドの親 discord.app_commands.Group としても機能するコグ。

これは Cog から継承され、 CogMeta のオプションもこれに適用されます。メソッドについては Cog ドキュメントを参照してください。

guild_only() 、 guilds() 、 default_permissions() のようなデコレータはコグの上に使用されている場合、グループに適用されます。

Hybrid commands will also be added to the Group, giving the ability categorize slash commands into groups, while keeping the prefix-style command as a root-level command.

例：

from discord import app_commands
from discord.ext import commands

@app_commands.guild_only()
class MyCog(commands.GroupCog, group_name='my-cog'):
    pass

バージョン 2.0 で追加.

CogMeta¶

Attributes

command_attrs
description
group_auto_locale_strings
group_description
group_extras
group_name
group_nsfw
name

class discord.ext.commands.CogMeta(*args, **kwargs)¶

コグを定義するメタクラス。

これを直接使うべきではないということに注意してください。これは、 abc.ABCMeta のような他のメタクラスと相互に混在させるカスタムメタクラスとして説明する目的だけで公開されています。

たとえば、抽象的なコグのミックスインのクラスを作成するには、次のようにします。

import abc

class CogABCMeta(commands.CogMeta, abc.ABCMeta):
    pass

class SomeMixin(metaclass=abc.ABCMeta):
    pass

class SomeCogMixin(SomeMixin, commands.Cog, metaclass=CogABCMeta):
    pass

注釈

以下に文書化されているメタクラスの属性を渡す場合、次の例のように、キーワードのみの引数としてクラスの作成に渡す必要があることに注意してください:

class MyCog(commands.Cog, name='My Cog'):
    pass

name¶

コグの名前。デフォルトではクラス名そのままになります。

型: str

description¶

コグの説明。デフォルトでは、綺麗にされたクラスのdocstringになります。

バージョン 1.6 で追加.

型: str

command_attrs¶

このコグ内のすべてのコマンドに適用される属性のリスト。辞書は Command オプションの __init__ に渡されます。クラス内の command 属性内で属性を指定すると、この属性内で指定された属性を上書きします。例えば:

class MyCog(commands.Cog, command_attrs=dict(hidden=True)):
    @commands.command()
    async def foo(self, ctx):
        pass # hidden -> True

    @commands.command(hidden=False)
    async def bar(self, ctx):
        pass # hidden -> False

型: dict

group_name¶

コグのグループ名。これは GroupCog インスタンスにのみ適用されます。デフォルトでは、 name と同じ値です。

バージョン 2.0 で追加.

型: Union[str, locale_str]

group_description¶

コグのグループ説明。これは GroupCog インスタンスにのみ適用されます。デフォルトでは、 description と同じ値です。

バージョン 2.0 で追加.

型: Union[str, locale_str]

group_nsfw¶

アプリケーションコマンドグループに年齢制限をかけるか。これは GroupCog インスタンスにのみ適用されます。デフォルトでは False です。

バージョン 2.0 で追加.

型: bool

group_auto_locale_strings¶

これが True に設定されている場合、翻訳可能な文字列は str ではなく暗黙的に locale_str にラップされます。デフォルトは True です。

バージョン 2.0 で追加.

型: bool

group_extras¶

追加のデータを保管できる辞書型。これは GroupCog インスタンスにのみ適用されます。ライブラリは辞書型の中のキーや値を一切操作しません。

バージョン 2.1 で追加.

型: dict

ヘルプコマンド¶

HelpCommand¶

Attributes

cog
command_attrs
context
invoked_with
show_hidden
verify_checks

Methods

defadd_check
asynccommand_callback
defcommand_not_found
asyncfilter_commands
defget_bot_mapping
defget_command_signature
defget_destination
defget_max_size
asyncon_help_command_error
asyncprepare_help_command
defremove_check
defremove_mentions
asyncsend_bot_help
asyncsend_cog_help
asyncsend_command_help
asyncsend_error_message
asyncsend_group_help
defsubcommand_not_found

class discord.ext.commands.HelpCommand(*args, **kwargs)¶

ヘルプコマンドの書式設定のための基本的実装。

注釈

内部的にこのクラスのインスタンスは、 GH-2123 に記載されている競合状態を防ぐため、コマンド自体が呼び出されるたびにディープコピーされます。

つまり、このクラスの状態に依存してコマンドの呼び出しが同じになると、期待どおりに動作しないということです。

context¶

このヘルプを整形するクラスを呼び出したコンテキストです。これは一般的にヘルプコマンドが割り当てられ、command_callback() が呼び出された後に設定されます。

型: Optional[Context]

show_hidden¶

隠しコマンドを表示するかどうかを指定します。デフォルトでは False です。

型: bool

verify_checks¶

コマンドが、 Command.checks を呼び出し検証すべきかを指定します。もし True なら、常に Command.checks を呼び出します。もし None なら、ギルドでのみ Command.checks を呼び出します。もし False なら、 Command.checks は一切呼び出しません。デフォルトは True です。

バージョン 1.7 で変更.

型: Optional[bool]

command_attrs¶

ヘルプコマンドの構築のために渡すオプションの辞書。これにより、実際にヘルプコマンドの実装を変更することなく、その動作を変更できます。属性は Command コンストラクタで渡されたものと同じになります。

型: dict

add_check(func, /)¶

ヘルプコマンドにチェックを追加します。

バージョン 1.4 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

参考

check() デコレータ

パラメータ: func -- チェックとして使用される関数。

remove_check(func, /)¶

ヘルプコマンドからチェックを除去します。

この関数は冪等性を保持しており、関数がグローバルチェックに含まれていない場合でも例外が発生しません。

バージョン 1.4 で追加.

バージョン 2.0 で変更: func 引数は位置限定引数になりました。

パラメータ: func -- チェックから除去する関数。

get_bot_mapping()¶: send_bot_help() に渡されたボットのマッピングを取得します。

property invoked_with¶

Context.send_help() が使われた場合にちゃんと処理することを除いて、Context.invoked_with と同様です。

ヘルプコマンドが標準的に使われたならば、これは Context.invoked_with を返します。そうではなく、もしヘルプコマンドが Context.send_help() を用いて呼び出されたなら、その時はヘルプコマンドの内部的なコマンド名を返します。

戻り値: この実行を引き起こしたコマンド名。
戻り値の型: Optional[str]

get_command_signature(command, /)¶

ヘルプページに表示される、コマンドの使用方法を示す文字列を返します。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ: command (Command) -- 使用方法を取得したいコマンド。
戻り値: コマンドの使用方法を示す文字列。
戻り値の型: str

remove_mentions(string, /)¶

不正使用を防ぐために文字列からメンションを除去します。

これには @everyone 、 @here 、メンバーメンションとロールメンションが含まれます。

バージョン 2.0 で変更: string 引数は位置限定引数になりました。

戻り値: メンションが除去された文字列。
戻り値の型: str

property cog¶

ヘルプコマンドのコグを取得または設定するためのプロパティ。

ヘルプコマンドにコグが設定されている場合は、ヘルプコマンドがそのコグに属している場合と同様です。コグの特別なメソッドはすべてヘルプコマンドに適用され、アンロード時に自動的にアンロードされます。

コグをヘルプコマンドから解除するには、None を設定します。

戻り値: ヘルプコマンドに現在設定されているコグ。
戻り値の型: Optional[bool]

command_not_found(string, /)¶

This function could be a coroutine.

ヘルプコマンドでコマンドが見つからない場合に呼び出されるメソッド。これは、i18nでオーバーライドするのに便利です。

デフォルトは No command called {0} found. です。

バージョン 2.0 で変更: string 引数は位置限定引数になりました。

パラメータ: string (str) -- 不正なコマンドを含む文字列。不正使用を防ぐためにメンションが削除されていることに注意してください。
戻り値: コマンドが見つからないときに使用する文字列。
戻り値の型: str

subcommand_not_found(command, string, /)¶

This function could be a coroutine.

ヘルプコマンドでコマンドが要求されたサブコマンドを持っていない場合に呼び出されるメソッド。これは、i18nでオーバーライドするのに便利です。

デフォルトは以下のどちらかです:

'Command "{command.qualified_name}" has no subcommands.'
- command パラメータにサブコマンドがない場合。
'Command "{command.qualified_name}" has no subcommand named {string}'
- command パラメータにサブコマンドはあるが、string という名前のものがない場合。

バージョン 2.0 で変更: command と string のパラメータは位置指定のみになりました。

パラメータ

command (Command) -- そのサブコマンドを持っていなかった要求されたコマンド。
string (str) -- 不正なサブコマンドを含む文字列。不正使用を防ぐためにメンションが削除されていることに注意してください。

戻り値

要求されたコマンドがそのサブコマンドを持っていなかった時に使われる文字列。

戻り値の型

str

await filter_commands(commands, /, *, sort=False, key=None)¶

This function is a coroutine.

フィルタリングされたコマンドのリストを返し、必要に応じて並び替えます。

これは verify_checks と show_hidden 属性を考慮します。

バージョン 2.0 で変更: commands 引数は位置限定引数になりました。

パラメータ

commands (Iterable[Command]) -- フィルタリングされるコマンドのイテラブル。
sort (bool) -- 結果を並び替えるかどうか。
key (Optional[Callable[[Command], Any]]) -- Command を唯一のパラメータとして取る、 sorted() に渡す任意のキー関数。 sort が True として渡された場合、これはコマンド名としてデフォルトになります。

戻り値

フィルタを通過したコマンドのリスト。

戻り値の型

List[Command]

get_max_size(commands, /)¶

指定されたコマンドリストの中の名前の最大の長さを返します。

バージョン 2.0 で変更: commands 引数は位置限定引数になりました。

パラメータ: commands (Sequence[Command]) -- 最大の長さをチェックするコマンドのシーケンス。
戻り値: コマンドの最大の幅。
戻り値の型: int

get_destination()¶

ヘルプコマンドが出力される Messageable を返します。

このメソッドをオーバーライドして動作をカスタマイズできます。

デフォルトでは、コンテキストのチャンネルを返します。

戻り値: ヘルプコマンドの出力先。
戻り値の型: abc.Messageable

await send_error_message(error, /)¶

This function is a coroutine.

ヘルプコマンドでエラーが発生したときにその実装を処理します。例えば、 command_not_found() の結果がここに渡されます。

このメソッドをオーバーライドして動作をカスタマイズできます。

デフォルトでは、これは get_destination() で指定された宛先にエラーメッセージを送信します。

注釈

HelpCommand.context で呼び出しコンテキストにアクセスできます。

バージョン 2.0 で変更: error 引数は位置限定引数になりました。

パラメータ: error (str) -- ユーザーに表示されるエラーメッセージ。これは、メンションが不正使用を防ぐために削除されていることに注意してください。

await on_help_command_error(ctx, error, /)¶

This function is a coroutine.

ヘルプコマンドのエラーハンドラはエラーハンドリングで指定されています。

エラーハンドラが呼び出されたときに特定の動作が必要な場合にオーバーライドするのに便利です。

デフォルトでは、このメソッドは何もせず、単にデフォルトのエラーハンドラに伝播します。

バージョン 2.0 で変更: bot と msg 引数は位置限定引数になりました。

パラメータ

ctx (Context) -- 呼び出しコンテキスト。
error (CommandError) -- 発生したエラー。

await send_bot_help(mapping, /)¶

This function is a coroutine.

ボットのコマンドページの実装をヘルプコマンドで処理します。この関数は、引数なしでヘルプコマンドが呼び出されたときに呼び出されます。

このメソッドは何も返さないことに注意してください -- むしろ実際のメッセージ送信はこのメソッド内で行う必要があります。適切な振る舞いをするサブクラスは、他のユーザ向けにカスタマイズする箇所であるため、どこに送信するかを知るために get_destination() を使用する必要があります。

このメソッドをオーバーライドして動作をカスタマイズできます。

注釈

HelpCommand.context で呼び出しコンテキストにアクセスできます。

また、マッピング内のコマンドはフィルタリングされません。フィルタリングを行うには、 filter_commands() を自分で呼び出す必要があります。

バージョン 2.0 で変更: mapping 引数は位置限定引数になりました。

パラメータ: mapping (Mapping[Optional[Cog], List[Command]]) -- ヘルプのためにユーザーから要求されたコマンドへのコグのマッピング。マッピングのキーはコマンドが属する Cog です。値がない場合は None になり、そのコグに属するコマンドのリストになります。

await send_cog_help(cog, /)¶

This function is a coroutine.

ヘルプコマンドでコグページの実装を処理します。この関数は、ヘルプコマンドがコグを引数として呼び出されたときに呼び出されます。

このメソッドをオーバーライドして動作をカスタマイズできます。

注釈

HelpCommand.context で呼び出しコンテキストにアクセスできます。

このコグに属するコマンドを取得するには、 Cog.get_commands() を確認してください。返されるコマンドはフィルタリングされていません。フィルタリングをするには、自分で filter_commands() を呼び出す必要があるでしょう。

バージョン 2.0 で変更: cog 引数は位置限定引数になりました。

パラメータ: cog (Cog) -- ヘルプを要求されたコグ。

await send_group_help(group, /)¶

This function is a coroutine.

ヘルプコマンドでグループページの実装を処理します。この関数は、ヘルプコマンドがグループを引数として呼び出されたときに呼び出されます。

このメソッドをオーバーライドして動作をカスタマイズできます。

注釈

HelpCommand.context で呼び出しコンテキストにアクセスできます。

このコグに属するコマンドを別名を除いて取得するには、 Group.commands を確認してください。返されるコマンドはフィルタリングされていません。フィルタリングをするには、自分で filter_commands() を呼び出す必要があるでしょう。

バージョン 2.0 で変更: group 引数は位置限定引数になりました。

パラメータ: group (Group) -- ヘルプを要求されたグループ。

await send_command_help(command, /)¶

This function is a coroutine.

ヘルプコマンドで単一のコマンドページの実装を処理します。

このメソッドをオーバーライドして動作をカスタマイズできます。

注釈

HelpCommand.context で呼び出しコンテキストにアクセスできます。

ヘルプを表示

以下のような、ヘルプコマンドに役立つ属性やメソッドがあります。

Command.help
Command.brief
Command.short_doc
Command.description
get_command_signature()

これら以外にももっと属性はありますが、欲しい出力を得るのを助けてくれるこいつらで遊ぶことに開放感を感じてみてください。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ: command (Command) -- ヘルプを要求されたコマンド。

await prepare_help_command(ctx, command=None, /)¶

This function is a coroutine.

ヘルプコマンドを準備するのに使用できる低レベルのメソッドです。例えば、コマンドが処理する前にサブクラスの状態を準備する必要がある場合は、ここで行うことができます。

デフォルトの実装では何もしません。

注釈

これは内部ヘルプコマンドコールバック本体と呼ばれていますので、内部で発生する通常のルールはすべてここでも適用されます。

バージョン 2.0 で変更: ctx と command 引数は位置限定引数になりました。

パラメータ

ctx (Context) -- 呼び出しコンテキスト。
command (Optional[str]) -- ヘルプコマンドに渡される引数。

await command_callback(ctx, /, *, command=None)¶

This function is a coroutine.

ヘルプコマンドの実際の実装。

このメソッドをオーバーライドして、実際にディスパッチされるメソッドを通じて動作を変更することは推奨されません。

send_bot_help()
send_cog_help()
send_group_help()
send_command_help()
get_destination()
command_not_found()
subcommand_not_found()
send_error_message()
on_help_command_error()
prepare_help_command()

バージョン 2.0 で変更: ctx パラメータは位置指定のみになりました。

DefaultHelpCommand¶

Attributes

arguments_heading
commands_heading
default_argument_description
dm_help
dm_help_threshold
indent
no_category
paginator
show_parameter_descriptions
sort_commands
width

Methods

defadd_command_arguments
defadd_command_formatting
defadd_indented_commands
defget_command_signature
defget_destination
defget_ending_note
asyncsend_pages
defshorten_text

class discord.ext.commands.DefaultHelpCommand(*args, **kwargs)¶

デフォルトのヘルプコマンドの実装。

これは HelpCommand から継承されます。

以下の属性で拡張されます。

width¶

1行に収める最大の文字数を指定します。デフォルトでは80です。

型: int

sort_commands¶

出力されるコマンドをアルファベット順に並べ替えるかどうか。デフォルトは True です。

型: bool

dm_help¶

ヘルプコマンドが、受信したチャンネルに送信する代わりにユーザのDMに送信するかどうかを示す三値論理値。ブール値が True に設定されている場合、すべてのヘルプ出力は DMに送信されます。 False の場合、いずれのヘルプ出力もDMには送信されません。 None の場合、ボットはヘルプメッセージが長すぎる場合にのみDMに送信します( dm_help_threshold の文字数以上で決定されます)。デフォルトは False です。

型: Optional[bool]

dm_help_threshold¶

dm_help が None に設定されているときに、ペジネーターがユーザのDMに送信するのに必要な文字数。デフォルトは 1000 です。

型: Optional[int]

indent¶

見出しからのコマンドのインデントの量。デフォルトは 2 です。

型: int

arguments_heading¶

コマンド名を指定してhelpコマンドを実行したときに使用される引数リストの見出し文字列です。国際化対応に便利です。デフォルトは "Arguments:" です。show_parameter_descriptions が True の場合に表示されます。

バージョン 2.0 で追加.

型: str

show_parameter_descriptions¶

パラメータの説明を表示するかどうか。デフォルトは True です。False に設定すると、代わりに signature が表示されるようになります。

バージョン 2.0 で追加.

型: bool

commands_heading¶

ヘルプコマンドがカテゴリ名で呼び出されたときに使用されるコマンドリストの見出し文字列。i18nに便利です。デフォルトは "Commands:" です。

型: str

default_argument_description¶

引数の description が None である場合に使用される、デフォルトの引数の説明文字列です。国際化対応に便利です。デフォルトは "No description given." です。

バージョン 2.0 で追加.

型: str

no_category¶

任意のカテゴリ(コグ) に属さないコマンドがある場合に使用される文字列。i18nに便利です。デフォルトは "No Category" です。

型: str

paginator¶

ヘルプコマンドの出力にページ番号を付けるために使用されるペジネーター。

型: Paginator

shorten_text(text, /)¶: str：渡された文字列を、 width に収まるよう省略します。

バージョン 2.0 で変更: text 引数は位置限定引数になりました。

get_ending_note()¶: str: Helpコマンドの末尾の文字列を返します。主に翻訳する際にオーバーライドしてください。

get_command_signature(command, /)¶

ヘルプページに表示される、コマンドの使用方法を示す文字列を返します。

show_parameter_descriptions が False の場合に get_command_signature() を呼び出し、それ以外の場合はコマンドパラメータを表示しない修正したシグネチャを返します。

バージョン 2.0 で追加.

パラメータ: command (Command) -- 使用方法を取得したいコマンド。
戻り値: コマンドの使用方法を示す文字列。
戻り値の型: str

add_indented_commands(commands, /, *, heading, max_size=None)¶

指定した見出しの後の、コマンドのリストをインデントします。

書式は paginator に追加されます。

デフォルトの実装は indent の空白でインデントされ、コマンドの Command.short_doc に先立って max_size まで肉付けされ、 width に沿うように縮められたコマンド名です。

バージョン 2.0 で変更: commands 引数は位置限定引数になりました。

パラメータ

commands (Sequence[Command]) -- 出力にてインデントするコマンドのリスト。
heading (str) -- 出力に追加する見出し。これはコマンドのリストが 0 より大きい場合にのみ追加されます。
max_size (Optional[int]) -- インデント間の差分に使用する最大サイズです。指定されていない場合は、 get_max_size() をコマンドパラメータとして呼び出します。

add_command_arguments(command, /)¶

コマンドの引数のリストを arguments_heading の後にインデントします。

デフォルトの実装では、引数の name は indent の量のスペースでインデントされ、引数の description または default_argument_description が後に続くよう get_max_size() を用いて max_size にパディングされ、そして引数の width と displayed_default の間に () があれば、その後に入るように短縮されます。

バージョン 2.0 で追加.

パラメータ: command (Command) -- 引数の一覧を表示するコマンド。

await send_pages()¶

This function is a coroutine.

paginator から出力されたページを宛先に送信するためのヘルパーユーティリティ。

add_command_formatting(command, /)¶

コマンドとグループのインデントされていないブロックをフォーマットするユーティリティ関数。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

バージョン 2.0 で変更: add_command_arguments() は show_parameter_descriptions が True であれば呼び出されるようになりました。

パラメータ: command (Command) -- フォーマットするコマンド。

get_destination()¶

ヘルプコマンドが出力される Messageable を返します。

このメソッドをオーバーライドして動作をカスタマイズできます。

デフォルトでは、コンテキストのチャンネルを返します。

戻り値: ヘルプコマンドの出力先。
戻り値の型: abc.Messageable

MinimalHelpCommand¶

Attributes

aliases_heading
commands_heading
dm_help
dm_help_threshold
no_category
paginator
sort_commands

Methods

defadd_aliases_formatting
defadd_bot_commands_formatting
defadd_command_formatting
defadd_subcommand_formatting
defget_command_signature
defget_destination
defget_ending_note
defget_opening_note
asyncsend_pages

class discord.ext.commands.MinimalHelpCommand(*args, **kwargs)¶

最小限の出力を持つヘルプコマンドの実装。

これは HelpCommand から継承されます。

sort_commands¶

出力されるコマンドをアルファベット順に並べ替えるかどうか。デフォルトは True です。

型: bool

commands_heading¶

ヘルプコマンドがカテゴリ名で呼び出されたときに使用されるコマンドリストの見出し文字列。i18nに便利です。デフォルトは "Commands" です。

型: str

aliases_heading¶

コマンドのエイリアスを列挙するために使用するエイリアス一覧のの見出し文字列。i18nに便利です。デフォルトでは "Aliases:" です。

型: str

dm_help¶

型: Optional[bool]

dm_help_threshold¶

dm_help が None に設定されているときに、ペジネーターがユーザのDMに送信するのに必要な文字数。デフォルトは 1000 です。

型: Optional[int]

no_category¶

任意のカテゴリ(コグ) に属さないコマンドがある場合に使用される文字列。i18nに便利です。デフォルトは "No Category" です。

型: str

paginator¶

ヘルプコマンドの出力にページ番号を付けるために使用されるペジネーター。

型: Paginator

await send_pages()¶

This function is a coroutine.

paginator から出力されたページを宛先に送信するためのヘルパーユーティリティ。

get_opening_note()¶

ヘルプコマンドの冒頭の文字列を返します。主に翻訳する際にオーバーライドしてください。

デフォルトの実装では次を返します

Use `{prefix}{command_name} [command]` for more info on a command.
You can also use `{prefix}{command_name} [category]` for more info on a category.

戻り値: ヘルプコマンドの冒頭の文字列。
戻り値の型: str

get_command_signature(command, /)¶

ヘルプページに表示される、コマンドの使用方法を示す文字列を返します。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ: command (Command) -- 使用方法を取得したいコマンド。
戻り値: コマンドの使用方法を示す文字列。
戻り値の型: str

get_ending_note()¶

ヘルプコマンドの末尾の文字列を返します。主に翻訳する際にオーバーライドしてください。

デフォルトの実装では何もしません。

戻り値: ヘルプコマンドの末尾の文字列。
戻り値の型: str

add_bot_commands_formatting(commands, heading, /)¶

出力に小さなボットの見出しとコマンドを追加します。

書式は paginator に追加すべきです。

デフォルトの実装では、太字の下線の見出しに続いて、次の行にEN スペース (U+2002) で区切られたコマンドが出力されます。

バージョン 2.0 で変更: commands と heading 引数は位置限定引数になりました。

パラメータ

commands (Sequence[Command]) -- この見出しに属するコマンドのリスト。
heading (str) -- 行に追加する見出し。

add_subcommand_formatting(command, /)¶

サブコマンドの書式情報を追加します。

書式は paginator に追加すべきです。

デフォルトの実装ではプレフィックスと、 Command.qualified_name の後にEn ダッシュとコマンドの Command.short_doc が追加されます。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ: command (Command) -- 情報を表示するコマンド。

add_aliases_formatting(aliases, /)¶

コマンドのエイリアスの書式情報を追加します。

書式は paginator に追加すべきです。

デフォルトの実装では、太字の aliases_heading の後にカンマで区切られたエイリアスの一覧が出力されます。

フォーマットするエイリアスがない場合は呼び出されません。

バージョン 2.0 で変更: 引数 aliases は位置専用引数となりました。

パラメータ: aliases (Sequence[str]) -- フォーマットするエイリアスのリスト。

add_command_formatting(command, /)¶

コマンドとグループをフォーマットするユーティリティ関数。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ: command (Command) -- フォーマットするコマンド。

get_destination()¶

ヘルプコマンドが出力される Messageable を返します。

このメソッドをオーバーライドして動作をカスタマイズできます。

デフォルトでは、コンテキストのチャンネルを返します。

戻り値: ヘルプコマンドの出力先。
戻り値の型: abc.Messageable

Paginator¶

Attributes

linesep
max_size
pages
prefix
suffix

Methods

defadd_line
defclear
defclose_page

class discord.ext.commands.Paginator(prefix='```', suffix='```', max_size=2000, linesep='\n')¶

Discordメッセージのコードブロックをページに分割するのに役立つクラス。

len(x): ペジネーター内の文字数の合計を返します。

prefix¶

存在する場合、毎ページに挿入されるプレフィックス。例: バックティック3個。

型: Optional[str]

suffix¶

存在する場合、毎ページの末尾に挿入されるサフィックス。例: バックティック3個。

型: Optional[str]

max_size¶

ページ内で許可されるコードポイントの最大数。

型: int

linesep¶

行間に挿入される文字列。例: 改行文字。: バージョン 1.7 で追加.

型: str

clear()¶: ページネーターのページを消去します。

add_line(line='', *, empty=False)¶

現在のページに行を追加します。

行が max_size を超えると、例外が発生します。

パラメータ

line (str) -- 追加する行。
empty (bool) -- 別に空行を追加するかどうかを示します。

例外

RuntimeError -- 現在の max_size に対し行が大きすぎる場合。

close_page()¶: ページを改めます。

property pages¶

レンダリングされたページの一覧を返します。

型: List[str]

列挙型¶

class discord.ext.commands.BucketType¶

クールダウンなどに使用するバケットの種類を指定します。

default¶: デフォルトのバケットはグローバル基準で動作します。

user¶: ユーザーバケットは、ユーザーごとに動作します。

guild¶: ギルドバケットは、ギルドごとに動作します。

channel¶: チャンネルバケットは、チャンネルごとに動作します。

member¶: メンバーバケットは、メンバーごとに動作します。

category¶: カテゴリバケットは、カテゴリごとに動作します。

role¶: ロールバケットは、ロールごとに動作します。

バージョン 1.3 で追加.

Checks¶

@discord.ext.commands.check(predicate)¶

Command またはそのサブクラスにチェックを追加するデコレータ。これらのチェックは Command.checks 経由でアクセスできます。

これらのチェックは唯一の引数 Context を取る関数であるべきです。もしチェックが False のような値を返せば、呼び出し中に CheckFailure が発生され on_command_error() に送られます。

もし関数内で例外が発生するとしたら、それは CommandError のサブクラスであるべきです。これらのサブクラスが on_command_error() に送られるのに対し、それから継承されていないどんな例外も、伝播します。

predicate という特別な属性は、デコレータから返された値にバインドされ、デコレータに渡された関数を取得します。これにより、次のイントロスペクションとチェーンを行うことができます:

def owner_or_permissions(**perms):
    original = commands.has_permissions(**perms).predicate
    async def extended_check(ctx):
        if ctx.guild is None:
            return False
        return ctx.guild.owner_id == ctx.author.id or await original(ctx)
    return commands.check(extended_check)

注釈

predicate によって返される関数は、たとえ元の関数がコルーチンでなくても、常にコルーチンです。

バージョン 1.3 で変更: predicate 属性が追加されました。

サンプル

コマンドを呼び出したのがあなたであるかどうかを確認するための基本的なチェックの作成。

def check_if_it_is_me(ctx):
    return ctx.message.author.id == 85309593344815104

@bot.command()
@commands.check(check_if_it_is_me)
async def only_for_me(ctx):
    await ctx.send('I know you!')

一般的なチェックを独自のデコレータに変換します:

def is_me():
    def predicate(ctx):
        return ctx.message.author.id == 85309593344815104
    return commands.check(predicate)

@bot.command()
@is_me()
async def only_me(ctx):
    await ctx.send('Only you!')

バージョン 2.0 で変更: predicate 引数は位置限定引数になりました。

パラメータ: predicate (Callable[[Context], bool]) -- コマンドが呼び出されるかどうかをチェックする関数。

@discord.ext.commands.check_any(*checks)¶

渡されたチェックのいずれかが合格するか、すなわち論理ORを使用するかをチェックする追加された check() 。

すべてのチェックに失敗した場合、 CheckAnyFailure が発生して失敗したことを通知します。これは CheckFailure を継承します。

注釈

この関数の predicate 属性は**コルーチン**です。

バージョン 1.3 で追加.

パラメータ: *checks (Callable[[Context], bool]) -- check() デコレータで装飾されたチェックの引数リスト。
例外: TypeError -- 渡されたチェックが check() デコレータで装飾されていません。

サンプル

ボットの所有者かサーバーの所有者かを確認するための基本的なチェックの作成なら:

def is_guild_owner():
    def predicate(ctx):
        return ctx.guild is not None and ctx.guild.owner_id == ctx.author.id
    return commands.check(predicate)

@bot.command()
@commands.check_any(commands.is_owner(), is_guild_owner())
async def only_for_owners(ctx):
    await ctx.send('Hello mister owner!')

@discord.ext.commands.has_role(item)¶

コマンドを呼び出したメンバーが、指定された名前またはIDのロールを持っているかどうかのチェックを追加する check() 。

文字列が指定された場合は、大文字やつづりを含めロールの名前を正確に指定する必要があります。

整数が指定されている場合は、ロールの正確なsnowflake IDを指定する必要があります。

メッセージがプライベートメッセージのコンテキストで呼び出された場合、チェックは False を返します。

このチェックは２つの特別な例外のうち１つ、もしユーザがロールを持っていないなら MissingRole を、プライベートメッセージで使用されたなら NoPrivateMessage を発生します。どちらも CheckFailure を継承します。

バージョン 1.1 で変更: 一般的な CheckFailure の代わりに MissingRole または NoPrivateMessage を発生させます。

バージョン 2.0 で変更: item 引数は位置限定引数になりました。

パラメータ: item (Union[int, str]) -- チェックするロールの名前またはID。

@discord.ext.commands.has_permissions(**perms)¶

メンバーが必要なすべての権限を持っているかどうかのチェックを追加する check() 。

このチェックはギルド全体の権限ではなく、現在のチャンネルの権限で動作することに注意してください。

渡された権限は、 discord.Permissions のプロパティとまったく同じでなければなりません。

このチェックは特別な例外であり、 CheckFailure から継承されている MissingPermissions を発生します。

パラメータ: perms -- チェックする権限の引数のリスト。

サンプル

@bot.command()
@commands.has_permissions(manage_messages=True)
async def test(ctx):
    await ctx.send('You can manage messages.')

@discord.ext.commands.has_guild_permissions(**perms)¶

has_permissions() と似ていますが、現在のチャンネルの権限の代わりにギルド全体の権限で動作します。

このチェックがDMのコンテキストで呼び出されると、 NoPrivateMessage 例外が発生します。

バージョン 1.3 で追加.

@discord.ext.commands.has_any_role(*items)¶

A check() that is added that checks if the member invoking the command has any of the roles specified. This means that if they have one out of the three roles specified, then this check will return True.

has_role() と同様に、渡された名前やIDは正確でなければなりません。

このチェックは２つの特別な例外のうち１つ、もしユーザがロールをすべて持っていないなら MissingAnyRole を、プライベートメッセージで使用されたなら NoPrivateMessage を発生します。どちらも CheckFailure を継承します。

バージョン 1.1 で変更: 一般的な CheckFailure の代わりに MissingAnyRole または NoPrivateMessage を発生させます。

パラメータ: items (List[Union[str, int]]) -- メンバーが割り当てられたロールを持っているかどうかをチェックする名前またはIDの引数リスト。

サンプル

@bot.command()
@commands.has_any_role('Library Devs', 'Moderators', 492212595072434186)
async def cool(ctx):
    await ctx.send('You are cool indeed')

@discord.ext.commands.bot_has_role(item)¶

ボット自体がロールを持っているかどうかをチェックする以外は、 has_role() と同様です。

このチェックは２つの特別な例外のうち１つ、もしボットがロールを持っていないなら BotMissingRole を、プライベートメッセージで使用されたなら NoPrivateMessage を発生します。どちらも CheckFailure を継承します。

バージョン 1.1 で変更: 一般的な CheckFailure の代わりに BotMissingRole または NoPrivateMessage を発生させます。

バージョン 2.0 で変更: item 引数は位置限定引数になりました。

@discord.ext.commands.bot_has_permissions(**perms)¶

ボット自身がリストされている権限を持っているかどうかをチェックすること以外は has_permissions() と同様です。

このチェックは特別な例外であり、 CheckFailure から継承されている BotMissingPermissions を発生します。

@discord.ext.commands.bot_has_guild_permissions(**perms)¶: has_guild_permissions() と似ていますが、ボットメンバーのギルドの権限をチェックします。

バージョン 1.3 で追加.

@discord.ext.commands.bot_has_any_role(*items)¶

ボット自体がリストされたロールを持っているかどうかをチェックする以外は、 has_any_role() と同様です。

このチェックは２つの特別な例外のうち１つ、もしボットがどのロールも持っていないなら BotMissingAnyRole を、プライベートメッセージで使用されたなら NoPrivateMessage を発生します。どちらも CheckFailure を継承します。

バージョン 1.1 で変更: 一般的なCheckFailureの代わりに BotMissingAnyRole または NoPrivateMessage を発生させます。

@discord.ext.commands.cooldown(rate, per, type=discord.ext.commands.BucketType.default)¶

Command にクールダウンを追加するデコレーター。

クールダウンにより、コマンドは特定の時間枠内でのみ使用することができます。これらのクールダウンは、ギルドごと、チャンネルごと、ユーザごと、ロールごと、またはグローバル基準のいずれかに基づくことができます。列挙型 BucketType でなければならない第３引数 type によって示されます。

クールダウンが発生した場合、 CommandOnCooldown が on_command_error() とローカルのエラーハンドラに引っかかります。

コマンドは1つのクールダウンしか持つことができません。

パラメータ

rate (int) -- クールダウンを発生させる前にコマンドを使用できる回数。
per (float) -- トリガーされたときにクールダウンを待つ秒数。
type (Union[BucketType, Callable[[Context], Any]]) --
持っているクールダウンの種類。呼び出し可能な場合は、マッピングのキーを返す必要があります。

バージョン 1.7 で変更: カスタムされたBucketタイプの呼び出しをサポートするようになりました。

バージョン 2.0 で変更: 呼び出し可能オブジェクトを渡す場合、 Message ではなく、 Context を引数として受け付けないといけないようになりました。

@discord.ext.commands.dynamic_cooldown(cooldown, type)¶

Command に動的なクールダウンを追加するデコレータ。

これは唯一のパラメータに Context を取り、 Cooldown または None を返す関数を取るという点で cooldown() と異なります。もし None を返せば、クールダウンは事実上回避されます。

クールダウンが発生した場合、 CommandOnCooldown が on_command_error() とローカルのエラーハンドラに引っかかります。

コマンドは1つのクールダウンしか持つことができません。

バージョン 2.0 で追加.

パラメータ

cooldown (Callable[[Context], Optional[Cooldown]]) -- メッセージを受け取り、この呼び出しに適用されるクールダウンまたはクールダウンを回避する場合 None を返す関数。
type (BucketType) -- 持っているクールダウンの種類。

@discord.ext.commands.max_concurrency(number, per=discord.ext.commands.BucketType.default, *, wait=False)¶

Command またはそのサブクラスに最大同時実行数制限を追加するデコレータ。

これにより、特定の数のコマンドの同時呼び出しを許可することができます。例えば、コマンドに時間がかかりすぎたり、あるいは一度に1人のユーザーしか使えない場合などです。これは、設定された待ち時間やトークンバケットがないという点でクールダウンとは異なります - コマンドを実行できるのは、設定された数の人だけです。

バージョン 1.3 で追加.

パラメータ

number (int) -- 同時に実行できるコマンドの呼び出しの最大数。
per (BucketType) -- この並行性がベースになっているバケット。例えば、BucketType.guild ではギルドごとに number 回まで使用できます。
wait (bool) -- コマンドがキューが終わるのを待つかどうか。これが False に設定されている場合、コマンドが再び実行可能になるまで待つことのかわりに、コマンドはそのエラーハンドラに対し MaxConcurrencyReached を発生させます。これが True に設定されている場合、コマンドが実行可能になるまで待機します。

@discord.ext.commands.before_invoke(coro)¶

渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。

これにより、同じコグ内になくてもよい、複数のコマンドについてフックを呼び出す前に参照することができます。

バージョン 1.4 で追加.

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

サンプル

async def record_usage(ctx):
    print(ctx.author, 'used', ctx.command, 'at', ctx.message.created_at)

@bot.command()
@commands.before_invoke(record_usage)
async def who(ctx): # Output: <User> used who at <Time>
    await ctx.send('i am a bot')

class What(commands.Cog):

    @commands.before_invoke(record_usage)
    @commands.command()
    async def when(self, ctx): # Output: <User> used when at <Time>
        await ctx.send(f'and i have existed since {ctx.bot.user.created_at}')

    @commands.command()
    async def where(self, ctx): # Output: <Nothing>
        await ctx.send('on Discord')

    @commands.command()
    async def why(self, ctx): # Output: <Nothing>
        await ctx.send('because someone made me')

@discord.ext.commands.after_invoke(coro)¶

コルーチンを、実行後に呼び出すフックとして登録するデコレータ。

これにより、同じコグ内になくてもよい、複数のコマンドについてフックを呼び出した後に参照することができます。

バージョン 1.4 で追加.

バージョン 2.0 で変更: coro パラメータが位置指定のみになりました。

@discord.ext.commands.guild_only()¶

このコマンドを示す check() は、ギルドのコンテキスト内でのみ使用される必要があります。基本的には、プライベートメッセージはコマンドを使用するときに許可されません。

このチェックは特別な例外であり、 CheckFailure から継承されている NoPrivateMessage を発生します。

ハイブリッドコマンドで使用する場合は、 discord.app_commands.guild_only() デコレータと同じです。サブコマンドのようなサポートされていないコンテキストであっても、チェックは適用されます。

@discord.ext.commands.dm_only()¶

このコマンドを示す check() は、DMのコンテキストでのみ使用される必要があります。このコマンドを使用するときプライベートメッセージのみが許可されます。

このチェックは特別な例外であり、 CheckFailure から継承されている PrivateMessageOnly を発生します。

バージョン 1.1 で追加.

@discord.ext.commands.is_owner()¶

このコマンドを実行している人がボットの所有者であるかどうかをチェックする check() 。

これは Bot.is_owner() を使って動作します。

このチェックは特別な例外であり、 CheckFailure から継承されている NotOwner を発生します。

@discord.ext.commands.is_nsfw()¶

NSFWチャンネルであるかどうかをチェックする check() 。

このチェックは特別な例外であり、 CheckFailure から継承されている NSFWChannelRequired を発生します。

ハイブリッドコマンドで使用する場合は、アプリケーションコマンドの nsfw 属性を True に設定するのと同じです。サブコマンドのようなサポートされていないコンテキストであっても、チェックは適用されます。

バージョン 1.1 で変更: 一般的な CheckFailure の代わりに NSFWChannelRequired を発生させます。DMチャンネルもこのチェックを通過するようになります。

Context¶

Methods

clsContext.from_interaction
asyncdefer
asyncfetch_message
async forhistory
asyncinvoke
asyncpins
asyncreinvoke
asyncreply
asyncsend
asyncsend_help
deftyping

class discord.ext.commands.Context(*, message, bot, view, args=..., kwargs=..., prefix=None, command=None, invoked_with=None, invoked_parents=..., invoked_subcommand=None, subcommand_passed=None, command_failed=False, current_parameter=None, current_argument=None, interaction=None)¶

コマンドが実行されているコンテキストを表します。

このクラスには、呼び出しコンテキストについて理解するのに役立つ多くのメタデータが含まれています。このクラスは手動では作成されず、代わりに最初のパラメータとしてコマンドに渡されます。

このクラスは Messageable ABC を実装しています。

message¶

実行中のコマンドをトリガーしたメッセージ。

注釈

インタラクションベースのコンテキストの場合、メッセージは「合成」されていて、実在しません。そのため、IDは一時的なメッセージ同様無効です。

型: Message

bot¶

実行中のコマンドを含むボット。

型: Bot

args¶

コマンドに渡された変換された引数のリスト。もしこれが on_command_error() イベント中にアクセスされた場合、このリストは不完全である可能性があります。

型: list

kwargs¶

コマンドに渡された変換された引数の辞書。 args と似ていて、もしこれが on_command_error() イベント中にアクセスされた場合、この辞書は不完全である可能性があります。

型: dict

current_parameter¶

現在検査および変換されているパラメータ。これはコンバータ内でのみ使用されます。

バージョン 2.0 で追加.

型: Optional[Parameter]

current_argument¶

現在変換されている current_parameter の引数文字列。これはコンバーター内でのみ使用されます。

バージョン 2.0 で追加.

型: Optional[str]

interaction¶

このコンテキストに関連付けられたインタラクション。

バージョン 2.0 で追加.

型: Optional[Interaction]

prefix¶

コマンドを呼び出すために使用された接頭辞。インタラクションベースのコンテキストでは、スラッシュコマンドでは / で、コンテキストメニューコマンドでは \u200b です。

型: Optional[str]

command¶

現在呼び出されているコマンド。

型: Optional[Command]

invoked_with¶

この呼び出しを引き起こしたコマンドの名前。コマンドを呼び出した別名を突き止めるのに役立ちます。

型: Optional[str]

invoked_parents¶

この呼び出しを引き起こした親のコマンドの名前。コマンドを呼び出した別名を突き止めるのに役立ちます。

例えば、?a b c test では、呼び出された親は ['a', 'b', 'c'] です。

バージョン 1.7 で追加.

型: List[str]

invoked_subcommand¶

呼び出されたサブコマンド。有効なサブコマンドが呼び出されなかった場合、これは None と等しくなります。

型: Optional[Command]

subcommand_passed¶

サブコマンドの呼び出しを試みた文字列。これは有効な登録されたサブコマンドを指す必要はなく、無茶な文字列を指すだけとなり得ます。サブコマンドへの呼び出しに何も渡されなかった場合、これは None に設定されます。

型: Optional[str]

command_failed¶

コマンドの分解、チェック、呼び出しに失敗したかどうかを示すブール値。

型: bool

async with typing(*, ephemeral=False)¶

入力インジケーターを宛先に無期限で、または await で呼び出された場合10秒間表示できるようにする非同期コンテキストマネージャーを返します。

インタラクションベースのコンテキストでは、これは defer() 呼び出しと同じで、入力呼び出しは行いません。

使用例:

async with channel.typing():
    # simulate something heavy
    await asyncio.sleep(20)

await channel.send('Done!')

使用例:

await channel.typing()
# Do some computational magic for about 10 seconds
await channel.send('Done!')

バージョン 2.0 で変更: これは with 構文で動作せず、代わりに async with を使用しないといけないように変更されました。

バージョン 2.0 で変更: コンテキストマネージャーを await して入力インジケーターを10秒間送信する機能を追加しました。

パラメータ

ephemeral (bool) --

遅延されたメッセージが後に一時的になるかどうかを示します。インタラクションベースのコンテキストでのみ有効です。

バージョン 2.0 で追加.

classmethod await from_interaction(interaction, /)¶

This function is a coroutine.

discord.Interaction からコンテキストを作成します。これはスラッシュコマンドやコンテキストメニューなどのアプリケーションコマンドベースのインタラクションでのみ動作します。

スラッシュコマンドベースのインタラクションではこれはコマンド実行者が実行した一時的なメッセージを指す Message を合成します。つまり、 Context.author はコマンドを実行したメンバーを返します。

メッセージコンテキストメニューベースのインタラクションでは、 Context.message 属性はコマンドが実行されたメッセージです。つまり、 Context.author は対象メッセージの送信者を返します。コマンドを実行したメンバーを得るには、代わりに discord.Interaction.user を使用すべきです。

バージョン 2.0 で追加.

パラメータ

interaction (discord.Interaction) -- コンテキストを作成するためのインタラクション。

例外

ValueError -- インタラクションに有効なコマンドが存在しない場合。
TypeError -- インタラクションクライアントが Bot や AutoShardedBot を継承していない場合。

await invoke(command, /, *args, **kwargs)¶

This function is a coroutine.

与えられた引数でコマンドを呼び出します。

単に Command が内部的に保持しているコールバックを呼び出したい場合に便利です。

注釈

これは、いずれの場合においても、コンバーター、チェック、クールダウン、呼び出し前、または呼び出し後のフックを処理しません。内部コールバックが通常の関数であるかのように直接呼び出します。

この関数を使用する場合は、適切な引数を渡すことに注意しなければなりません。

バージョン 2.0 で変更: command 引数は位置限定引数になりました。

パラメータ

command (Command) -- 呼び出されるコマンド。
*args -- 使用する引数。
**kwargs -- 使用するキーワード引数。

例外

TypeError -- 呼び出すコマンド引数がありません。

await reinvoke(*, call_hooks=False, restart=True)¶

This function is a coroutine.

コマンドを再度呼び出します。

これはチェック、クールダウン、エラーハンドラが回避されていることを除き、 invoke() と同様です。

注釈

派生した例外の UserInputError を回避したい場合は、より自然に動作する標準の invoke() を使用することをお勧めします。結局のところ、これはユーザが使用した古い引数を使用することになり、したがって再び失敗します。

パラメータ

call_hooks (bool) -- 前後にフックを呼び出すかどうかを設定します。
restart (bool) -- 呼び出しチェーンを最初、または中断した場所(例えばエラーの原因となったコマンド)から開始するかどうか。デフォルトでは、中断した位置から開始します。

例外

ValueError -- 再呼び出しするコンテキストが無効です。

property valid¶

呼び出しコンテキストを呼び出すのが有効かどうかを確認します。

型: bool

property clean_prefix¶

「クリーンアップ」されたプレフィックスを返します。たとえば、メンションは <@id> のかわりに @name となります。

バージョン 2.0 で追加.

型: str

property cog¶

このコンテキストのコマンドに関連付けられたコグを返します。存在しない場合はNoneを返します。

型: Optional[Cog]

guild¶

このコンテキストのコマンドに関連付けられているギルドを返します。利用できない場合はNoneを返します。

型: Optional[Guild]

channel¶

このコンテキストのコマンドに関連付けられているチャンネルを返します。 Message.channel のショートカットです。

型: Union[abc.Messageable]

author¶: Union[User, Member]: このコンテキストのコマンドに関連付けられた作者を返します。 Message.author のショートカットです。

me¶: Union[Member, ClientUser]: これはプライベートメッセージコンテキストでは ClientUser を返すことを除いて、 Guild.me と同様です。

permissions¶

このチャンネルでのコマンドを実行したユーザーの解決された権限を返します。 abc.GuildChannel.permissions_for() と Interaction.permissions のショートカットです。

バージョン 2.0 で追加.

型: Permissions

bot_permissions¶

このチャンネルでのボットの解決された権限を返します。 abc.GuildChannel.permissions_for() と Interaction.app_permissions のショートカットです。

インタラクションベースのコマンドでは、これは Context 呼び出しにて有効な権限を反映していて、 channel のような他の abc.Messageable に適用されるものと異なる可能性があります。

特に、メッセージの送信、埋め込みリンク、ファイルの添付は常に許可されていますが、メッセージを読むことはできない場合があります。

バージョン 2.0 で追加.

型: Permissions

property voice_client¶

該当する場合は、 Guild.voice_client へのショートカット。

型: Optional[VoiceProtocol]

await send_help(entity=<bot>)¶

This function is a coroutine.

指定されたエンティティのヘルプコマンドを表示します。エンティティはコマンドまたはコグになることができます。

エンティティが指定されていない場合は、ボット全体のヘルプが表示されます。

エンティティが文字列の場合、 Cog または Command を検索します。

注釈

この関数の動作によっては、 command_not_found() のようなものを返す代わりに、不正な入力またはヘルプコマンドがない際に None を返します。

パラメータ: entity (Optional[Union[Command, Cog, str]]) -- ヘルプを表示するエンティティ。
戻り値: もしあれば、ヘルプコマンドの結果。
戻り値の型: Any

await reply(content=None, **kwargs)¶

This function is a coroutine.

このコンテキストで参照されている Message に返信するための、 send() のショートカットメソッド。

インタラクションベースのコンテキストでは、 send() と同じです。

バージョン 1.6 で追加.

バージョン 2.0 で変更: この関数は InvalidArgument の代わりに TypeError または ValueError を発生するようになりました。

例外

HTTPException -- メッセージの送信に失敗しました。
Forbidden -- メッセージを送信するための適切な権限がありません。
ValueError -- files リストの大きさが適切ではありません。
TypeError -- file と files の両方が指定されています。

戻り値

送信されたメッセージ。

戻り値の型

Message

await defer(*, ephemeral=False)¶

This function is a coroutine.

インタラクションの応答を遅らせます。

これは通常、インタラクションを認識した後、後で他のことを実行する場合に使われます。

これがインタラクションベースのコンテキストでない場合、何もしません。

パラメータ

ephemeral (bool) -- 遅れて送信するメッセージが一時的になるかを示します。

例外

HTTPException -- インタラクションの遅延に失敗した場合。
InteractionResponded -- 既にインタラクションに応答していた場合。

await fetch_message(id, /)¶

This function is a coroutine.

出力先から、単一の Message を取得します。

パラメータ

id (int) -- 探索をするメッセージID。

例外

NotFound -- 指定されたメッセージが見つからなかった場合。
Forbidden -- メッセージの取得に必要な権限がない場合。
HTTPException -- メッセージの取得に失敗した場合。

戻り値

要求されたメッセージ。

戻り値の型

Message

async for ... in history(*, limit=100, before=None, after=None, around=None, oldest_first=None)¶

出力先のメッセージ履歴を取得する asynchronous iterator を返します。

これを行うためには、 read_message_history が必要です。

サンプル

使い方

counter = 0
async for message in channel.history(limit=200):
    if message.author == client.user:
        counter += 1

リストにフラット化:

messages = [message async for message in channel.history(limit=123)]
# messages is now a list of Message...

すべてのパラメータがオプションです。

パラメータ

limit (Optional[int]) -- 取得するメッセージの数。 None の場合、チャンネルのメッセージすべてを取得します。ただし、これには時間がかかります。
before (Optional[Union[Snowflake, datetime.datetime]]) -- この日付またはメッセージより前のメッセージを取得します。もしdatetimeを指定する場合、UTC基準のawareなdatetimeを利用することを推奨します。naiveなdatetimeである場合、これはローカル時間であるとみなされます。
after (Optional[Union[Snowflake, datetime.datetime]]) -- この日付またはメッセージより後のメッセージを取得します。もしdatetimeを指定する場合、UTC基準のawareなdatetimeを利用することを推奨します。naiveなdatetimeである場合、これはローカル時間であるとみなされます。
around (Optional[Union[Snowflake, datetime.datetime]]) -- この日付またはメッセージの周辺のメッセージを取得します。もしdatetimeを指定する場合、UTC基準のawareなdatetimeを利用することを推奨します。naiveなdatetimeである場合、これはローカル時間であるとみなされます。この引数を使うとき、最大限界値は101です。限界値が偶数なら最大で限界値+1のメッセージが返されることに注意してください。
oldest_first (Optional[bool]) -- True の場合、古いものから新しいものの順で項目を返します。デフォルトは、 after が指定された場合には True で、そうでなければ False です。

例外

Forbidden -- チャンネルのメッセージ履歴を読む権限がありません。
HTTPException -- メッセージ履歴の取得に失敗しました。

列挙

Message -- メッセージのデータを解析されたメッセージ。

await pins()¶

This function is a coroutine.

現時点でチャンネルにピン留めされている全てのメッセージを取得します。

注釈

Discord APIの制限により、このメソッドの返した Message オブジェクトには、完全な Message.reactions のデータが含まれていません。

例外

Forbidden -- ピン留めされたメッセージの取得に必要な権限がない場合。
HTTPException -- ピン留めされたメッセージの取得に失敗しました。

戻り値

現時点でピン留めされているメッセージ。

戻り値の型

List[Message]

await send(content=None, *, tts=False, embed=None, embeds=None, file=None, files=None, stickers=None, delete_after=None, nonce=None, allowed_mentions=None, reference=None, mention_author=None, view=None, suppress_embeds=False, ephemeral=False)¶

This function is a coroutine.

指定された内容のメッセージを出力先に送信します。

これはインタラクションベースでないコンテキストでは send() と同様に動作します。

インタラクションベースのコンテキストでは以下のどれかを行います：

応答が与えられていない場合 discord.InteractionResponse.send_message() 。
応答が与えられた場合フォローアップメッセージ。
インタラクションが期限切れの場合通常の送信

バージョン 2.0 で変更: この関数は InvalidArgument の代わりに TypeError または ValueError を発生するようになりました。

パラメータ

content (Optional[str]) -- 送信するメッセージの内容。
tts (bool) -- メッセージが読み上げテキストで送信されるべきかどうかを示します。
embed (Embed) -- 内容に埋め込む、typeが rich な埋め込み。
file (File) -- アップロードするファイル。
files (List[File]) -- アップロードするファイルのリスト。ファイル数は最大で10個まででなければなりません。
nonce (int) -- メッセージの送信時に使用するナンス値。メッセージが正常に送信された場合、このメッセージにはこの値のナンス値が含まれます。
delete_after (float) -- If provided, the number of seconds to wait in the background before deleting the message we just sent. If the deletion fails, then it is silently ignored.
allowed_mentions (AllowedMentions) --
処理されるメッセージ内のメンションを制御します。これが渡された場合、オブジェクトは allowed_mentions で合併されます。これは、オブジェクトに明示的に渡された属性のみを上書きするもので、それ以外は allowed_mentions で設定された属性が使用されます。もしオブジェクトが渡されていない場合は allowed_mentions がデフォルトとして利用されます。

バージョン 1.4 で追加.
reference (Union[Message, MessageReference, PartialMessage]) --
返信する Message への参照。これは、 to_reference() を使用して作成することができ、また、 Message を直接渡すこともできます。これが返信元のメッセージの投稿者をメンションすべきかは、 allowed_mentions の replied_user 属性や、 mention_author パラメータで制御できます。

インタラクションベースのコンテキストでは無視されます。

バージョン 1.6 で追加.
mention_author (Optional[bool]) --
設定された場合、 allowed_mentions の replied_user 属性を上書きします。インタラクションベースのコンテキストでは無視されます。

バージョン 1.6 で追加.
view (discord.ui.View) --
メッセージに追加するDiscord UI ビュー。

バージョン 2.0 で追加.
embeds (List[Embed]) --
送信する埋め込みのリスト。最大10個まで送信できます。

バージョン 2.0 で追加.
stickers (Sequence[Union[GuildSticker, StickerItem]]) --
送信するスタンプのリスト。最大3個まで送信できます。インタラクションベースのコンテキストでは無視されます。

バージョン 2.0 で追加.
suppress_embeds (bool) --
メッセージの埋め込みを抑制するかどうか。これが True に設定されている場合、埋め込みなしでメッセージを送信します。

バージョン 2.0 で追加.
ephemeral (bool) --
メッセージがインタラクションを開始したユーザーだけに表示されるかどうか。もしビューが一時的なメッセージで送信されている、かつタイムアウトが設定されていない場合、タイムアウトは15分に設定されます。 これはインタラクションベースのコンテキストでのみ適用されます。

バージョン 2.0 で追加.

例外

HTTPException -- メッセージの送信に失敗しました。
Forbidden -- メッセージを送信するための適切な権限がありません。
ValueError -- files リストの大きさが適切でない場合。
TypeError -- file と files の両方が指定された場合、 embed と embeds の両方が指定された場合、または reference が Message 、 MessageReference 、 PartialMessage でない場合。

戻り値

送信されたメッセージ。

戻り値の型

Message

コンバーター¶

Methods

asyncconvert

class discord.ext.commands.Converter(*args, **kwargs)¶

Context を渡す必要のあるカスタムコンバーターの基底クラス。

これにより、スペシャルケースの discord クラスと似たコンバーターを実装できます。

サブクラスは convert() メソッドを上書きして変換ロジックを実装すべきです。このメソッドは coroutine でないといけません。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.ObjectConverter(*args, **kwargs)¶

Object に変換します。

The argument must follow the valid ID or mention formats (e.g. <@80088516616269824>).

バージョン 2.0 で追加.

検索は以下の順で行われます:

IDで検索
メンバー、ロール、またはチャネルのメンションで検索。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.MemberConverter(*args, **kwargs)¶

Member に変換します。

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前#タグで検索
名前で検索
ニックネームで検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに MemberNotFound を発生させます。

バージョン 1.5.1 で変更: このコンバータは、ゲートウェイやHTTP APIからメンバーを取得でき、 MemberCacheFlags.joined が有効な場合には結果がキャッシュされるようになりました。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.UserConverter(*args, **kwargs)¶

User に変換します。

すべての検索はグローバルユーザーキャッシュを介して行われます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前#タグで検索
名前で検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに UserNotFound を発生させます。

バージョン 1.6 で変更: このコンバータは、ID が渡され、キャッシュされていない場合、HTTP API からユーザーを取得するようになりました。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.MessageConverter(*args, **kwargs)¶

discord.Message に変換します。

バージョン 1.1 で追加.

検索は以下の順で行われます:

"{チャンネルID}-{メッセージID}" で検索 ("Copy ID" をシフト-クリック)
メッセージIDによる検索 (メッセージはコンテキストチャンネル内で なければなりません)
メッセージURLで検索

バージョン 1.5 で変更: ChannelNotFound, MessageNotFound または ChannelNotReadable を一般的な BadArgument の代わりに発生します。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.PartialMessageConverter(*args, **kwargs)¶

discord.PartialMessage に変換します。

バージョン 1.7 で追加.

作成は以下の順で行われます:

"{チャンネルID}-{メッセージID}" ("Copy ID" をシフト-クリック)
メッセージID (メッセージは現在のチャンネル内であると推定されます。)
メッセージURL

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.GuildChannelConverter(*args, **kwargs)¶

GuildChannel に変換します。

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

バージョン 2.0 で追加.

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.TextChannelConverter(*args, **kwargs)¶

TextChannel に変換します。

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに ChannelNotFound を発生させます

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.VoiceChannelConverter(*args, **kwargs)¶

VoiceChannel に変換します。

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに ChannelNotFound を発生させます

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.StageChannelConverter(*args, **kwargs)¶

StageChannel に変換します。

バージョン 1.7 で追加.

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.CategoryChannelConverter(*args, **kwargs)¶

CategoryChannel に変換します。

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに ChannelNotFound を発生させます

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.ForumChannelConverter(*args, **kwargs)¶

ForumChannel に変換します。

すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

バージョン 2.0 で追加.

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.InviteConverter(*args, **kwargs)¶

Invite に変換します。

Bot.fetch_invite() を使用したHTTP リクエストによって行われます。

バージョン 1.5 で変更: 一般的な BadArgument の代わりに BadInviteArgument を発生させます。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.GuildConverter(*args, **kwargs)¶

Guild に変換します。

検索は以下の順で行われます:

IDで検索
名前で検索。(名前が一致するギルドの曖昧さ回避は行われません。)

バージョン 1.7 で追加.

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.RoleConverter(*args, **kwargs)¶

Role に変換します。

すべて検索は現在のギルドで行われます。DMでは、 NoPrivateMessage 例外が送出されます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに RoleNotFound を発生させます。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.GameConverter(*args, **kwargs)¶

Game に変換します。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.ColourConverter(*args, **kwargs)¶

Colour に変換します。

バージョン 1.5 で変更: ColorConverter という名前のエイリアスを追加

以下のフォーマットが利用可能です:

0x<hex>
#<hex>
0x#<hex>
rgb(<数値>, <数値>, <数値>)
Colour の classmethod のどれか
- 名前の _ は任意でスペースに置き換えることができます。

CSSのように、 <number> は0-255か0-100%で指定でき、 <hex> は6桁の16進数表記か3桁のショートカット (例: #fff)で指定できます。

バージョン 1.5 で変更: 一般的な BadArgument の代わりに BadColourArgument を発生させます。

バージョン 1.7 で変更: rgb 関数と3桁の16進数ショートカットのサポートを追加しました。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.EmojiConverter(*args, **kwargs)¶

Emoji に変換します。

すべて検索は利用できる場合まず現在のギルドで行われます。失敗した場合、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
絵文字からIDを抽出して検索。
名前で検索

バージョン 1.5 で変更: 一般的な BadArgument の代わりに EmojiNotFound を発生させます。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.PartialEmojiConverter(*args, **kwargs)¶

PartialEmoji に変換します。

これは絵文字からアニメーションフラグ、名前、IDを抽出することによって行われます。

バージョン 1.5 で変更: 一般的な BadArgument の代わりに PartialEmojiConversionFailure を発生させます。

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.ThreadConverter(*args, **kwargs)¶

Thread に変換します。

すべての検索はローカルギルドを経由して行われます。

検索は以下の順で行われます:

IDで検索
メンションで検索
名前で検索

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.GuildStickerConverter(*args, **kwargs)¶

GuildSticker に変換します。

すべて検索は利用できる場合まず現在のギルドで行われます。失敗した場合、グローバルキャッシュが使用されます。

検索は以下の順で行われます:

IDで検索
名前で検索

バージョン 2.0 で追加.

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Methods

asyncconvert

class discord.ext.commands.ScheduledEventConverter(*args, **kwargs)¶

ScheduledEvent に変換します。

可能な場合は、ローカルギルドに対して検索が行われます。それ以外の場合は、DMコンテキストでは、ルックアップはグローバルキャッシュによって行われます。

検索は以下の順で行われます:

IDで検索
URL で検索する。
名前で検索

バージョン 2.0 で追加.

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

Attributes

escape_markdown
fix_channel_mentions
remove_markdown
use_nicknames

Methods

asyncconvert

class discord.ext.commands.clean_content(*, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False, remove_markdown=False)¶

引数を、メンションを削ぎ落とされたコンテンツに変換します。

これは clean_content と同様に動作します。

fix_channel_mentions¶

チャンネルのメンションを削除するかどうか。

型: bool

use_nicknames¶

メンションを変換する際にニックネームを使用するかどうか。

型: bool

escape_markdown¶

特殊なマークダウン文字もエスケープするかどうか。

型: bool

remove_markdown¶

特殊なマークダウン文字も除去するかどうか。このオプションは escape_markdown と一緒にはサポートされていません。

バージョン 1.7 で追加.

型: bool

await convert(ctx, argument)¶

This function is a coroutine.

変換ロジックを行うために上書きすべきメソッド。

変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために CommandError から派生する例外を送出することをおすすめします。

パラメータ

ctx (Context) -- 引数が使用されている呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。

class discord.ext.commands.Greedy¶

できなくなるまで貪欲に引数を消費する特別なコンバータ。この挙動の結果として、ほとんどの入力エラーは解析をいつ停止するかの指標として使用されるため無視されます。

解析エラーに遭遇すると、貪欲なコンバータは変換を停止し、内部の文字列の解析ルーチンを取り消し、通常の解析を続けます。

例えば、以下のコードです:

@commands.command()
async def test(ctx, numbers: Greedy[int], reason: str):
    await ctx.send("numbers: {}, reason: {}".format(numbers, reason))

[p]test 1 2 3 4 5 6 hello で呼び出すと numbers に [1, 2, 3, 4, 5, 6] を、 reason に hello を渡します。

詳細については、特殊なコンバーターを参照してください。

注釈

インタラクションベースのコンテキストではアプリケーションコマンドでのユーザーエクスペリエンスの差異のため変換エラーは無視されず伝播されます。

class discord.ext.commands.Range¶

与えられた範囲内に収まる数値または文字列型を必要とするパラメータに適用できる特別なコンバーター。

型チェック時には型チェッカがコードの意図を理解できるよう typing.Annotated と同様になります。

例:

Range[int, 10] は最小値10、最大値なしを意味します。
Range[int, None, 10] は最小値なし、最大値10を意味します。
Range[int, 1, 10] は最小値1、最大値10を意味します。

HybridCommand 内では、この関数は discord.app_commands.Range と同様に動作します。

もし値が渡された型に変換できず、または指定された範囲外である場合、BadArgument や RangeError が適切なエラーハンドラに送出されます。

バージョン 2.0 で追加.

サンプル

@bot.command()
async def range(ctx: commands.Context, value: commands.Range[int, 10, 12]):
    await ctx.send(f'Your value is {value}')

await discord.ext.commands.run_converters(ctx, converter, argument, param)¶

This function is a coroutine.

指定したコンバータ、引数、パラメータのコンバータを実行します。

この関数は、内部的にはライブラリと同じように動作します。

バージョン 2.0 で追加.

パラメータ

ctx (Context) -- コンバータを実行する呼び出しコンテキスト。
converter (Any) -- 実行するコンバータで、関数の注釈に対応します。
argument (str) -- 変換する引数。
param (Parameter) -- 変換されるパラメータ。これは主にエラー報告用です。

例外

CommandError -- コンバータが変換に失敗しました。

戻り値

変換の結果

戻り値の型

Any

Flag Converter¶

Methods

clsFlagConverter.convert
clsFlagConverter.get_flags

class discord.ext.commands.FlagConverter¶

ユーザに優しいフラグ構文を可能にするコンバータ。

フラグはPythonモジュールの dataclasses と同様に PEP 526 の型アノテーションを用いて定義されています。どのようにしてこのコンバータが動作するかの詳細については、当該のドキュメントを確認してください。

iter(x): (flag_name, flag_value) ペアのイテレータを返します。これにより、例えば、辞書型やペアのリストに変換できます。別名は表示されないことに注意してください。

バージョン 2.0 で追加.

パラメータ

case_insensitive (bool) -- フラグ解析で大文字と小文字を区別しないようにするクラスパラメータ。 True の場合、フラグは大文字と小文字を区別しない方法で解析されます。デフォルトは False です。
prefix (str) -- すべてのフラグに付いていなければならない接頭辞。デフォルトでは接頭辞はありません。
delimiter (str) -- フラグの引数とフラグの名前を区切る区切り文字。デフォルトでは : です。

classmethod get_flags()¶: Dict[str, Flag]: このコンバータが持つフラグ名とフラグオブジェクトのマッピング。

classmethod await convert(ctx, argument)¶

This function is a coroutine.

フラグのマッピングに実際に引数を変換するメソッド。

パラメータ

ctx (Context) -- 呼び出しコンテキスト。
argument (str) -- 変換する引数。

例外

FlagError -- フラグ関連の解析エラー。

戻り値

すべての解析済みフラグ付きのフラグコンバータインスタンス。

戻り値の型

FlagConverter

Attributes

aliases
annotation
attribute
default
description
max_args
name
override
required

class discord.ext.commands.Flag¶

FlagConverter のフラグパラメータを表します。

flag() 関数はこれらのフラグオブジェクトを作成するのに役立ちますが、必須ではありません。これらは手動で構築することはできません。

name¶

フラグの名前

型: str

aliases¶

フラグ名のエイリアス

型: List[str]

attribute¶

このフラグに対応するクラスの属性。

型: str

default¶

利用可能であれば、フラグのデフォルト値。

型: Any

annotation¶

基礎評価済みのフラグのアノテーション。

型: Any

max_args¶

フラグが受け付けられる引数の最大数。負の値は、引数の量が無制限であることを示します。

型: int

override¶

指定された重複する値が前の値を上書きするかどうか。

型: bool

description¶

フラグの説明。ハイブリッドコマンドがアプリケーションコマンドとして使用されたときに表示されます。

型: str

property required¶

フラグが必須かどうか。

必須フラグにはデフォルト値はありません。

型: bool

discord.ext.commands.flag(*, name=..., aliases=..., default=..., max_args=..., override=..., converter=..., description=...)¶

FlagConverter クラス属性のデフォルトの機能とパラメータを上書きします。

パラメータ

name (str) -- フラグ名。指定しない場合、デフォルトでは属性名です。
aliases (List[str]) -- フラグ名の別名。渡されない場合別名は設定されません。
default (Any) -- デフォルトパラメータ。これは値または Context を引数として取る呼び出し可能オブジェクトでないといけません。指定されていない場合は、属性の既定値が使用されます。
max_args (int) -- フラグが受け付けられる最大の引数の数。負数を渡した場合は何個でも引数を渡せることを示します。デフォルト値は与えられたアノテーションによって異なります。
override (bool) -- 複数の値が与えられた場合に前の値を上書きするかどうか。デフォルト値は与えられたアノテーションによって異なります。
converter (Any) -- このフラグに使用するコンバーター。実行時にアノテーションを置き換えます。これは型チェッカに対して透過的です。
description (str) -- フラグの説明。ハイブリッドコマンドがアプリケーションコマンドとして使用されたときに表示されます。

既定値¶

Attributes

annotation
converter
default
description
displayed_default
kind
name
required

Methods

asyncget_default
defreplace

class discord.ext.commands.Parameter¶

Command のパラメータに関する情報を格納するクラス。

inspect.Parameter のサブクラスです。

バージョン 2.0 で追加.

replace(*, name=..., kind=..., default=..., annotation=..., description=..., displayed_default=...)¶: パラメータのカスタマイズされたコピーを返します。

property name¶: パラメータの名前。

property kind¶: パラメータの種類。

property default¶: パラメータの既定値。

property annotation¶: パラメータのアノテーション。

property required¶

パラメータが必須かどうか。

型: bool

property converter¶: このパラメータに使用すべきコンバーター。

property description¶

このパラメータの説明。

型: Optional[str]

property displayed_default¶

Command.signature で表示される既定値。

型: Optional[str]

await get_default(ctx)¶

This function is a coroutine.

このパラメータの既定値を取得します。

パラメータ: ctx (Context) -- 引数の既定値を取得するために使用される呼び出しコンテキスト。

discord.ext.commands.parameter(\*, converter=..., default=..., description=..., displayed_default=...)¶

Command のパラメータにカスタムメタデータを割り当てる方法。

バージョン 2.0 で追加.

サンプル

カスタムの既定値を指定すると、既定値を動的に指定できます。

@bot.command()
async def wave(ctx, to: discord.User = commands.parameter(default=lambda ctx: ctx.author)):
    await ctx.send(f'Hello {to.mention} :wave:')

パラメータ

converter (Any) -- このフラグに使用するコンバーター。実行時にアノテーションを置き換えます。これは型チェッカに対して透過的です。
default (Any) -- パラメータの既定値。これが callable か coroutine の場合これは位置指定の Context 引数を渡して呼び出されます。
description (str) -- このパラメータの説明。
displayed_default (str) -- Command.signature で表示される既定値。

discord.ext.commands.param(*, converter, default, description, displayed_default)¶

param(*, converter=..., default=..., description=..., displayed_default=...)

parameter() のエイリアス。

バージョン 2.0 で追加.

discord.ext.commands.Author¶: このコンテキストの author を返すデフォルト Parameter 。

バージョン 2.0 で追加.

discord.ext.commands.CurrentChannel¶: このコンテキストの channel を返すデフォルト Parameter 。

バージョン 2.0 で追加.

discord.ext.commands.CurrentGuild¶: このコンテキストの guild を返すデフォルト Parameter 。これは None にはなりません。コマンドがDM内で呼び出された場合は NoPrivateMessage がエラーハンドラに送出されます。

バージョン 2.0 で追加.

例外¶

exception discord.ext.commands.CommandError(message=None, *args)¶

コマンドに関連するエラーすべての基礎となる例外。

これは discord.DiscordException を継承しています。

この例外及び、ここから継承された例外は、キャッチされると Bot の on_command_error() に渡され、特別な方法で処理されます。

exception discord.ext.commands.ConversionError(converter, original)¶

Converter クラスで、CommandErrorではない例外が発生した際に、発生する例外。

これは CommandError から継承されます。

converter¶

失敗したコンバーター。

型: discord.ext.commands.Converter

original¶

Converter内で発生した元の例外。 __cause__ からも取得できます。

型: Exception

exception discord.ext.commands.MissingRequiredArgument(param)¶

コマンドのパラメータ解析の際、要求されたパラメータに値が渡されていない場合に発生します。

これは UserInputError から継承されます。

param¶

不足している引数

型: Parameter

exception discord.ext.commands.MissingRequiredAttachment(param)¶

コマンドのパラメータ解析の際、添付ファイルを必要とするパラメータが与えられていない場合に発生します。

これは UserInputError から継承されます。

バージョン 2.0 で追加.

param¶

添付ファイルがない引数。

型: Parameter

exception discord.ext.commands.ArgumentParsingError(message=None, *args)¶

パーサーがユーザーの入力の解析に失敗したときに発生する例外。

これは UserInputError から継承されます。

i18n のためにより細かい解析エラーを実装するサブクラスがあります。

exception discord.ext.commands.UnexpectedQuoteError(quote)¶

パーサーが引用符で囲まれていない文字列の中で引用符に遭遇したときに発生する例外。

これは ArgumentParsingError から継承されます。

quote¶

引用符で囲まれていない文字列の中に見つかった引用符。

型: str

exception discord.ext.commands.InvalidEndOfQuotedStringError(char)¶

文字列の引用符が閉じられた後に空白が期待されるとき、別の文字が見つかった場合の例外。

これは ArgumentParsingError から継承されます。

char¶

期待される文字列の代わりに見つかった文字。

型: str

exception discord.ext.commands.ExpectedClosingQuoteError(close_quote)¶

引用符が期待されているが見つからない場合に発生する例外。

これは ArgumentParsingError から継承されます。

close_quote¶

期待された引用符。

型: str

exception discord.ext.commands.BadArgument(message=None, *args)¶

コマンドの引数に渡された値の解析、または変換に失敗した場合に発生する例外。

これは UserInputError から継承されます。

exception discord.ext.commands.BadUnionArgument(param, converters, errors)¶

typing.Union コンバーターが対応するすべての型に対して失敗した場合に発生する例外。

これは UserInputError から継承されます。

param¶

変換に失敗したパラメータ。

型: inspect.Parameter

converters¶

変換しようとして失敗したコンバーターの、失敗した順のタプル。

型: Tuple[Type, ...]

errors¶

変換失敗時に捕捉されたエラーのリスト。

型: List[CommandError]

exception discord.ext.commands.BadLiteralArgument(param, literals, errors)¶

typing.Literal コンバーターが対応するすべての値に対して失敗した場合に発生する例外。

これは UserInputError から継承されます。

バージョン 2.0 で追加.

param¶

変換に失敗したパラメータ。

型: inspect.Parameter

literals¶

比較が失敗した値の、失敗した順のタプル。

型: Tuple[Any, ...]

errors¶

変換失敗時に捕捉されたエラーのリスト。

型: List[CommandError]

exception discord.ext.commands.PrivateMessageOnly(message=None)¶

プライベートメッセージコンテキスト外で、要求された処理が実行できない場合に発生する例外。

これは CheckFailure から継承されます。

exception discord.ext.commands.NoPrivateMessage(message=None)¶

プライベートメッセージコンテキストで、要求された処理が実行できない場合に発生する例外。

これは CheckFailure から継承されます。

exception discord.ext.commands.CheckFailure(message=None, *args)¶

Command.checks のチェックが失敗した場合に発生する例外。

これは CommandError から継承されます。

exception discord.ext.commands.CheckAnyFailure(checks, errors)¶

check_any() のチェックがすべて失敗した場合に発生する例外。

これは CheckFailure から継承されます。

バージョン 1.3 で追加.

errors¶

実行時に捕捉されたエラーのリスト。

型: List[CheckFailure]

checks¶

失敗したチェックのリスト。

型: List[Callable[[Context], bool]]

exception discord.ext.commands.CommandNotFound(message=None, *args)¶

コマンドを呼び出す際に、指定された名前を持つコマンドが存在していなかった場合に発生する例外。

これは無効なサブコマンドに対して発生するのではなく、呼び出されようとした最初のメインコマンドに対し発生します。

これは CommandError から継承されます。

exception discord.ext.commands.DisabledCommand(message=None, *args)¶

呼び出そうとしたコマンドが無効化されていた際に発生する例外。

これは CommandError から継承されます。

exception discord.ext.commands.CommandInvokeError(e)¶

呼び出そうとしたコマンドが例外を送出した場合に発生する例外。

これは CommandError から継承されます。

origi