APIリファレンス¶
この項目ではdiscord.pyのAPIが持つコマンド拡張モジュールについて解説します。
Bot¶
Bot¶
- activity
- allowed_mentions
- application
- application_flags
- application_id
- cached_messages
- case_insensitive
- cogs
- command_prefix
- commands
- description
- emojis
- extensions
- guilds
- help_command
- intents
- latency
- owner_id
- owner_ids
- persistent_views
- private_channels
- status
- stickers
- strip_after_prefix
- tree
- tree_cls
- user
- users
- voice_clients
- 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
です。この属性はグループに適用されません。もしグループコマンドも大文字と小文字を区別したくない場合、すべてのグループで設定しなければなりません。- 型
- 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 で追加.
- 型
- tree_cls¶
使用するアプリケーションコマンドツリーの型を指定します。デフォルトは
CommandTree
です。バージョン 2.0 で追加.
- 型
Type[
CommandTree
]
- @after_invoke¶
コルーチンを、実行後に呼び出すフックとして登録するデコレータ。
実行後呼び出しフックは、コマンドが呼び出された直後に呼び出されます。 これにより、データベース接続をクリーンアップしたり、必要なクリーンアップを行うための便利な機能になります。
この実行後呼び出しフックは、
Context
を単独の引数として取ります。注釈
before_invoke()
と似て、チェックと引数展開が成功しない限り、これが呼び出されることはありません。ただし、このフックは、コマンドのエラー発生にかかわらず(例えば、CommandInvokeError
など)、常時 呼び出されます。そのため、クリーンアップするのに最適です。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @before_invoke¶
渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。
実行前呼び出しフックは、コマンドが呼び出される前に呼び出されます。 これにより、データベース接続のセットアップや、必要なセットアップを行うにあたって便利です。
この実行前呼び出しフックは、
Context
を単独の引数として取ります。注釈
before_invoke()
とafter_invoke()
は、すべてのチェックと引数解析が、例外を送出せずに渡された場合にのみ呼び出されます。 何らかのチェックまたは引数の解析に失敗した場合、これらのフックは呼び出されません。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @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()
デコレータ
- 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 で追加.
- 例外
CommandError -- 読み込み中にエラーが発生した場合。
ClientException -- 同じ名前のコグがすでに読み込まれている場合。
- add_command(command, /)¶
Command
を内部のコマンドリストに追加します。これは通常、呼び出されません。代わりに
command()
かgroup()
のショートカットデコレータが使われます。バージョン 1.4 で変更: 一般的な
ClientException
の代わりに、CommandRegistrationError
を送出します。バージョン 2.0 で変更:
command
引数は位置限定引数になりました。- パラメータ
command (
Command
) -- 追加するコマンド。- 例外
CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
- add_listener(func, /, name=...)¶
listen()
に対するデコレーターでない代替物です。バージョン 2.0 で変更:
func
引数は位置限定引数になりました。サンプル
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
) -- 実行するために登録するViewmessage_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 で追加.
- property application_id¶
クライアントのアプリケーションID。
これが
__init__
で渡されなかった場合、データを含むイベントが発生した際にゲートウェイを介して、またはlogin()
の後に取得されます。通常はon_connect()
が呼び出された後です。バージョン 2.0 で追加.
- 型
Optional[
int
]
- await application_info()¶
This function is a coroutine.
Botのアプリケーション情報を取得します。
- 例外
HTTPException -- 情報の取得に失敗した場合。
- 戻り値
Botのアプリケーション情報。
- 戻り値の型
- await before_identify_hook(shard_id, *, initial=False)¶
This function is a coroutine.
セッションをIDENTIFYingする前に、呼び出されるフック。 これは、複数の IDENTIFYing クライアントの同期を、より詳細に制御したい場合に便利です。
デフォルトでは、5秒間スリープします。
バージョン 1.4 で追加.
- 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 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 で追加.
- 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とはまた別物です。
- 戻り値の型
- await delete_invite(invite, /)¶
This function is a coroutine.
Invite
や、招待のURL、IDを削除します。これを行うには、関連付けられたGuildにて、
manage_channels
が必要です。バージョン 2.0 で変更:
invite
引数は位置限定引数になりました。- パラメータ
- 例外
Forbidden -- 削除する権限がない場合。
NotFound -- 招待が無効または期限切れの場合。
HTTPException -- 招待の取り消しに失敗した場合。
- 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から取得したギルド。
- 戻り値の型
- 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から取得した招待。
- 戻り値の型
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で取得したステージインスタンス
- 戻り値の型
- 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/コードからのテンプレート。
- 戻り値の型
- 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 -- ユーザーの取得に失敗した場合。
- 戻り値
あなたがリクエストしたユーザー。
- 戻り値の型
- 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。
- 戻り値の型
- 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のウィジェット。
- 戻り値の型
- 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
引数は位置限定引数になりました。
- get_command(name, /)¶
内部のコマンドリストから検索し、
Command
を取得します。これはコマンドのエイリアスを取得する方法としても使用できます。
名前は修飾されていても構いません(例:
'foo bar'
など)。サブコマンドが見つからなかった場合は、通常通りNone
が返されます。バージョン 2.0 で変更:
name
引数は位置限定引数になりました。
- 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
パラメータを使用して変更できます。- 戻り値の型
- get_emoji(id, /)¶
与えられた ID の絵文字を返します。
バージョン 2.0 で変更:
id
引数は位置限定引数になりました。
- get_guild(id, /)¶
与えられたIDを検索し、それに合致するGuildを返します。
バージョン 2.0 で変更:
id
引数は位置限定引数になりました。
- 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
- 戻り値の型
- await get_prefix(message, /)¶
This function is a coroutine.
特定のメッセージの文脈内でボットが使用する接頭辞を取得します。
バージョン 2.0 で変更:
message
パラメータが位置指定のみになりました。- パラメータ
message (
discord.Message
) -- 接頭辞を取得するメッセージのコンテキスト。- 戻り値
ボットが受け取る接頭辞またはそのリスト。
- 戻り値の型
- 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
引数は位置限定引数になりました。
- await invoke(ctx, /)¶
This function is a coroutine.
コンテキストに与えられたコマンドを呼び出します。すべての内部イベントも処理されます。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- 呼び出すコンテキスト。
- await is_owner(user, /)¶
This function is a coroutine.
User
またはMember
がこのボットの所有者か確認します。owner_id
が設定されていない場合、application_info()
から取得されます。バージョン 1.3 で変更:
owner_ids
が設定されていない場合、この関数はチームが所有しているかも確認します。バージョン 2.0 で変更:
user
引数は位置限定引数になりました。
- is_ws_ratelimited()¶
bool
: WebSocketがレート制限中かどうか。メンバーへのクエリをHTTPで行うか、ゲートウェイ経由で行うかを決めるときに役立ちます。
バージョン 1.6 で追加.
- property latency¶
HEARTBEATとHEARTBEAT_ACKの間の遅延を秒単位で測定します。
DiscordのWebSocketプロトコルの遅延として使うこともできます。
- 型
- await load_extension(name, *, package=None)¶
This function is a coroutine.
エクステンションを読み込みます。
エクステンションはコマンド、コグ、リスナーを含むPythonのモジュールです。
エクステンションは
setup
という名前のグローバルな関数を持っている必要があります。setup
はエクステンションを読み込むときのエントリーポイントになります。エントリーポイントはbot
という引数を持っている必要があります。バージョン 2.0 で変更: このメソッドは、coroutine です。
- パラメータ
- 例外
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 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は以前の状態にロールバックします。- パラメータ
- 例外
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 です。
- パラメータ
- 戻り値
除去されたコグ。見つからない場合は
None
。- 戻り値の型
Optional[
Cog
]
- remove_command(name, /)¶
内部のコマンドリストから該当するコマンドを検索し、その
Command
を除去します。これはコマンドのエイリアスによって、コマンドを除去することもできます。
バージョン 2.0 で変更:
name
引数は位置限定引数になりました。
- 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()
で1回だけ呼ばれ、全てのイベントが発火する前に呼ばれます。on_ready()
より良いセットアップの方法です。警告
これはWebSocket接続の 前に 呼ばれるため、WebSocketを待つ関数の呼び出しはデッドロックします。これには
wait_for()
やwait_until_ready()
が含まれます。バージョン 2.0 で追加.
- property stickers¶
接続したクライアントが持つスタンプ。
バージョン 2.0 で追加.
- 型
Sequence[
GuildSticker
]
- property tree¶
このボット内のアプリケーションコマンドを処理するコマンドツリー。
バージョン 2.0 で追加.
- await unload_extension(name, *, package=None)¶
This function is a coroutine.
拡張機能をアンロードします。
拡張機能がアンロードされると、すべてのコマンド、リスナー、コグがボットから除去され、モジュールはアンインポートされます。
拡張機能から提供される、オプションのグローバル関数
teardown
によって、必要に応じてその他のクリーンアップを行うことができます。 この関数は、load_extension()
のsetup
と似た、単一のパラメータを取ります。バージョン 2.0 で変更: このメソッドは、coroutine です。
- パラメータ
- 例外
ExtensionNotFound -- 渡された
package
パラメータを使用してエクステンションの名前を解決できなかった場合。ExtensionNotLoaded -- 拡張機能がもともとロードされていなかった場合。
- property user¶
接続されたクライアントを表します。ログインしていない場合は
None
が返されます。- 型
Optional[
ClientUser
]
- 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()
の内部でこれを呼び出すと、デッドロックになる可能性があります。
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)
イベントリファレンス¶
これらのイベントは、コマンド拡張モジュールのカスタム関数であることを除けば、 通常のイベント に似ています。
- discord.ext.commands.on_command_error(ctx, error)¶
ユーザーによる入力エラー、チェックの失敗、またはコードの記述ミスによって、コマンド内でエラーが発生したときに呼び出されるエラーハンドラ。
デフォルトは (
Bot.on_command_error()
) です。- パラメータ
ctx (
Context
) -- 呼び出しコンテキスト。error (
CommandError
derived) -- 発生したエラー。
コマンド¶
デコレータ¶
- @discord.ext.commands.command(name=..., cls=..., **attrs)¶
関数を
Command
、またはgroup()
で呼び出した場合にはGroup
に変換するデコレータです。デフォルトでは、
help
属性は、関数の docstring から自動的に取得したものをinspect.cleandoc
を使用してクリーンアップされたものを使用します。 docstring がbytes
の場合、utf-8 エンコーディングを使ってstr
にデコードされます。check()
& co.デコレータを使用して追加された、すべてのチェックを機能に追加されます。 このデコレータを通さずして、独自のチェックを提供する以外の方法はありません。
- @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
を取ります。check()
& co.デコレータを使用して追加された、すべてのチェックを機能に追加されます。 このデコレータを通さずして、独自のチェックを提供する以外の方法はありません。バージョン 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()
デコレータに似ていますが、代わりにハイブリッドグループを作成します。
Command¶
- async__call__
- defadd_check
- @after_invoke
- @before_invoke
- asynccan_run
- defcopy
- @error
- defget_cooldown_retry_after
- defhas_error_handler
- defis_on_cooldown
- defremove_check
- defreset_cooldown
- defupdate
- class discord.ext.commands.Command(*args, **kwargs)¶
Botのテキストコマンドのプロトコルを実装するクラス。
これらは手動では作成されず、デコレータまたは機能インターフェースを介して作成されます。
- enabled¶
コマンドが、現在、有効かどうかを示すbool値。コマンドが無効化されている状態で呼び出された場合、
DisabledCommand
がon_command_error()
にて発生します。デフォルトはTrue
です。- 型
- checks¶
与えられた
Context
を唯一のパラメータとしてコマンドが実行できるかどうかを確認するチェック関数のリストです。もし失敗を知らせるために例外を発生させる必要がある場合には、CommandError
から継承したものを使用する必要があります。もしチェックに失敗した場合には、on_command_error()
イベントでCheckFailure
例外が発生することに注意してください。
True
の場合、デフォルトのヘルプコマンドではヘルプ出力に表示されません。- 型
- rest_is_raw¶
もし
False
でキーワードのみの引数を指定した場合には、キーワードのみの引数は取り除かれて、残りを完全に生のまま渡すのではなく、MissingRequiredArgument
やデフォルト値を通常の引数として扱うように処理されます。もしTrue
ならば、キーワードのみの引数は、残りの引数を完全に生のまま渡します。デフォルトはFalse
です。- 型
- require_var_positional¶
もし
True
で可変長の位置引数が指定された場合、少なくとも1つの引数を指定するようユーザーに要求します。デフォルトはFalse
です。バージョン 1.5 で追加.
- 型
- ignore_extra¶
もし
True
ならば、コマンドの要求がすべて満たされていれば、余計な文字列を無視します (例:?foo a b c
でa
とb
しか期待できない場合)。そうでなければon_command_error()
とローカルのエラーハンドラがTooManyArguments
と共に呼び出されます。デフォルトはTrue
です。- 型
- cooldown_after_parsing¶
もし
True
ならば、引数解析の後にクールダウン処理が行われ、コンバータが呼び出されます。False
の場合は、クールダウン処理が最初に行われ、その後にコンバータが呼ばれます。デフォルトはFalse
です。- 型
- @after_invoke¶
コルーチンを、実行後に呼び出すフックとして登録するデコレータ。
実行後呼び出しフックは、コマンドが呼び出された直後に呼び出されます。 これにより、データベース接続をクリーンアップしたり、必要なクリーンアップを行うための便利な機能になります。
この実行後呼び出しフックは、
Context
を単独の引数として取ります。詳細は
Bot.after_invoke()
を参照してください。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @before_invoke¶
渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。
実行前呼び出しフックは、コマンドが呼び出される前に呼び出されます。 これにより、データベース接続のセットアップや、必要なセットアップを行うにあたって便利です。
この実行前呼び出しフックは、
Context
を単独の引数として取ります。詳細は
Bot.before_invoke()
を参照してください。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @error¶
コルーチンをローカルエラーハンドラとして登録するデコレータです。
ローカルエラーハンドラは、一つのコマンドに限定された
on_command_error()
イベントです。しかし、キャッチオールとしてon_command_error()
イベントはその後も呼び出されます。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- 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
パラメータは位置指定のみになりました。
- property cooldown¶
コマンドを実行したときのクールダウン。クールダウンが登録されていないコマンドの場合は
None
となります。バージョン 2.0 で追加.
- 型
Optional[
discord.app_commands.Cooldown
]
- property full_parent_name¶
完全修飾された親コマンド名を取得します。
これは実行に必要なベースコマンド名です。例えば、
?one two three
では親名はone two
になります。- 型
- 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
となります。- 型
- is_on_cooldown(ctx, /)¶
コマンドが現在クールダウン中であるかどうかを確認します。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。
- reset_cooldown(ctx, /)¶
このコマンドのクールダウンをリセットします。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- クールダウンをリセットするための呼び出しコンテキスト。
- get_cooldown_retry_after(ctx, /)¶
このコマンドを再試行できるまでの秒数を取得します。
バージョン 1.4 で追加.
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。
- property short_doc¶
コマンドの「短い」説明を取得します。
デフォルトでは、これは
brief
属性です。属性値が空の文字列であれば、代わりにhelp
属性の最初の行が使われます。- 型
- await can_run(ctx, /)¶
This function is a coroutine.
checks
属性内のすべての関数をチェックすることで、コマンドが実行可能かどうかをチェックします。また、コマンドが無効かどうかもチェックします。バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- 現在呼び出されているコマンドのコンテキスト。- 例外
CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
- 戻り値
コマンドが呼び出し可能かどうかを示すbool値。
- 戻り値の型
Group¶
- 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
です。- 型
- @after_invoke¶
コルーチンを、実行後に呼び出すフックとして登録するデコレータ。
実行後呼び出しフックは、コマンドが呼び出された直後に呼び出されます。 これにより、データベース接続をクリーンアップしたり、必要なクリーンアップを行うための便利な機能になります。
この実行後呼び出しフックは、
Context
を単独の引数として取ります。詳細は
Bot.after_invoke()
を参照してください。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @before_invoke¶
渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。
実行前呼び出しフックは、コマンドが呼び出される前に呼び出されます。 これにより、データベース接続のセットアップや、必要なセットアップを行うにあたって便利です。
この実行前呼び出しフックは、
Context
を単独の引数として取ります。詳細は
Bot.before_invoke()
を参照してください。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @command(*args, **kwargs)¶
command()
を呼び出し、add_command()
を介して内部コマンドリストに追加するショートカットデコレータ。- 戻り値
提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
- 戻り値の型
Callable[...,
Command
]
- @error¶
コルーチンをローカルエラーハンドラとして登録するデコレータです。
ローカルエラーハンドラは、一つのコマンドに限定された
on_command_error()
イベントです。しかし、キャッチオールとしてon_command_error()
イベントはその後も呼び出されます。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @group(*args, **kwargs)¶
group()
を呼び出し、add_command()
を介して内部コマンドリストに追加するショートカットデコレータ。- 戻り値
提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
- 戻り値の型
Callable[...,
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 -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
- await can_run(ctx, /)¶
This function is a coroutine.
checks
属性内のすべての関数をチェックすることで、コマンドが実行可能かどうかをチェックします。また、コマンドが無効かどうかもチェックします。バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- 現在呼び出されているコマンドのコンテキスト。- 例外
CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
- 戻り値
コマンドが呼び出し可能かどうかを示すbool値。
- 戻り値の型
- property cooldown¶
コマンドを実行したときのクールダウン。クールダウンが登録されていないコマンドの場合は
None
となります。バージョン 2.0 で追加.
- 型
Optional[
discord.app_commands.Cooldown
]
- property full_parent_name¶
完全修飾された親コマンド名を取得します。
これは実行に必要なベースコマンド名です。例えば、
?one two three
では親名はone two
になります。- 型
- get_command(name, /)¶
内部のコマンドリストから検索し、
Command
を取得します。これはコマンドのエイリアスを取得する方法としても使用できます。
名前は修飾されていても構いません(例:
'foo bar'
など)。サブコマンドが見つからなかった場合は、通常通りNone
が返されます。バージョン 2.0 で変更:
name
引数は位置限定引数になりました。
- get_cooldown_retry_after(ctx, /)¶
このコマンドを再試行できるまでの秒数を取得します。
バージョン 1.4 で追加.
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。
- is_on_cooldown(ctx, /)¶
コマンドが現在クールダウン中であるかどうかを確認します。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。
- property parents¶
このコマンドの親を取得します。
親がない場合は、空の
list
を返します。例えば、
?a b c test
では、親は[c, b, a]
です。バージョン 1.1 で追加.
- 型
List[
Group
]
- property qualified_name¶
完全修飾されたコマンド名を取得します。
これは、コマンド名を含む完全な親名称です。例えば、
?one two three
の場合、完全修飾名はone two three
となります。- 型
- remove_check(func, /)¶
コマンドからチェックを削除します。
この関数は冪等性を保持しており、関数がグローバルチェックに含まれていない場合でも例外が発生しません。
バージョン 1.3 で追加.
バージョン 2.0 で変更:
func
引数は位置限定引数になりました。- パラメータ
func -- チェックから除去する関数。
- remove_command(name, /)¶
内部のコマンドリストから該当するコマンドを検索し、その
Command
を除去します。これはコマンドのエイリアスによって、コマンドを除去することもできます。
バージョン 2.0 で変更:
name
引数は位置限定引数になりました。
- reset_cooldown(ctx, /)¶
このコマンドのクールダウンをリセットします。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- クールダウンをリセットするための呼び出しコンテキスト。
- property root_parent¶
このコマンドの大元の親を取得します。
親がない場合は、
None
を返します。例えば、
?a b c test
では、親はa
です。- 型
Optional[
Group
]
- property short_doc¶
コマンドの「短い」説明を取得します。
デフォルトでは、これは
brief
属性です。属性値が空の文字列であれば、代わりにhelp
属性の最初の行が使われます。- 型
GroupMixin¶
- defadd_command
- @command
- defget_command
- @group
- defremove_command
- defwalk_commands
- class discord.ext.commands.GroupMixin(*args, **kwargs)¶
Group
と同様に動作し、コマンドを登録可能なクラスの共通機能を実装したミックスイン。- @command(*args, **kwargs)¶
command()
を呼び出し、add_command()
を介して内部コマンドリストに追加するショートカットデコレータ。- 戻り値
提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
- 戻り値の型
Callable[...,
Command
]
- @group(*args, **kwargs)¶
group()
を呼び出し、add_command()
を介して内部コマンドリストに追加するショートカットデコレータ。- 戻り値
提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
- 戻り値の型
Callable[...,
Group
]
- add_command(command, /)¶
Command
を内部のコマンドリストに追加します。これは通常、呼び出されません。代わりに
command()
かgroup()
のショートカットデコレータが使われます。バージョン 1.4 で変更: 一般的な
ClientException
の代わりに、CommandRegistrationError
を送出します。バージョン 2.0 で変更:
command
引数は位置限定引数になりました。- パラメータ
command (
Command
) -- 追加するコマンド。- 例外
CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
- remove_command(name, /)¶
内部のコマンドリストから該当するコマンドを検索し、その
Command
を除去します。これはコマンドのエイリアスによって、コマンドを除去することもできます。
バージョン 2.0 で変更:
name
引数は位置限定引数になりました。
- for ... in walk_commands()¶
すべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。
バージョン 1.4 で変更: エイリアスによって重複した場合は、そのエイリアスまたはコマンドは返しません。
HybridCommand¶
- @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
パラメータが位置指定のみになりました。
- @autocomplete(name)¶
パラメータのオートコンプリートに使用されるコルーチンを登録するデコレータ。
これは
autocomplete()
と同じです。これはアプリケーションコマンドにのみ適用され、通常のコマンドでは何もしません。注釈
autocomplete()
メソッドと同様に、Context
ではなくInteraction
をパラメータとして取ります。
- @before_invoke¶
渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。
実行前呼び出しフックは、コマンドが呼び出される前に呼び出されます。 これにより、データベース接続のセットアップや、必要なセットアップを行うにあたって便利です。
この実行前呼び出しフックは、
Context
を単独の引数として取ります。詳細は
Bot.before_invoke()
を参照してください。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @error¶
コルーチンをローカルエラーハンドラとして登録するデコレータです。
ローカルエラーハンドラは、一つのコマンドに限定された
on_command_error()
イベントです。しかし、キャッチオールとしてon_command_error()
イベントはその後も呼び出されます。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- await can_run(ctx, /)¶
This function is a coroutine.
checks
属性内のすべての関数をチェックすることで、コマンドが実行可能かどうかをチェックします。また、コマンドが無効かどうかもチェックします。バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- 現在呼び出されているコマンドのコンテキスト。- 例外
CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
- 戻り値
コマンドが呼び出し可能かどうかを示すbool値。
- 戻り値の型
HybridGroup¶
- 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
パラメータが位置指定のみになりました。
- @autocomplete(name)¶
パラメータのオートコンプリートに使用されるコルーチンを登録するデコレータ。
これは
autocomplete()
と同じです。これはアプリケーションコマンドにのみ適用され、通常のコマンドでは何もしません。これは、フォールバックアプリケーションコマンドが登録されている場合にのみ使用できます。
注釈
autocomplete()
メソッドと同様に、Context
ではなくInteraction
をパラメータとして取ります。
- @before_invoke¶
渡されたコルーチンを、実行前呼び出しフックとして登録するデコレータ。
実行前呼び出しフックは、コマンドが呼び出される前に呼び出されます。 これにより、データベース接続のセットアップや、必要なセットアップを行うにあたって便利です。
この実行前呼び出しフックは、
Context
を単独の引数として取ります。詳細は
Bot.before_invoke()
を参照してください。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @command(*args, **kwargs)¶
hybrid_command()
を呼び出し、add_command()
を介して内部コマンドリストに追加するショートカットデコレータ。- 戻り値
提供されたメソッドをCommandに変換し、Botに追加し、さらにCommandを返すデコレータ。
- 戻り値の型
Callable[...,
HybridCommand
]
- @error¶
コルーチンをローカルエラーハンドラとして登録するデコレータです。
ローカルエラーハンドラは、一つのコマンドに限定された
on_command_error()
イベントです。しかし、キャッチオールとしてon_command_error()
イベントはその後も呼び出されます。バージョン 2.0 で変更:
coro
パラメータが位置指定のみになりました。
- @group(*args, **kwargs)¶
hybrid_group()
を呼び出し、add_command()
を介して内部コマンドリストに追加するショートカットデコレータ。- 戻り値
提供されたメソッドをGroupに変換し、Botに追加し、そしてGroupを返すデコレータ。
- 戻り値の型
Callable[...,
HybridGroup
]
- await can_run(ctx, /)¶
This function is a coroutine.
checks
属性内のすべての関数をチェックすることで、コマンドが実行可能かどうかをチェックします。また、コマンドが無効かどうかもチェックします。バージョン 1.3 で変更: コマンドが無効であるかどうかをチェックします。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。- パラメータ
ctx (
Context
) -- 現在呼び出されているコマンドのコンテキスト。- 例外
CommandError -- チェック中に発生したコマンドエラーは、この関数によってキャッチされます。
- 戻り値
コマンドが呼び出し可能かどうかを示すbool値。
- 戻り値の型
- add_check(func, /)¶
コマンドにチェックを追加します。
これは
check()
に対する非デコレーターインターフェイスです。バージョン 1.3 で追加.
バージョン 2.0 で変更:
func
引数は位置限定引数になりました。参考
check()
デコレータ- パラメータ
func -- チェックとして使用される関数。
- add_command(command, /)¶
HybridCommand
を内部のコマンドリストに追加します。これは通常、呼び出されません。代わりに
command()
かgroup()
のショートカットデコレータが使われます。- パラメータ
command (
HybridCommand
) -- 追加するコマンド。- 例外
CommandRegistrationError -- コマンドやその別名が異なるコマンドによって、すでに登録されている場合。
TypeError -- 渡されたコマンドが、
HybridCommand
のサブクラスでない場合。
- property cooldown¶
コマンドを実行したときのクールダウン。クールダウンが登録されていないコマンドの場合は
None
となります。バージョン 2.0 で追加.
- 型
Optional[
discord.app_commands.Cooldown
]
- property full_parent_name¶
完全修飾された親コマンド名を取得します。
これは実行に必要なベースコマンド名です。例えば、
?one two three
では親名はone two
になります。- 型
- get_command(name, /)¶
内部のコマンドリストから検索し、
Command
を取得します。これはコマンドのエイリアスを取得する方法としても使用できます。
名前は修飾されていても構いません(例:
'foo bar'
など)。サブコマンドが見つからなかった場合は、通常通りNone
が返されます。バージョン 2.0 で変更:
name
引数は位置限定引数になりました。
- get_cooldown_retry_after(ctx, /)¶
このコマンドを再試行できるまでの秒数を取得します。
バージョン 1.4 で追加.
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。
- is_on_cooldown(ctx, /)¶
コマンドが現在クールダウン中であるかどうかを確認します。
バージョン 2.0 で変更:
ctx
パラメータは位置指定のみになりました。
- property parents¶
このコマンドの親を取得します。
親がない場合は、空の
list
を返します。例えば、
?a b c test
では、親は[c, b, a]
です。バージョン 1.1 で追加.
- 型
List[
Group
]
- property qualified_name¶
完全修飾されたコマンド名を取得します。
これは、コマンド名を含む完全な親名称です。例えば、
?one two three
の場合、完全修飾名はone two three
となります。- 型
- 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
属性の最初の行が使われます。- 型
- update(**kwargs)¶
Command
インスタンスを更新された属性で更新します。これは
command()
デコレーターと同様に動作します。パラメータはCommand
やサブクラスのコンストラクターに渡され、名前とコールバックは除かれます。
- for ... in walk_commands()¶
すべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。
バージョン 1.4 で変更: エイリアスによって重複した場合は、そのエイリアスまたはコマンドは返しません。
Cogs¶
Cog¶
- 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
のインスタンスは 含まれません 。
- get_app_commands()¶
このコグ内で定義されているアプリケーションコマンドを返します。
- 戻り値
このコグ内で定義されている、サブコマンドを除いた
discord.app_commands.Command
とdiscord.app_commands.Group
のlist
。- 戻り値の型
List[Union[
discord.app_commands.Command
,discord.app_commands.Group
]]
- for ... in walk_commands()¶
このコグのすべてのコマンドとサブコマンドを、再帰的に網羅するイテレータ。
- for ... in walk_app_commands()¶
このコグのすべてのアプリケーションコマンドとサブコマンドを、再帰的に網羅するイテレータ。
- 列挙
Union[
discord.app_commands.Command
,discord.app_commands.Group
] -- コグのアプリケーションコマンドまたはグループ。
- property app_command¶
このコグに関連付けられたグループを返します。
GroupCog
から継承する場合にのみ使用できます。- 型
Optional[
discord.app_commands.Group
]
- classmethod listener(name=...)¶
関数をリスナーとしてマークするデコレータ。
これはコグの
Bot.listen()
に相当するものです。
- 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¶
- 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
- 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
- 型
- 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 で追加.
- 型
- group_auto_locale_strings¶
これが
True
に設定されている場合、翻訳可能な文字列はstr
ではなく暗黙的にlocale_str
にラップされます。デフォルトはTrue
です。バージョン 2.0 で追加.
- 型
ヘルプコマンド¶
HelpCommand¶
- 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
]
隠しコマンドを表示するかどうかを指定します。デフォルトでは
False
です。- 型
- verify_checks¶
コマンドが、
Command.checks
を呼び出し検証すべきかを指定します。もしTrue
なら、常にCommand.checks
を呼び出します。もしNone
なら、ギルドでのみCommand.checks
を呼び出します。もしFalse
なら、Command.checks
は一切呼び出しません。デフォルトはTrue
です。バージョン 1.7 で変更.
- 型
Optional[
bool
]
- command_attrs¶
ヘルプコマンドの構築のために渡すオプションの辞書。 これにより、実際にヘルプコマンドの実装を変更することなく、その動作を変更できます。 属性は
Command
コンストラクタで渡されたものと同じになります。- 型
- 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
引数は位置限定引数になりました。
- remove_mentions(string, /)¶
不正使用を防ぐために文字列からメンションを除去します。
これには
@everyone
、@here
、 メンバーメンションとロールメンションが含まれます。バージョン 2.0 で変更:
string
引数は位置限定引数になりました。- 戻り値
メンションが除去された文字列。
- 戻り値の型
- property cog¶
ヘルプコマンドのコグを取得または設定するためのプロパティ。
ヘルプコマンドにコグが設定されている場合は、ヘルプコマンドがそのコグに属している場合と同様です。 コグの特別なメソッドはすべてヘルプコマンドに適用され、アンロード時に自動的にアンロードされます。
コグをヘルプコマンドから解除するには、
None
を設定します。- 戻り値
ヘルプコマンドに現在設定されているコグ。
- 戻り値の型
Optional[
bool
]
- command_not_found(string, /)¶
This function could be a coroutine.
ヘルプコマンドでコマンドが見つからない場合に呼び出されるメソッド。これは、i18nでオーバーライドするのに便利です。
デフォルトは
No command called {0} found.
です。バージョン 2.0 で変更:
string
引数は位置限定引数になりました。
- 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
のパラメータは位置指定のみになりました。
- await filter_commands(commands, /, *, sort=False, key=None)¶
This function is a coroutine.
フィルタリングされたコマンドのリストを返し、必要に応じて並び替えます。
これは
verify_checks
とshow_hidden
属性を考慮します。バージョン 2.0 で変更:
commands
引数は位置限定引数になりました。
- get_max_size(commands, /)¶
指定されたコマンドリストの中の名前の最大の長さを返します。
バージョン 2.0 で変更:
commands
引数は位置限定引数になりました。
- get_destination()¶
ヘルプコマンドが出力される
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
引数は位置限定引数になりました。
- await send_cog_help(cog, /)¶
This function is a coroutine.
ヘルプコマンドでコグページの実装を処理します。 この関数は、ヘルプコマンドがコグを引数として呼び出されたときに呼び出されます。
このメソッドは何も返さないことに注意してください -- むしろ実際のメッセージ送信はこのメソッド内で行う必要があります。 適切な振る舞いをするサブクラスは、他のユーザ向けにカスタマイズする箇所であるため、どこに送信するかを知るために
get_destination()
を使用する必要があります。このメソッドをオーバーライドして動作をカスタマイズできます。
注釈
HelpCommand.context
で呼び出しコンテキストにアクセスできます。このコグに属するコマンドを取得するには、
Cog.get_commands()
を確認してください。返されるコマンドはフィルタリングされていません。フィルタリングをするには、自分でfilter_commands()
を呼び出す必要があるでしょう。バージョン 2.0 で変更:
cog
引数は位置限定引数になりました。- パラメータ
cog (
Cog
) -- ヘルプを要求されたコグ。
- await send_group_help(group, /)¶
This function is a coroutine.
ヘルプコマンドでグループページの実装を処理します。 この関数は、ヘルプコマンドがグループを引数として呼び出されたときに呼び出されます。
このメソッドは何も返さないことに注意してください -- むしろ実際のメッセージ送信はこのメソッド内で行う必要があります。 適切な振る舞いをするサブクラスは、他のユーザ向けにカスタマイズする箇所であるため、どこに送信するかを知るために
get_destination()
を使用する必要があります。このメソッドをオーバーライドして動作をカスタマイズできます。
注釈
HelpCommand.context
で呼び出しコンテキストにアクセスできます。このコグに属するコマンドを別名を除いて取得するには、
Group.commands
を確認してください。返されるコマンドはフィルタリングされていません。フィルタリングをするには、自分でfilter_commands()
を呼び出す必要があるでしょう。バージョン 2.0 で変更:
group
引数は位置限定引数になりました。- パラメータ
group (
Group
) -- ヘルプを要求されたグループ。
- await send_command_help(command, /)¶
This function is a coroutine.
ヘルプコマンドで単一のコマンドページの実装を処理します。
このメソッドは何も返さないことに注意してください -- むしろ実際のメッセージ送信はこのメソッド内で行う必要があります。 適切な振る舞いをするサブクラスは、他のユーザ向けにカスタマイズする箇所であるため、どこに送信するかを知るために
get_destination()
を使用する必要があります。このメソッドをオーバーライドして動作をカスタマイズできます。
注釈
HelpCommand.context
で呼び出しコンテキストにアクセスできます。ヘルプを表示
以下のような、ヘルプコマンドに役立つ属性やメソッドがあります。
これら以外にももっと属性はありますが、欲しい出力を得るのを助けてくれるこいつらで遊ぶことに開放感を感じてみてください。
バージョン 2.0 で変更:
command
引数は位置限定引数になりました。- パラメータ
command (
Command
) -- ヘルプを要求されたコマンド。
- await prepare_help_command(ctx, command=None, /)¶
This function is a coroutine.
ヘルプコマンドを準備するのに使用できる低レベルのメソッドです。 例えば、 コマンドが処理する前にサブクラスの状態を準備する必要がある場合は、ここで行うことができます。
デフォルトの実装では何もしません。
注釈
これは 内部 ヘルプコマンドコールバック本体と呼ばれていますので、内部で発生する通常のルールはすべてここでも適用されます。
バージョン 2.0 で変更:
ctx
とcommand
引数は位置限定引数になりました。
DefaultHelpCommand¶
- class discord.ext.commands.DefaultHelpCommand(*args, **kwargs)¶
デフォルトのヘルプコマンドの実装。
これは
HelpCommand
から継承されます。以下の属性で拡張されます。
- 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
]
- arguments_heading¶
コマンド名を指定してhelpコマンドを実行したときに使用される引数リストの見出し文字列です。国際化対応に便利です。デフォルトは
"Arguments:"
です。show_parameter_descriptions
がTrue
の場合に表示されます。バージョン 2.0 で追加.
- 型
- show_parameter_descriptions¶
パラメータの説明を表示するかどうか。デフォルトは
True
です。False
に設定すると、代わりにsignature
が表示されるようになります。バージョン 2.0 で追加.
- 型
- default_argument_description¶
引数の
description
がNone
である場合に使用される、デフォルトの引数の説明文字列です。国際化対応に便利です。デフォルトは"No description given."
です。バージョン 2.0 で追加.
- 型
- get_command_signature(command, /)¶
ヘルプページに表示される、コマンドの使用方法を示す文字列を返します。
show_parameter_descriptions
がFalse
の場合にget_command_signature()
を呼び出し、それ以外の場合はコマンドパラメータを表示しない修正したシグネチャを返します。バージョン 2.0 で追加.
- 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
) -- 引数の一覧を表示するコマンド。
- add_command_formatting(command, /)¶
コマンドとグループのインデントされていないブロックをフォーマットするユーティリティ関数。
バージョン 2.0 で変更:
command
引数は位置限定引数になりました。バージョン 2.0 で変更:
add_command_arguments()
はshow_parameter_descriptions
がTrue
であれば呼び出されるようになりました。- パラメータ
command (
Command
) -- フォーマットするコマンド。
- get_destination()¶
ヘルプコマンドが出力される
Messageable
を返します。このメソッドをオーバーライドして動作をカスタマイズできます。
デフォルトでは、コンテキストのチャンネルを返します。
- 戻り値
ヘルプコマンドの出力先。
- 戻り値の型
MinimalHelpCommand¶
- class discord.ext.commands.MinimalHelpCommand(*args, **kwargs)¶
最小限の出力を持つヘルプコマンドの実装。
これは
HelpCommand
から継承されます。- 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
]
- 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.
- 戻り値
ヘルプコマンドの冒頭の文字列。
- 戻り値の型
- get_command_signature(command, /)¶
ヘルプページに表示される、コマンドの使用方法を示す文字列を返します。
バージョン 2.0 で変更:
command
引数は位置限定引数になりました。
- get_ending_note()¶
ヘルプコマンドの末尾の文字列を返します。主に翻訳する際にオーバーライドしてください。
デフォルトの実装では何もしません。
- 戻り値
ヘルプコマンドの末尾の文字列。
- 戻り値の型
- add_bot_commands_formatting(commands, heading, /)¶
出力に小さなボットの見出しとコマンドを追加します。
書式は
paginator
に追加すべきです。デフォルトの実装では、太字の下線の見出しに続いて、次の行にEN スペース (U+2002) で区切られたコマンドが出力されます。
バージョン 2.0 で変更:
commands
とheading
引数は位置限定引数になりました。
- 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
を返します。このメソッドをオーバーライドして動作をカスタマイズできます。
デフォルトでは、コンテキストのチャンネルを返します。
- 戻り値
ヘルプコマンドの出力先。
- 戻り値の型
Paginator¶
- class discord.ext.commands.Paginator(prefix='```', suffix='```', max_size=2000, linesep='\n')¶
Discordメッセージのコードブロックをページに分割するのに役立つクラス。
- len(x)
ペジネーター内の文字数の合計を返します。
- clear()¶
ページネーターのページを消去します。
- add_line(line='', *, empty=False)¶
現在のページに行を追加します。
行が
max_size
を超えると、例外が発生します。- パラメータ
- 例外
RuntimeError -- 現在の
max_size
に対し行が大きすぎる場合。
- close_page()¶
ページを改めます。
列挙型¶
- 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
引数は位置限定引数になりました。
- @discord.ext.commands.check_any(*checks)¶
渡されたチェックのいずれかが合格するか、すなわち論理ORを使用するかをチェックする追加された
check()
。すべてのチェックに失敗した場合、
CheckAnyFailure
が発生して失敗したことを通知します。これはCheckFailure
を継承します。注釈
この関数の
predicate
属性は**コルーチン**です。バージョン 1.3 で追加.
サンプル
ボットの所有者かサーバーの所有者かを確認するための基本的なチェックの作成なら:
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
を返します。このチェックは2つの特別な例外のうち1つ、もしユーザがロールを持っていないなら
MissingRole
を、プライベートメッセージで使用されたならNoPrivateMessage
を発生します。どちらもCheckFailure
を継承します。バージョン 1.1 で変更: 一般的な
CheckFailure
の代わりにMissingRole
またはNoPrivateMessage
を発生させます。バージョン 2.0 で変更:
item
引数は位置限定引数になりました。
- @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 returnTrue
.has_role()
と同様に、渡された名前やIDは正確でなければなりません。このチェックは2つの特別な例外のうち1つ、もしユーザがロールをすべて持っていないなら
MissingAnyRole
を、プライベートメッセージで使用されたならNoPrivateMessage
を発生します。どちらもCheckFailure
を継承します。バージョン 1.1 で変更: 一般的な
CheckFailure
の代わりにMissingAnyRole
またはNoPrivateMessage
を発生させます。サンプル
@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()
と同様です。このチェックは2つの特別な例外のうち1つ、もしボットがロールを持っていないなら
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()
と同様です。このチェックは2つの特別な例外のうち1つ、もしボットがどのロールも持っていないなら
BotMissingAnyRole
を、プライベートメッセージで使用されたならNoPrivateMessage
を発生します。どちらもCheckFailure
を継承します。バージョン 1.1 で変更: 一般的なCheckFailureの代わりに
BotMissingAnyRole
またはNoPrivateMessage
を発生させます。
- @discord.ext.commands.cooldown(rate, per, type=discord.ext.commands.BucketType.default)¶
Command
にクールダウンを追加するデコレーター。クールダウンにより、コマンドは特定の時間枠内でのみ使用することができます。 これらのクールダウンは、ギルドごと、チャンネルごと、ユーザごと、ロールごと、またはグローバル基準のいずれかに基づくことができます。 列挙型
BucketType
でなければならない第3引数type
によって示されます。クールダウンが発生した場合、
CommandOnCooldown
がon_command_error()
とローカルのエラーハンドラに引っかかります。コマンドは1つのクールダウンしか持つことができません。
- パラメータ
rate (
int
) -- クールダウンを発生させる前にコマンドを使用できる回数。per (
float
) -- トリガーされたときにクールダウンを待つ秒数。type (Union[
BucketType
, Callable[[Context
], Any]]) --持っているクールダウンの種類。呼び出し可能な場合は、マッピングのキーを返す必要があります。
バージョン 1.7 で変更: カスタムされたBucketタイプの呼び出しをサポートするようになりました。
- @discord.ext.commands.dynamic_cooldown(cooldown, type)¶
Command
に動的なクールダウンを追加するデコレータ。これは唯一のパラメータに
Context
を取り、Cooldown
またはNone
を返す関数を取るという点でcooldown()
と異なります。もしNone
を返せば、クールダウンは事実上回避されます。クールダウンにより、コマンドは特定の時間枠内でのみ使用することができます。 これらのクールダウンは、ギルドごと、チャンネルごと、ユーザごと、ロールごと、またはグローバル基準のいずれかに基づくことができます。 列挙型
BucketType
でなければならない第3引数type
によって示されます。クールダウンが発生した場合、
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¶
- 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は一時的なメッセージ同様無効です。
- 型
- args¶
コマンドに渡された変換された引数のリスト。 もしこれが
on_command_error()
イベント中にアクセスされた場合、このリストは不完全である可能性があります。- 型
- kwargs¶
コマンドに渡された変換された引数の辞書。
args
と似ていて、もしこれがon_command_error()
イベント中にアクセスされた場合、この辞書は不完全である可能性があります。- 型
- current_argument¶
現在変換されている
current_parameter
の引数文字列。これはコンバーター内でのみ使用されます。バージョン 2.0 で追加.
- 型
Optional[
str
]
- interaction¶
このコンテキストに関連付けられたインタラクション。
バージョン 2.0 で追加.
- 型
Optional[
Interaction
]
- prefix¶
コマンドを呼び出すために使用された接頭辞。インタラクションベースのコンテキストでは、スラッシュコマンドでは
/
で、コンテキストメニューコマンドでは\u200b
です。- 型
Optional[
str
]
- invoked_parents¶
この呼び出しを引き起こした親のコマンドの名前。コマンドを呼び出した別名を突き止めるのに役立ちます。
例えば、
?a b c test
では、呼び出された親は['a', 'b', 'c']
です。バージョン 1.7 で追加.
- 型
List[
str
]
- subcommand_passed¶
サブコマンドの呼び出しを試みた文字列。 これは有効な登録されたサブコマンドを指す必要はなく、無茶な文字列を指すだけとなり得ます。 サブコマンドへの呼び出しに何も渡されなかった場合、これは
None
に設定されます。- 型
Optional[
str
]
- 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
引数は位置限定引数になりました。
- await reinvoke(*, call_hooks=False, restart=True)¶
This function is a coroutine.
コマンドを再度呼び出します。
これはチェック、クールダウン、エラーハンドラが回避されていることを除き、
invoke()
と同様です。注釈
派生した例外の
UserInputError
を回避したい場合は、より自然に動作する標準のinvoke()
を使用することをお勧めします。結局のところ、これはユーザが使用した古い引数を使用することになり、したがって再び失敗します。- パラメータ
- 例外
ValueError -- 再呼び出しするコンテキストが無効です。
- property clean_prefix¶
「クリーンアップ」されたプレフィックスを返します。たとえば、メンションは
<@id>
のかわりに@name
となります。バージョン 2.0 で追加.
- 型
- 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 で追加.
- bot_permissions¶
このチャンネルでのボットの解決された権限を返します。
abc.GuildChannel.permissions_for()
とInteraction.app_permissions
のショートカットです。インタラクションベースのコマンドでは、これは
Context
呼び出しにて有効な権限を反映していて、channel
のような他のabc.Messageable
に適用されるものと異なる可能性があります。特に、メッセージの送信、埋め込みリンク、ファイルの添付は常に許可されていますが、メッセージを読むことはできない場合があります。
バージョン 2.0 で追加.
- property voice_client¶
該当する場合は、
Guild.voice_client
へのショートカット。- 型
Optional[
VoiceProtocol
]
- await send_help(entity=<bot>)¶
This function is a coroutine.
指定されたエンティティのヘルプコマンドを表示します。エンティティはコマンドまたはコグになることができます。
エンティティが指定されていない場合は、ボット全体のヘルプが表示されます。
エンティティが文字列の場合、
Cog
またはCommand
を検索します。注釈
この関数の動作によっては、
command_not_found()
のようなものを返す代わりに、不正な入力またはヘルプコマンドがない際にNone
を返します。
- 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
の両方が指定されています。
- 戻り値
送信されたメッセージ。
- 戻り値の型
- 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 -- メッセージの取得に失敗した場合。
- 戻り値
要求されたメッセージ。
- 戻り値の型
- 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
でない場合。
- 戻り値
送信されたメッセージ。
- 戻り値の型
コンバーター¶
- asyncconvert
- class discord.ext.commands.Converter(*args, **kwargs)¶
Context
を渡す必要のあるカスタムコンバーターの基底クラス。これにより、スペシャルケースの
discord
クラスと似たコンバーターを実装できます。サブクラスは
convert()
メソッドを上書きして変換ロジックを実装すべきです。このメソッドは coroutine でないといけません。- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.GuildChannelConverter(*args, **kwargs)¶
GuildChannel
に変換します。すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。
検索は以下の順で行われます:
IDで検索
メンションで検索
名前で検索
バージョン 2.0 で追加.
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.StageChannelConverter(*args, **kwargs)¶
StageChannel
に変換します。バージョン 1.7 で追加.
すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。
検索は以下の順で行われます:
IDで検索
メンションで検索
名前 で検索
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.ForumChannelConverter(*args, **kwargs)¶
ForumChannel
に変換します。すべて検索は現在のギルドで行われます。DMでは、グローバルキャッシュが使用されます。
検索は以下の順で行われます:
IDで検索
メンションで検索
名前 で検索
バージョン 2.0 で追加.
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.GuildConverter(*args, **kwargs)¶
Guild
に変換します。検索は以下の順で行われます:
IDで検索
名前で検索。(名前が一致するギルドの曖昧さ回避は行われません。)
バージョン 1.7 で追加.
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.GameConverter(*args, **kwargs)¶
Game
に変換します。- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- 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
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.PartialEmojiConverter(*args, **kwargs)¶
PartialEmoji
に変換します。これは絵文字からアニメーションフラグ、名前、IDを抽出することによって行われます。
バージョン 1.5 で変更: 一般的な
BadArgument
の代わりにPartialEmojiConversionFailure
を発生させます。- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.ThreadConverter(*args, **kwargs)¶
Thread
に変換します。すべての検索はローカルギルドを経由して行われます。
検索は以下の順で行われます:
IDで検索
メンションで検索
名前で検索
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.GuildStickerConverter(*args, **kwargs)¶
GuildSticker
に変換します。すべて検索は利用できる場合まず現在のギルドで行われます。失敗した場合、グローバルキャッシュが使用されます。
検索は以下の順で行われます:
IDで検索
名前で検索
バージョン 2.0 で追加.
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.ScheduledEventConverter(*args, **kwargs)¶
ScheduledEvent
に変換します。可能な場合は、ローカルギルドに対して検索が行われます。それ以外の場合は、DMコンテキストでは、ルックアップはグローバルキャッシュによって行われます。
検索は以下の順で行われます:
IDで検索
URL で検索する。
名前で検索
バージョン 2.0 で追加.
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
CommandError -- 引数変換中に一般的なエラーが発生した場合。
BadArgument -- 引数の変換に失敗した場合。
- asyncconvert
- class discord.ext.commands.clean_content(*, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False, remove_markdown=False)¶
引数を、メンションを削ぎ落とされたコンテンツに変換します。
これは
clean_content
と同様に動作します。- remove_markdown¶
特殊なマークダウン文字も除去するかどうか。このオプションは
escape_markdown
と一緒にはサポートされていません。バージョン 1.7 で追加.
- 型
- await convert(ctx, argument)¶
This function is a coroutine.
変換ロジックを行うために上書きすべきメソッド。
変換中にエラーが発生した場合、エラーハンドラーに適切に伝播させるために
CommandError
から派生する例外を送出することをおすすめします。- パラメータ
- 例外
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 で追加.
- パラメータ
- 例外
CommandError -- コンバータが変換に失敗しました。
- 戻り値
変換の結果
- 戻り値の型
Any
Flag Converter¶
- class discord.ext.commands.FlagConverter¶
ユーザに優しいフラグ構文を可能にするコンバータ。
フラグはPythonモジュールの
dataclasses
と同様に PEP 526 の型アノテーションを用いて定義されています。どのようにしてこのコンバータが動作するかの詳細については、当該の ドキュメント を確認してください。- iter(x)
(flag_name, flag_value)
ペアのイテレータを返します。 これにより、例えば、辞書型やペアのリストに変換できます。別名は表示されないことに注意してください。
バージョン 2.0 で追加.
- パラメータ
- class discord.ext.commands.Flag¶
FlagConverter
のフラグパラメータを表します。flag()
関数はこれらのフラグオブジェクトを作成するのに役立ちますが、必須ではありません。これらは手動で構築することはできません。- default¶
利用可能であれば、フラグのデフォルト値。
- 型
Any
- annotation¶
基礎評価済みのフラグのアノテーション。
- 型
Any
- 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
) -- フラグの説明。ハイブリッドコマンドがアプリケーションコマンドとして使用されたときに表示されます。
既定値¶
- 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 converter¶
このパラメータに使用すべきコンバーター。
- property displayed_default¶
Command.signature
で表示される既定値。- 型
Optional[
str
]
- 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:')
- discord.ext.commands.param(*, converter, default, description, displayed_default)¶
param(*, converter=..., default=..., description=..., displayed_default=...)
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¶
失敗したコンバーター。
- exception discord.ext.commands.MissingRequiredArgument(param)¶
コマンドのパラメータ解析の際、要求されたパラメータに値が渡されていない場合に発生します。
これは
UserInputError
から継承されます。
- exception discord.ext.commands.MissingRequiredAttachment(param)¶
コマンドのパラメータ解析の際、添付ファイルを必要とするパラメータが与えられていない場合に発生します。
これは
UserInputError
から継承されます。バージョン 2.0 で追加.
- exception discord.ext.commands.ArgumentParsingError(message=None, *args)¶
パーサーがユーザーの入力の解析に失敗したときに発生する例外。
これは
UserInputError
から継承されます。i18n のためにより細かい解析エラーを実装するサブクラスがあります。
- exception discord.ext.commands.UnexpectedQuoteError(quote)¶
パーサーが引用符で囲まれていない文字列の中で引用符に遭遇したときに発生する例外。
これは
ArgumentParsingError
から継承されます。
- exception discord.ext.commands.InvalidEndOfQuotedStringError(char)¶
文字列の引用符が閉じられた後に空白が期待されるとき、別の文字が見つかった場合の例外。
これは
ArgumentParsingError
から継承されます。
- exception discord.ext.commands.ExpectedClosingQuoteError(close_quote)¶
引用符が期待されているが見つからない場合に発生する例外。
これは
ArgumentParsingError
から継承されます。
- exception discord.ext.commands.BadArgument(message=None, *args)¶
コマンドの引数に渡された値の解析、または変換に失敗した場合に発生する例外。
これは
UserInputError
から継承されます。
- exception discord.ext.commands.BadUnionArgument(param, converters, errors)¶
typing.Union
コンバーターが対応するすべての型に対して失敗した場合に発生する例外。これは
UserInputError
から継承されます。- param¶
変換に失敗したパラメータ。
- converters¶
変換しようとして失敗したコンバーターの、失敗した順のタプル。
- 型
Tuple[Type,
...
]
- errors¶
変換失敗時に捕捉されたエラーのリスト。
- 型
List[
CommandError
]
- exception discord.ext.commands.BadLiteralArgument(param, literals, errors)¶
typing.Literal
コンバーターが対応するすべての値に対して失敗した場合に発生する例外。これは
UserInputError
から継承されます。バージョン 2.0 で追加.
- param¶
変換に失敗したパラメータ。
- 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
]
- 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