Commands Ext#
The commands ext is meant purely for creating twitch chatbots. It gives you powerful tools, including dynamic loading/unloading/reloading of modules, organization of code using Cogs, and of course, commands.
Bot#
- clsBot.from_client_credentials
- defadd_cog
- defadd_command
- asyncclose
- defcommand
- asyncconnect
- defcreate_user
- asyncdelete_videos
- asyncevent_channel_join_failure
- asyncevent_channel_joined
- asyncevent_command_error
- asyncevent_error
- asyncevent_join
- asyncevent_message
- asyncevent_mode
- asyncevent_notice
- asyncevent_part
- asyncevent_raw_data
- asyncevent_raw_notice
- asyncevent_raw_usernotice
- asyncevent_ready
- asyncevent_reconnect
- asyncevent_token_expired
- asyncevent_usernotice_subscription
- asyncevent_userstate
- asyncfetch_channel
- asyncfetch_channels
- asyncfetch_chatters_colors
- asyncfetch_cheermotes
- asyncfetch_clips
- asyncfetch_games
- asyncfetch_global_chat_badges
- asyncfetch_global_emotes
- asyncfetch_streams
- asyncfetch_tags
- asyncfetch_teams
- asyncfetch_top_games
- asyncfetch_users
- asyncfetch_videos
- defget_channel
- defget_cog
- defget_command
- asyncget_context
- asyncget_webhook_subscriptions
- asyncglobal_after_invoke
- asyncglobal_before_invoke
- asynchandle_commands
- asyncjoin_channels
- defload_module
- asyncpart_channels
- defreload_module
- defremove_cog
- defremove_command
- defrun
- asyncsearch_categories
- asyncsearch_channels
- asyncstart
- defunload_module
- asyncupdate_chatter_color
- asyncwait_for
- asyncwait_for_ready
- class twitchio.ext.commands.Bot(token: str, *, prefix: Union[str, list, tuple, set, Callable, Coroutine], client_secret: Optional[str] = None, initial_channels: Optional[Union[list, tuple, Callable]] = None, heartbeat: Optional[float] = 30.0, retain_cache: Optional[bool] = True, **kwargs)#
- add_cog(cog: Cog)#
Method which adds a cog to the bot.
- Parameters
cog (
Cog
) – The cog instance to add to the bot.
Warning
This must be an instance of
Cog
.
- add_command(command: Command)#
Method which registers a command for use by the bot.
- Parameters
command (
Command
) – The command to register.
- command(*, name: ~typing.Optional[str] = None, aliases: ~typing.Optional[~typing.Union[list, tuple]] = None, cls=<class 'twitchio.ext.commands.core.Command'>, no_global_checks=False) Callable[[Callable], Command] #
Decorator which registers a command with the bot.
Commands must be a coroutine.
- Parameters
name (str [Optional]) – The name of the command. By default if this is not supplied, the function name will be used.
aliases (Optional[Union[list, tuple]]) – The command aliases. This must be a list or tuple.
cls (class [Optional]) – The custom command class to override the default class. This must be similar to
Command
.no_global_checks (Optional[bool]) – Whether or not the command should abide by global checks. Defaults to False, which checks global checks.
- Raises
TypeError – cls is not type class.
- create_user(user_id: int, user_name: str) PartialUser #
A helper method to create a
twitchio.PartialUser
from a user id and user name.- Parameters
- Returns
- coroutine delete_videos(token: str, ids: List[int]) List[int] #
This function is a coroutine.
Delete videos from the api. Returns the video ids that were successfully deleted.
- coroutine event_channel_join_failure(channel: str)#
This function is a coroutine.
Event called when the bot fails to join a channel.
- Parameters
channel (str) – The channel name that was attempted to be joined.
- coroutine event_channel_joined(channel: Channel)#
This function is a coroutine.
Event called when the bot joins a channel.
- Parameters
channel (
Channel
) – The channel that was joined.
- coroutine event_command_error(context: Context, error: Exception) None #
This function is a coroutine.
Event called when an error occurs during command invocation.
- coroutine event_error(error: Exception, data: Optional[str] = None)#
This function is a coroutine.
Event called when an error occurs while processing data.
- Parameters
Example
@bot.event() async def event_error(error, data): traceback.print_exception(type(error), error, error.__traceback__, file=sys.stderr)
- coroutine event_join(channel: Channel, user: User)#
This function is a coroutine.
Event called when a JOIN is received from Twitch.
- coroutine event_message(message: Message) None #
This function is a coroutine.
Event called when a PRIVMSG is received from Twitch.
- Parameters
message (
Message
) – Message object containing relevant information.
- coroutine event_mode(channel: Channel, user: User, status: str)#
This function is a coroutine.
Event called when a MODE is received from Twitch.
- coroutine event_notice(message: str, msg_id: Optional[str], channel: Optional[Channel])#
This function is a coroutine.
Event called with the NOTICE data received by Twitch.
Tip
For more information on NOTICE msg_ids visit: https://dev.twitch.tv/docs/irc/msg-id/
- Parameters
Example
@bot.event() async def event_notice(message, msg_id, channel): print(message)
- coroutine event_part(user: User)#
This function is a coroutine.
Event called when a PART is received from Twitch.
- Parameters
user (
User
) – User object containing relevant information to the PART.
- coroutine event_raw_data(data: str)#
This function is a coroutine.
Event called with the raw data received by Twitch.
- Parameters
data (str) – The raw data received from Twitch.
Example
@bot.event() async def event_raw_data(data): print(data)
- coroutine event_raw_notice(data: str)#
This function is a coroutine.
Event called with the raw NOTICE data received by Twitch.
- Parameters
data (str) – The raw NOTICE data received from Twitch.
Example
@bot.event() async def event_raw_notice(data): print(data)
- coroutine event_raw_usernotice(channel: Channel, tags: dict)#
This function is a coroutine.
Event called when a USERNOTICE is received from Twitch. Since USERNOTICE’s can be fairly complex and vary, the following sub-events are available:
event_usernotice_subscription()
: Called when a USERNOTICE Subscription or Re-subscription event is received.Tip
For more information on how to handle USERNOTICE’s visit: https://dev.twitch.tv/docs/irc/tags/#usernotice-twitch-tags
- coroutine event_ready()#
This function is a coroutine.
Event called when the Bot has logged in and is ready.
Example
@bot.event() async def event_ready(): print(f'Logged into Twitch | {bot.nick}')
- coroutine event_reconnect()#
This function is a coroutine.
Event called when twitch sends a RECONNECT notice. The library will automatically handle reconnecting when such an event is received
- coroutine event_token_expired()#
This function is a coroutine.
A special event called when the oauth token expires. This is a hook into the http system, it will call this when a call to the api fails due to a token expiry. This function should return either a new token, or None. Returning None will cause the client to attempt an automatic token generation.
Note
This event is a callback hook. It is not a dispatched event. Any errors raised will be passed to the
event_error()
event.
- coroutine event_usernotice_subscription(metadata)#
This function is a coroutine.
Event called when a USERNOTICE subscription or re-subscription event is received from Twitch.
- Parameters
metadata (
NoticeSubscription
) – The object containing various metadata about the subscription event. For ease of use, this contains aUser
andChannel
.
- coroutine event_userstate(user: User)#
This function is a coroutine.
Event called when a USERSTATE is received from Twitch.
- Parameters
user (
User
) – User object containing relevant information to the USERSTATE.
- coroutine fetch_channel(broadcaster: str, token: Optional[str] = None)#
This function is a coroutine.
Retrieve channel information from the API.
Note
This will be deprecated in 3.0. It’s recommended to use
fetch_channels()
instead.- Parameters
- Returns
- coroutine fetch_channels(broadcaster_ids: List[int], token: Optional[str] = None)#
This function is a coroutine.
Retrieve information for up to 100 channels from the API.
- Parameters
- Returns
List[
twitchio.ChannelInfo
]
- coroutine fetch_chatters_colors(user_ids: List[int], token: Optional[str] = None)#
This function is a coroutine.
Fetches the color of a chatter.
- Parameters
- Returns
List[
twitchio.ChatterColor
]
- coroutine fetch_cheermotes(user_id: Optional[int] = None)#
This function is a coroutine.
Fetches cheermotes from the twitch API
- Parameters
user_id (Optional[
int
]) – The channel id to fetch from.- Returns
List[
twitchio.CheerEmote
]
- coroutine fetch_clips(ids: List[str])#
This function is a coroutine.
Fetches clips by clip id. To fetch clips by user id, use
twitchio.PartialUser.fetch_clips()
- Parameters
ids (List[
str
]) – A list of clip ids- Returns
List[
twitchio.Clip
]
- coroutine fetch_games(ids: Optional[List[int]] = None, names: Optional[List[str]] = None, igdb_ids: Optional[List[int]] = None) List[Game] #
This function is a coroutine.
Fetches games by id or name. At least one id or name must be provided
- Parameters
- Returns
List[
twitchio.Game
]
- coroutine fetch_global_chat_badges()#
This function is a coroutine.
Fetches Twitch’s list of chat badges, which users may use in any channel’s chat room.
Returns: List[
twitchio.ChatBadge
]
- coroutine fetch_global_emotes()#
This function is a coroutine.
Fetches global emotes from the twitch API
- Returns
List[
twitchio.GlobalEmote
]
- coroutine fetch_streams(user_ids: Optional[List[int]] = None, game_ids: Optional[List[int]] = None, user_logins: Optional[List[str]] = None, languages: Optional[List[str]] = None, token: Optional[str] = None, type: typing_extensions.Literal[all, live] = 'all')#
This function is a coroutine.
Fetches live streams from the helix API
- Parameters
user_ids (Optional[List[
int
]]) – user ids of people whose streams to fetchgame_ids (Optional[List[
int
]]) – game ids of streams to fetchuser_logins (Optional[List[
str
]]) – user login names of people whose streams to fetchlanguages (Optional[List[
str
]]) – language for the stream(s). ISO 639-1 or two letter code for supported stream languagetoken (Optional[
str
]) – An optional OAuth token to use instead of the bot OAuth tokentype (Literal["all", "live"]) – One of
"all"
or"live"
. Defaults to"all"
. Specifies what type of stream to fetch.
- Returns
List[
twitchio.Stream
]
- coroutine fetch_tags(ids: Optional[List[str]] = None)#
This function is a coroutine.
Fetches stream tags.
- Parameters
ids (Optional[List[
str
]]) – The ids of the tags to fetch- Returns
List[
twitchio.Tag
]
- coroutine fetch_teams(team_name: Optional[str] = None, team_id: Optional[str] = None)#
This function is a coroutine.
Fetches information for a specific Twitch Team.
- Parameters
- Returns
List[
twitchio.Team
]
- coroutine fetch_top_games() List[Game] #
This function is a coroutine.
Fetches the top games from the api
- Returns
List[
twitchio.Game
]
- coroutine fetch_users(names: Optional[List[str]] = None, ids: Optional[List[int]] = None, token: Optional[str] = None, force=False) List[User] #
This function is a coroutine.
Fetches users from the helix API
- Parameters
- Returns
List[
twitchio.User
]
- coroutine fetch_videos(ids: Optional[List[int]] = None, game_id: Optional[int] = None, user_id: Optional[int] = None, period=None, sort=None, type=None, language=None)#
This function is a coroutine.
Fetches videos by id, game id, or user id
- Parameters
ids (Optional[List[
int
]]) – A list of video idsgame_id (Optional[
int
]) – A game to fetch videos fromuser_id (Optional[
int
]) – A user to fetch videos from. Seetwitchio.PartialUser.fetch_videos()
period (Optional[
str
]) – The period for which to fetch videos. Valid values are all, day, week, month. Defaults to all. Cannot be used when video id(s) are passedsort (
str
) – Sort orders of the videos. Valid values are time, trending, views, Defaults to time. Cannot be used when video id(s) are passedtype (Optional[
str
]) – Type of the videos to fetch. Valid values are upload, archive, highlight. Defaults to all. Cannot be used when video id(s) are passedlanguage (Optional[
str
]) – Language of the videos to fetch. Must be an ISO-639-1 two letter code. Cannot be used when video id(s) are passed
- Returns
List[
twitchio.Video
]
- classmethod from_client_credentials(client_id: str, client_secret: str, *, loop: Optional[AbstractEventLoop] = None, heartbeat: Optional[float] = 30.0, prefix: Union[str, list, tuple, set, Callable, Coroutine] = '!') Bot #
creates a client application token from your client credentials.
- Parameters
client_id (
str
) – Your application’s Client ID.client_secret (
str
) – An application Client Secret used to generate Access Tokens automatically.loop (Optional[
asyncio.AbstractEventLoop
]) – The event loop the client will use to run.heartbeat (Optional[
float
]) – The heartbeat interval. Defaults to 30.prefix (Union[
str
,list
,tuple
,set
, Callable, Coroutine]) – The bots prefix. Defaults to “!”.
- Returns
A new
Bot
instance
- get_cog(name: str) Optional[Cog] #
Retrieve a Cog from the bots loaded Cogs.
Could be None if the Cog was not found.
- Returns
Optional[
Cog
]
- coroutine get_context(message, *, cls=None)#
Get a Context object from a message.
- Parameters
message (
Message
) – The message object to get context for.cls – The class to return. Defaults to Context. Its constructor must take message, prefix, valid, and bot as arguments.
- Returns
An instance of cls.
- Raises
.CommandNotFound –
- coroutine get_webhook_subscriptions()#
This function is a coroutine.
Fetches your current webhook subscriptions. Requires your bot to be logged in with an app access token.
- Returns
- coroutine global_after_invoke(ctx: Context) None #
This function is a coroutine.
Method which is called after any command is invoked regardless if it failed or not.
This method is useful for cleaning up things after command invocation. E.g Database connections.
- Parameters
ctx – The context used for command invocation.
Note
The global_after_invoke is called only after the command successfully invokes.
- coroutine global_before_invoke(ctx)#
This function is a coroutine.
Method which is called before any command is about to be invoked.
This method is useful for setting up things before command invocation. E.g Database connections or retrieving tokens for use in the command.
- Parameters
ctx – The context used for command invocation.
Examples
async def global_before_invoke(self, ctx): # Make a database query for example to retrieve a specific token. token = db_query() ctx.token = token async def my_command(self, ctx): data = await self.create_clip(ctx.token, ...)
Note
The global_before_invoke is called before any other command specific hooks.
- coroutine handle_commands(message)#
This function is a coroutine.
This method handles commands sent from chat and invokes them.
By default, this coroutine is called within the
Bot.event_message()
event. If you choose to overrideBot.event_message()
then you need to invoke this coroutine in order to handle commands.- Parameters
message (
Message
) – The message object to get content of and context for.
- coroutine join_channels(channels: Union[List[str], Tuple[str]])#
This function is a coroutine.
Join the specified channels.
- load_module(name: str) None #
Method which loads a module and it’s cogs.
- Parameters
name (str) – The name of the module to load in dot.path format.
- coroutine part_channels(channels: Union[List[str], Tuple[str]])#
This function is a coroutine.
Part the specified channels.
- reload_module(name: str)#
Method which reloads a module and it’s cogs.
- Parameters
name (str) – The name of the module to unload in dot.path format.
Note
This is roughly equivalent to bot.unload_module(…) then bot.load_module(…).
- remove_cog(cog_name: str)#
Method which removes a cog from the bot. :param cog_name: The name of the cog to remove. :type cog_name: str
- remove_command(name: str)#
Method which removes a registered command
- Parameters
name (
str
) – the name or alias of the command to delete.- Returns
None
- Raises
.CommandNotFound –
- run()#
A blocking function that starts the asyncio event loop, connects to the twitch IRC server, and cleans up when done.
- coroutine search_categories(query: str)#
This function is a coroutine.
Searches twitches categories
- Parameters
query (
str
) – The query to search for- Returns
List[
twitchio.Game
]
- coroutine search_channels(query: str, *, live_only=False)#
This function is a coroutine.
Searches channels for the given query
- Parameters
- Returns
List[
twitchio.SearchUser
]
- coroutine start()#
This function is a coroutine.
Connects to the twitch IRC server, and cleanly disconnects when done.
- unload_module(name: str) None #
Method which unloads a module and it’s cogs.
- Parameters
name (str) – The name of the module to unload in dot.path format.
- coroutine update_chatter_color(token: str, user_id: int, color: str)#
This function is a coroutine.
Updates the color of the specified user in the specified channel/broadcaster’s chat.
- Parameters
token (
str
) – An oauth token with theuser:manage:chat_color
scope.user_id (
int
) – The ID of the user whose color is being updated, this must match the user ID in the token.color (
str
) – Turbo and Prime users may specify a named color or a Hex color code like #9146FF. Please see the Twitch documentation for more information.
- Returns
None
- coroutine wait_for(event: str, predicate: ~typing.Callable[[], bool] = <function Client.<lambda>>, *, timeout=60.0) Tuple[Any] #
This function is a coroutine.
Waits for an event to be dispatched, then returns the events data
- Parameters
event (
str
) – The event to wait for. Do not include the event_ prefixpredicate (Callable[[...], bool]) – A check that is fired when the desired event is dispatched. if the check returns false, the waiting will continue until the timeout.
timeout (
int
) – How long to wait before timing out and raising an error.
- Returns
The arguments passed to the event.
- wait_for_ready() Coroutine[Any, Any, bool] #
This function is a coroutine.
Waits for the underlying connection to finish startup
- Returns
bool
The state of the underlying flag. This will always beTrue
- property commands#
The currently loaded commands.
- property events#
A mapping of events name to coroutine.
- property nick#
The IRC bots nick.
- property user_id#
The IRC bot user id.
Context#
- class twitchio.ext.commands.Context(message: Message, bot: Bot, **attrs)#
A class that represents the context in which a command is being invoked under.
This class contains the meta data to help you understand more about the invocation context. This class is not created manually and is instead passed around to commands as the first parameter.
- author#
The Chatter object of the user in chat that invoked the command.
- Type
Union[
PartialChatter
,Chatter
]
- args#
List of arguments that were passed to the command.
- Type
Optional[List[
Any
]]
- view#
StringParser object that breaks down the command string received.
- Type
Optional[
StringParser
]
- get_user(name: str) Optional[Union[PartialUser, User]] #
Retrieve a user from the channels user cache.
- Parameters
name (str) – The user’s name to try and retrieve.
- Returns
Union[
twitchio.user.User
,twitchio.user.PartialUser
] – Could be atwitchio.user.PartialUser
depending on how the user joined the channel. Returns None if no user was found.
- coroutine reply(content: str)#
This function is a coroutine.
Send a message in reply to the user who sent a message in the destination associated with the dataclass.
Destination will be the context of which the message/command was sent.
- Parameters
content (str) – The content you wish to send as a message. The content must be a string.
- Raises
InvalidContent – Invalid content.
- coroutine send(content: str)#
This function is a coroutine.
Send a message to the destination associated with the dataclass.
Destination will either be a channel or user.
- Parameters
content (str) – The content you wish to send as a message. The content must be a string.
- Raises
InvalidContent – Invalid content.
Command#
Cog#
- clsCog.event
- asynccog_check
- asynccog_command_error
- class twitchio.ext.commands.Cog#
Class used for creating a TwitchIO Cog.
Cogs help organise code and provide powerful features for creating bots. Cogs can contain commands, events and special cog specific methods to help with checks, before and after command invocation hooks, and cog error handlers.
To use a cog simply subclass Cog and add it. Once added, cogs can be un-added and re-added live.
Examples
# In modules/test.py from twitchio.ext import commands class MyCog(commands.Cog): def __init__(self, bot: commands.Bot): self.bot = bot @commands.command() async def hello(self, ctx: commands.Context): await ctx.send(f"Hello, {ctx.author.name}!") @commands.Cog.event() async def event_message(self, message): # An event inside a cog! if message.echo: return print(message.content) def prepare(bot: commands.Bot): # Load our cog with this module... bot.add_cog(MyCog(bot))
- coroutine cog_check(ctx: Context) bool #
A cog-wide check which is ran everytime a command from this Cog is invoked.
- Parameters
ctx (
Context
) – The context used to try and invoke this command.
Notes
Note
This method must return True/False or raise. If this check returns False or raises, it will fail and an exception will be propagated to error handlers.
- coroutine cog_command_error(ctx: Context, exception: Exception) None #
Method invoked when an error is raised in one of this cogs commands.
- classmethod event(event: Optional[str] = None) Callable[[function], CogEvent] #
Add an event listener to this Cog.
Examples
class MyCog(commands.Cog): def __init__(...): ... @commands.Cog.event() async def event_message(self, message: twitchio.Message): print(message.content) @commands.Cog.event("event_ready") async def bot_is_ready(self): print('Bot is ready!')
Cooldowns#
- class twitchio.ext.commands.Bucket(value)#
Enum values for the different cooldown buckets.
- Parameters
default (
enum.Enum
) – The default bucket.channel (
enum.Enum
) – Cooldown is shared amongst all chatters per channel.member (
enum.Enum
) – Cooldown operates on a per channel basis per user.user (
enum.Enum
) – Cooldown operates on a user basis across all channels.subscriber (
enum.Enum
) – Cooldown for subscribers.mod (
enum.Enum
) – Cooldown for mods.
- class twitchio.ext.commands.Cooldown(rate: int, per: float, bucket: Bucket)#
Cooldown decorator values.
- Parameters
Examples
# Restrict a command to once every 10 seconds on a per channel basis. @commands.cooldown(rate=1, per=10, bucket=commands.Bucket.channel) @commands.command() async def my_command(self, ctx: commands.Context): pass # Restrict a command to once every 30 seconds for each individual channel a user is in. @commands.cooldown(rate=1, per=30, bucket=commands.Bucket.member) @commands.command() async def my_command(self, ctx: commands.Context): pass # Restrict a command to 5 times every 60 seconds globally for a user. @commands.cooldown(rate=5, per=60, bucket=commands.Bucket.user) @commands.command() async def my_command(self, ctx: commands.Context): pass